[bug#61765] custom toolchain blog post

[Mitchell Schmeisser]

Hello Ludo,

Thank you for your feedback!

> 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?

You cannot. I do not know how to describe it in a succinct way but
suffice to say the applications need to know they are targeting Zephyr
when they are written. The application will include a `prj.conf` which
is analogous to a custom defconfig in the Linux kernel.
Either in this file, or somewhere in the CMakeLists.txt a `BOARD`
variable is set to specify a specific board definition.
These board definitions contain information about the architecture and
the CMake scripts themselves pick the toolchain.

It's not that it's impossible to implement something like `guix build
--target=arm-zephyr-eabi k64f-hello-world` but the k64f-hello-world
would be written in such a way that the target is implicit in the
package.

The way I envision the `--target/system` flags being used in this
context is `guix build --target=arm-linux-gnueabihf k64f-hello-world`
which will still produce the correct firmware but will allow the
firmware to be staged to another machine which will be responsible for
the final deployment over some transport.

> 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?

I considered trying to add Zephyr platforms but I'm not sure it's worth
the effort.
In addition to the patch to the website I attached another post(in org)
which describes how I integrated this toolchain into the Guix
infrastructure to allow defining firmware packages.
Maybe there will be additional information in there which can help you
understand where I'm going with all of this.

There will be a part 3 (and possibly more) about how to practically use
this stuff in a real project.

- Mitchell

0001-website-Add-toolchain-blog-post.patch
Description: patch

custom-build-systems-with-guix.org
Description: build-systems

Ludovic Courtès <ludo@gnu.org> writes:

> 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’.