[bug#61765] custom toolchain blog post

["Ludovic Courtès" <ludo@gnu.org>]

Hello Mitchell,

Mitchell Schmeisser <mitchellschmeisser@librem.one> skribis:

> Here is a rough draft of my toolchain post.
> I hope it can make an interesting contribution to the Guix literature.

Yay, definitely!

>>From 4f6c43091ffd67cdbc5f041e496f61bc8a06070e Mon Sep 17 00:00:00 2001
> From: Mitchell Schmeisser <mitchellschmeisser@librem.one>
> Date: Fri, 24 Feb 2023 13:02:05 -0500
> Subject: [PATCH] website: Add custom toolchain blog post
>
> * website/posts/custom-toolchains-with-guix.md: New file.

This looks great to me!  It’s useful insight for anyone who might want
to add a cross-compilation target to Guix or simply learn how this is
implemented.

> +++ b/website/posts/custom-toolchains-with-guix.md
> @@ -0,0 +1,557 @@
> +# Table of Contents
> +
> +1.  [Overview](#org2633a51)
> +2.  [Anatomy of a toolchain](#orgc440e9e)
> +3.  [Bootstrapping a Toolchain](#orgd42b6c3)
> +4.  [Defining the Packages](#org55042c5)
> +	1.  [Binutils](#org67da1ec)
> +	2.  [GCC sans libc](#org82d6f83)
> +	3.  [Newlib(-nano)](#orgf6bafbc)
> +	4.  [Complete toolchain](#org052f2a2)
> +5.  [Integrating with Zephyr Build System](#orgc3f87f4)
> +	1.  [Testing](#org9f3c314)
> +
> +All code is available at [guix-zephyr](https://github.com/paperclip4465/guix-zephyr) channel.
> +
> +
> +<a id="org2633a51"></a>

You can remove the table of contents and all the HTML snippets that
pandoc added—I don’t think that works as expected with Haunt/CommonMark.

> +# Overview

You can drop the heading.

> +In order to deploy embedded software using Guix we first need to teach Guix
> +how to build it. Since Guix bootstraps everything this means we must teach Guix
> +how to build our toolchain.
> +
> +The [Zephyr Project](https://zephyrproject.org) uses its own fork of GCC with custom configs for
> +the architectures supported by the project.

We want blog posts to be widely accessible so I would recommend
providing more context in the intro.  In particular, I’d suggest:

  1. Mentioning that Guix supports cross-compilation (not everyone is
     aware of that), with a link to
     <https://guix.gnu.org/en/manual/en/html_node/Cross_002dCompilation.html>.

  2. Adding a couple of sentences saying what Zephyr is (I didn’t know
     about it before :-)).

  3. Saying a few words as to why Zephyr uses a GCC fork.

  4. Clearly stating that you added support for cross-compilation to
     Zephyr with Guix in a channel, linking to said channel, and that
     this is what the remainder of the post will describe.

You can check out posts at <https://guix.gnu.org/blog> for inspiration.

> +# Anatomy of a toolchain
> +
> +Toolchains are responsible for taking high level descriptions of programs
> +and lowering them down to a series of equivalent machine instructions.
> +This process involves more than just a compiler. The compiler uses the `binutils`
> +to manipulate it's internal representation down to a given architecture.
> +It also needs the use of the C standard library as well as a few other libraries
> +needed for some compiler optimizations.
> +
> +The C library provides the interface to the underlying kernel. System calls like `write`
> +and `read` are provided by `Glibc` on most Linux distributions.
>
> +In embedded systems smaller implementations like `newlib` and `newlib-nano` are used.

I’d suggest not using fixed-width font (backquotes) for proper nouns;
you can write “glibc” or “the GNU C Library (glibc)”, “Binutils” or “the
GNU Binary Utilities (Binutils)”, etc.

> +First thing we need to build is the `arm-zephyr-eabi` binutils.
> +This is very easy in Guix.
> +
> +	(define-module (zephyr packages zephyr)
> +	  #:use-module (guix packages))
> +
> +	(define-public arm-zephyr-eabi-binutils
> +	  (let ((xbinutils (cross-binutils "arm-zephyr-eabi")))
> +		(package
> +		  (inherit xbinutils)
> +		  (name "arm-zephyr-eabi-binutils")
> +		  (version "2.38")
> +		  (source
> +		   (origin (method git-fetch)
> +				   (uri (git-reference
> +						 (url "https://github.com/zephyrproject-rtos/binutils-gdb")
> +						 (commit "6a1be1a6a571957fea8b130e4ca2dcc65e753469")))
> +				   (file-name (git-file-name name version))
> +				   (sha256 (base32 "0ylnl48jj5jk3jrmvfx5zf8byvwg7g7my7jwwyqw3a95qcyh0isr"))))
> +		  (arguments
> +		   `(#:tests? #f
> +			 ,@(substitute-keyword-arguments (package-arguments xbinutils)
> +				 ((#:configure-flags flags)
> +				  `(cons "--program-prefix=arm-zephyr-eabi-" ,flags)))))
> +		  (native-inputs
> +		   (append
> +			(list texinfo
> +				  bison
> +				  flex
> +				  gmp
> +				  dejagnu)
> +			(package-native-inputs xbinutils)))
> +		  (home-page "https://zephyrproject.org")
> +		  (synopsis "binutils for zephyr RTOS"))))

Code snippets should be written like this, without leading indentation:

  ```scheme
  (define …)
  ```

This will enable syntax highlighting.

> +We can test our package definition using the `-L` flag with `guix build`
> +to add our packages.
> +
> +	guix build -L guix-zephyr zephyr-binutils
> +
> +	/gnu/store/...-zephyr-binutils-2.38

Likewise:

  ```
  guix build foo
  ```

> +# Integrating with Zephyr Build System
> +
> +Zephyr uses CMake as it's build system. It contains numerous CMake

s/it's/its/

One thing that’s not clear to me: with this in place, can you do “guix
build --target=arm-zephyr-eabi hello”, for instance?  If not, what’s
missing to support it?

It would be great if you could finish with a short conclusion stating,
for instance, the key takeaway message, lessons learned, and/or your
thoughts on how this could benefit others in the broader community.

I wonder if it would be worth mentioning
<https://guix.gnu.org/manual/en/html_node/Platforms.html> too, and how
one would go about adding a  module.  WDYT?

Could you send an updated patch?

Thanks for contributing this article!

Ludo’.