Configuring and building distortos

Starting with version 0.7.0, distortos uses CMake exclusively to generate its build description. You need following tools to configure and build distortos:

distortos follows CMake’s typical cross-compiling workflow, which means that you always have to use a so-called toolchain file. In distortos these files also serve another important purpose – they select the board which will be used by your application. Therefore the toolchain file for distortos is not architecture-specific – as you would expect – but board-specific.

  1. Download source code of distortos using one of following methods:
    • download latest release and extract it;
    • clone the repository with git clone https://github.com/DISTORTEC/distortos;
    • download current snapshot of the repository either in tar.gz or in zip format and extract it;
  2. Create a build folder, for example output, inside the source folder;
  3. From within the build folder, initialize it with CMake, for example with cmake .. -DCMAKE_TOOLCHAIN_FILE=../source/board/ST_STM32F4DISCOVERY/Toolchain-ST_STM32F4DISCOVERY.cmake -GNinja if you want a default configuration or cmake -C ../configurations/ST_STM32F4DISCOVERY/test/distortosConfiguration.cmake .. -GNinja if you want to start from a saved configuration;
  4. Edit distortos configuration either with cmake-gui .. (a GUI application) or with ccmake .. (curses-based application);
  5. Execute selected build tool, for example ninja (or ninja -v if you want to see all command lines while building);

tl;dr

$ wget https://github.com/DISTORTEC/distortos/archive/master.tar.gz
$ tar -xf master.tar.gz
$ cd distortos-master
$ mkdir output
$ cd output
$ cmake .. -DCMAKE_TOOLCHAIN_FILE=../source/board/ST_STM32F4DISCOVERY/Toolchain-ST_STM32F4DISCOVERY.cmake -GNinja
$ cmake-gui ..
$ ninja

or

$ wget https://github.com/DISTORTEC/distortos/archive/master.tar.gz
$ tar -xf master.tar.gz
$ cd distortos-master
$ mkdir output
$ cd output
$ cmake -C ../configurations/ST_STM32F4DISCOVERY/test/distortosConfiguration.cmake .. -GNinja
$ cmake-gui ..
$ ninja

Initializing directly with cmake-gui

Instead of initializing the build folder with command prompt, it is also possible to do it directly with CMake GUI (cmake-gui). After starting the application, make sure that it looks as on the right screenshot – both top text boxes should be empty. If they are not, just delete their contents.

Click on Browse Source… and navigate to the folder with distortos. Then click on Browse Build… and navigate to the folder where you want to build the project (you may need to create it, but in the browser there will be a button to do it).

When both folders are specified, press Configure. In the dialog which appears choose the generator – recommended one is Ninja – and make sure that Specify toolchain file for cross-compiling is selected. In the next step browse to the toolchain file, for example <distortos-path>/source/board/ST_STM32F4DISCOVERY/Toolchain-ST_STM32F4DISCOVERY.cmake, and click Finish to initialize the build folder.

In the middle of the window new project options will appear, while at the bottom you will see the status log of the process. You may now change whichever option you like. After you change a setting, new options may appear or existing ones may be removed, so it is advisable to click Configure after each change. New items initially have red background to highlight them. To see help message for any of the options, just hoover your mouse over it and wait for the tooltip to appear. After you are done editing the configuration, press Generate. If no errors are displayed in the status log (last line is Generating done) you can close the window.

Common CMake pitfall

When using saved configurations (distortosConfiguration.cmake) to initialize the build folder, CMake will NOT fail immediately if it cannot find this file. It will instead continue to initialize the build folder and fail near the end of the process, as no toolchain file was provided. If saved configuration would be found, it would specify the toolchain file and all other important settings.

$ cmake -C ../invalid/path/distortosConfiguration.cmake .. -GNinja
loading initial cache file ../invalid/path/distortosConfiguration.cmake
CMake Error: Error processing file: ../invalid/path/distortosConfiguration.cmake
-- The C compiler identification is GNU 8.3.0
-- The CXX compiler identification is GNU 8.3.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
CMake Error at CMakeLists.txt:19 (distortosSetConfiguration):
  Unknown CMake command "distortosSetConfiguration".


-- Configuring incomplete, errors occurred!
See also "/home/freddie/distortos/output/CMakeFiles/CMakeOutput.log".

Upon closer inspection, you will notice that instead of detecting an arm-none-eabi-gcc compiler, CMake found your system’s native compiler /usr/bin/cc. Even if you now provide correct path to the saved configuration, the process will not succeed, as at this stage CMake ignores this file.

$ cmake -C ../configurations/ST_STM32F4DISCOVERY/test/distortosConfiguration.cmake .. -GNinja
loading initial cache file ../configurations/ST_STM32F4DISCOVERY/test/distortosConfiguration.cmake
CMake Error at CMakeLists.txt:19 (distortosSetConfiguration):
  Unknown CMake command "distortosSetConfiguration".


-- Configuring incomplete, errors occurred!
See also "/home/freddie/distortos/output/CMakeFiles/CMakeOutput.log".

Such partially initialized build folder is broken beyond repair and cannot be fixed in any way. The only solution is to delete it and start from scratch.

$ cd ..
$ rm -rf output/
$ mkdir output
$ cd output/
$ cmake -C ../configurations/ST_STM32F4DISCOVERY/test/distortosConfiguration.cmake .. -GNinja
loading initial cache file ../configurations/ST_STM32F4DISCOVERY/test/distortosConfiguration.cmake
-- The C compiler identification is GNU 9.1.0
-- The CXX compiler identification is GNU 9.1.0
-- Check for working C compiler: /home/freddie/arm-none-eabi-gcc-9.1.0-190503/bin/arm-none-eabi-gcc
-- Check for working C compiler: /home/freddie/arm-none-eabi-gcc-9.1.0-190503/bin/arm-none-eabi-gcc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /home/freddie/arm-none-eabi-gcc-9.1.0-190503/bin/arm-none-eabi-g++
-- Check for working CXX compiler: /home/freddie/arm-none-eabi-gcc-9.1.0-190503/bin/arm-none-eabi-g++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Generating /home/freddie/distortos/output/include/distortos/distortosConfiguration.h
-- Generating /home/freddie/distortos/output/distortosConfiguration.cmake
-- Generating /home/freddie/distortos/output/ST_STM32F4DISCOVERY.preprocessed.ld
-- Generating /home/freddie/distortos/output/.gitignore
-- Configuring done
-- Generating done
-- Build files have been written to: /home/freddie/distortos/output

Leave a Reply

Your email address will not be published. Required fields are marked *