[RFC] Build systems improvements

[torfmaster]

Update Summer 2023

Some progress is underway to update the build system since this issue was originally opened.

Status: we still use cargo + make and probably will continue to.

New requirements

In addition to what was originally mentioned, we want:

• Nicely support out-of-tree apps. This shouldn't require duplicating a lot of build machinery.
• Support multiple fixed address apps on the same board.

TODO

• Consolidate the per-board makefile rules and use target directories (Specify per-platform target directories for cargo run invocations. #490)
• Add make target to build for multiple flash/ram locations (Make: add make tab as an approach to build for multiple locations #482)
• Support an out-of-tree libtock-rs app with an example
• Support building a board-specific TAB file with many suitable flash/ram addresses for a particular board.
  • Need some way for make to know how many times to invoke cargo to build for different ram/flash locations.

Original RFC

Background

In order to split out the discussion about the build system of libtock-rs from the PR #161 this issue was created.

To organize this discussion I want to collect the requirements for a build system in this issue.

Current status

Currently building and flashing is done using cargo, Rust's build system and dependency manager. This is considered partially unsatisfying. Currently, the command line needed for compiling and flashing the nrf52 board is

PLATFORM=nrf52 cargo rthumbv7em blink

Running the (unit) tests works via:

cargo test --workspace

However, some use cases are more difficult to tackle and require additional effort. One example is running integration tests, where currently an external test runner is used: #158

Requirements

A (non-comprehensive) list of requirements is

• the build system should do the dependency management (download dependencies from crates.io)
• it should build incrementally and react on changes of the environment (layout files, environment variables, code)
• it should be able to flash most boards (using external tools like tockloader)
• it should work on the most popular platforms (linux, mac OS X)

Moreover, there should be one and only one build system (not a combinations).

Alternatives to cargo

• Makefiles (automake, gmake)
• cmake
• gradle

From this list I only know gradle well enough to judge whether it can fulfill our requirements.

[bradjc]

Improvement suggestions:

1. The make setup step should be removed. The build system should know when this needs to be run, not users.
2. .cargo/config should be removed. Critical build infrastructure should not be intentionally obscured by putting it in hidden files.
3. elf2tab should be moved out of flash.sh, since that is a build step, and not related to flashing code.

Additional thoughts:

1. I think the focus on user-specifying hardware platforms should be significantly lessened. In particular, things should be built for all platforms every time into a TAB, and tools can then use the TAB and pick the correct binary. For flashing purposes specifying a board is reasonable (although we should work towards removing that need as well...but that is a separate issue). Ideally users shouldn't have to know what hardware they have, just as with the OS/app separation in other computing platforms.

[ppannuto]

Moreover, there should be one and only one build system (not a combinations).

I disagree with this. These two tools solve different problems, and each tools should solve the problem it is good at. Cargo is very good at building & testing rust code. Make is good at executing arbitrary recipes, encapsulating arbitrary configuration complexity, and acting as a job runner (these jobs can include building sources, but they do not need to, and there is no reason to re-write the rules that cargo already knows in make).

---

I also agree with everything @bradjc suggested [especially (2), so much (2). Hidden files that drive configuration are the worst, most evil, awful, cruel, anti-feature ever crafted by humanity].

[torfmaster]

.cargo/config should be removed. Critical build infrastructure should not be intentionally obscured by putting it in hidden files.

After the long discussions about the build system I think that the current compromise looks as follows:

• there are the Makefiles for the people coming to tock from embedded world/C world
• there are the cargo aliases for people coming from the Rust world (\setminus{embedded})

The effect of this is that we have convenient solutions for these large groups and I lean towards keeping this (I think it is impossible to convince Rust users to use Makefiles, likewise it is impossible to convince someone using Makefiles for years to stop doing this).
I - belonging to the latter group - simply ignore the fact that there are Makefiles and just use cargo directly and I am very happy with that. I am very used to having configurations files in dot-directories (.vscode, .cargo, .git, ...).

[alistair23]

1. The `make setup` step should be removed. The build system should know when this needs to be run, not users.

I would be very upset if a Makefile made permanent changes to my system without asking or telling me. The make setup is there for people like me :)

2\. `.cargo/config` should be removed. Critical build infrastructure should not be intentionally obscured by putting it in hidden files.

Makes sense, this has confused me a few times.

3\. `elf2tab` should be moved out of flash.sh, since that is a build step, and not related to flashing code.

Agreed. That is a good idea.

1. In particular, things should be built for all platforms every time into a TAB, and tools can then use the TAB and pick the correct binary.

This is slow though. It wastes time building everything, when I only want one thing. Maybe the default make can do that and more advanced users can specify what they want.

[jrvanwhy]

Could we address the concerns about .cargo/config's visibility by using symlinks? E.g. we could put the config in cargo-config and symlink .cargo/config to cargo-config.

I would be very upset if a Makefile made permanent changes to my system without asking or telling me. The make setup is there for people like me :)

+1, I tried sandboxing Tock's build system in tock-on-titan but doing so is very difficult (poor sandboxing tools in GNU/Linux...).

[alistair23]

I'm not sure if symlinks are any clearer, it's just another level of indirection.

[torfmaster]

What about inlining everything (--target, deny warnings, ...) inside the Makefiles and keeping (+documenting) the config for everyone who wants to use cargo instead of Makefiles. Another option would be to gitignore the cargo config and putting it to a folder so everyone can opt-in in a Makefile-free build system, if desired.

[gentooza]

Hi,

I think it's related with Tock System as a whole (not only Libtock-rs) but, Why not implement it's development system as a framework tool?

I explain, look for example ionic, or expo.dev, two frameworks for mobile phone hybrid app development.

We could use only single executable, and it can prepare your dependencies, install components, choose versions, environments, flash, etc.

As I Imagine (python):

$ virtualenv .env
$ source .env/bin/activate
$(.env) pip install tockdev
$(.env) tockdev start
*First launch, install/checking dependencies*
Choose Tock Kernel version:
(1) 1.0
(2) 2.0
(3) unstable
Choose your board:
(1) esp32
(2) smt..
(3) qemu
Choose programming language:
(1) C
(2) Rust
[...]
$(.env) tockdev build
*building app*
$(.env) tockdev flash (kernel) (bootloader) (all)
*checking board*
*has kernel?* flash kernel
*flash bootloader?* flash bootloader
*flashing app*
[...]

Everything based in Makefiles, cargo, .toml, etc. But centralized
I like this approach, and I hope to have explained it well :-D

cheers, and cool project!