Configuring and building distortos v0.1.0 – v0.6.0

Note: This article applies only to distortos v0.1.0 – v0.6.0.

To configure and build distortos you need:

  • GNU Make build system;
  • (optionally) tup (version 0.7.3 or above) build system;
  • arm-none-eabi bleeding-edge-toolchain; alternatively you can try any other arm-none-eabi toolchain, but C++ exception handling code will increase the size of binary and incorrect newlib’s _reent struct configuration will dramatically increase RAM requirements (bleeding-edge-toolchain has the exceptions properly disabled and uses small variant of _reent struct – see here) – such combinations are not tested extensively;
  • POSIX-compatible shell (e.g. Bash);
  • GNU Coreutils or a set of compatible utilities;
  • kconfig-frontends (especially mconf tool) to create or edit the configurations;

Make sure the tools are available in your system’s PATH environment variable.

To create or edit a configuration run make menuconfig in the root of the project. You can either start from scratch or edit one of existing configurations (from configurations/<board>/<variant> folder). When creating a new configuration make sure the name of created file is

DO NOT edit files manually! kconfig-frontends tools make sure that multiple pre- and post-conditions are satisfied, and these conditions can easily be violated by manual modifications of the configuration.

To select the configuration of your choice execute make configure CONFIG_PATH=<>, where <> is the relative path to selected file. This will create file which is needed to build distortos. If <> is in the form configurations/<board>/<variant>, you can omit configurations/ prefix – make configure CONFIG_PATH=configurations/STM32F4DISCOVERY/test and make configure CONFIG_PATH=STM32F4DISCOVERY/test will both select the same configuration. You can execute make configure with no arguments if the selected file is in the main folder of the project – in that case . is used as CONFIG_PATH.

To build just execute make (if using GNU Make) or tup (if using tup) command in the main directory of the project. If you need to see verbose compilation log, execute make VERBOSE=1 (if using GNU Make) or tup --verbose (if using tup).

To remove all generated files (tup database, build outputs, doxygen outputs and file) you can run make distclean.

If you use tup and Linux

You need to set suid bit on your tup executable (sudo chmod +s `which tup`) and you need to make sure that fuse.conf (usually /etc/fuse.conf) has user_allow_other option enabled.

If you use tup and Windows

Don’t use 64-bit tools (even if you have 64-bit system), as tup cannot currently handle 64-bit executables.

Tools for Windows

You can get GNU Make, Bash and GNU Coreutils by installing MSYS2 and executing pacman -S make in the shell of this software distro – the binaries will be placed in <installation path>\usr\bin folder. kconfig-frontends binaries for Windows can be found in kconfig-frontends for Windows. tup and arm-none-eabi bleeding-edge-toolchain binaries for Windows are available from their main websites.