The Toolbelt has been around for a pretty long time but we have not been that good at promoting it and documentation is unfortunately a bit sparse. In this blog post we will talk a bit about the Toolbelt and how to use it.
The basic idea behind the Toolbelt is to provide an easy to access tool that helps the user to do common tasks in Bitcraze projects, without installing a lot of special tool-chains, libs or programs. The intention is also to harmonize the use in all our projects to make them as similar as possible and reduce the cognitive load when switching between repositories.
A functional view
After a standard installation (see below), the Toolbelt is available using the tb command and it is intended to be executed from the root of (almost) any Bitcraze repository file tree. You can run tools (commands) from the toolbelt with the extra spice that they run in the required environment, for instance when building the firmware the correct compiler is automatically available.
Without any arguments the Toolbelt will display a brief help. For instance if I run it in the root of the crazyflie-firmware repository I get this:
kristoffer@kristoffer-XPS-13-9310:~/code/bitcraze/crazyflie-firmware$ tb
Usage: tb [-d] tool [arguments]
The toolbelt is used to develop, test and build Bitcraze modules. When the toolbelt is called, it will first try to find the tool in the belt, after that it will try the tools in the module if the working directory is the root of a module. Module tools are executed in the context of a docker container based on the module requirements configured in the module.json config file.
-d: print the docker call that executes the tool
Tools in the belt:
help, -h, --help - Help
update - Update tool belt to latest version
version, -V, --version - Display version of the tool belt
ghrn - Generate release notes from github milestone
docs - Serve docs locally
Tools in the current module:
build
test
compile
check_elf
make
test_python
clean
build-docs
Code language: JavaScript (javascript)We can see that there are two groups of tools; “Tools in the belt” that are available in all repositories and ” Tools in the current module”, these are tools that are specific to the current repository.
To run a tool, simply use tb and the command. To build the firmware for instance, you can use make
kristoffer@kristoffer-XPS-13-9310:~/code/bitcraze/crazyflie-firmware$ tb make
Running script tools/build/make in a container based on the bitcraze/builder docker image as uid 1000
Using default tag: latest
latest: Pulling from bitcraze/builder
Digest: sha256:bee591d94db757465b88338c69be847cdf527698f0270ea1a86a2ccaa3c9845d
Status: Image is up to date for bitcraze/builder:latest
docker.io/bitcraze/builder:latest
make: Entering directory '/module'
CLEAN_VERSION
CC stm32f4xx_dma.o
CC stm32f4xx_exti.o
CC stm32f4xx_flash.o
CC stm32f4xx_gpio.o
...Code language: JavaScript (javascript)We can see that the firmware is built but we did not have to set our environment beforehand like instructed in the build/install page. The Toolbelt handled that by providing an precompiled development environment to do the firmware-compiling for us.
I will not go through all the tools but I’d like to mention the docs command. The docs command starts a web server and renders a simplified version of the documentation for a repository (in the docs directory). It is useful when browsing or editing the documentation.
Implementation
The Toolbelt is based on Docker and it runs in container. When executing a tool, the Toolbelt starts a second container where the tool runs. This second container is called a builder and it contains all the software required to execute the tool. There are a few different builders with tool-chains that are appropriate for various languages, CPUs and so on, luckily the Toolbelt picks the correct one automatically.
The directory that the tool is executed from is mapped into the docker containers and this is how the tools access the files, for instance when compiling.
In the example above we can see that the Toolbelt is pulling the latest version of the bitcraze/builder image from docker hub to have the latest and greatest builder when running make. It will take a while to download the builder image the first time (or when it has been updated) but usually this is not necessary and usually starting a tool takes only around 1 second.
The builder images are also used by our build servers for CI and release builds, this means that building with the Toolbelt replicates the exact same environment as on our builder servers.
The tools that are specific to a repository can be found in the tools/build and tools/build-docs directories. They are usually bash or python scripts and often they can also be executed without the toolbelt if you have the appropriate software installed on your system.
The source code for the Toolbelt is available on github. You can also find the source code for the builders on github, search for “builder”
Installation
The Toolbelt is mainly designed for Linux like environments and works on MacOS and in WSL (Windows Subsystem for Linux). Some operations are slowish on Mac as file access is a bit slower from docker containers.
To run the Toolbelt you need to have Docker installed on your system, after that installation is as simple as adding an alias to your .bashrc (or similar). For instructions run:
docker run --rm -it bitcraze/toolbeltNative installation VS Toolbelt VS Virtual machine
There are three paths for building and working with Bitcraze source code; native install, the Toolbelt and the VM (Virtual machine). They all have their pros and cons.
Native installation
All build tools installed on the machine.
Pros: fast, access to USB and Crazyradio which enables flashing of firmware, can use your standard development environment
Cons: Possible compatibility issues with other software on the system. Must maintain installation and upgrade from time to time.
Toolbelt
Pros: highly separated from the OS, automatically updated with the appropriate tools and versions
Cons: can not access USB and the Crazyradio – flashing not possible. No access to GUIs – can not run the client
VM
Pros: Everything ready in one place, also supports USB, Crazyradio and flashing. Client works. Highly separated from the OS.
Cons: A bit bulky
Conclusions
The Toolbelt is an option for users that are interested in working with the source code for the Bitcraze ecosystem, but do not want to put too much time into installing tool-chains and setting up environments. It does not solve all problems but hopefully simplifies some tasks.
Any feedback is welcome!