CMake Build System

Miosix 3 introduces a new build system, based on CMake. The CMake build system has the same capabilities of the old Miosix Makefiles, and in addition it allows better composability of Miosix with other external projects.

Creating a kernelspace project with CMake

If you are following the instructions from the Getting started guides, init_project_out_of_git_tree.pl script should have already created a CMakeLists.txt file for you. For a simple Miosix project without processes or external libraries, the script will look like this (after the copyright notice):

cmake_minimum_required(VERSION 3.21)

# Set the path to the Miosix kernel
set(MIOSIX_KPATH ${CMAKE_SOURCE_DIR}/../../miosix)
# Configure CMake toolchain and build type.
# This must to be done before the project() command
set(CMAKE_TOOLCHAIN_FILE ${MIOSIX_KPATH}/cmake/Toolchains/gcc.cmake)
set(CMAKE_BUILD_TYPE "Release")

project(Main C CXX ASM)

# Select the board (mandatory). See the options in miosix/arch/CMakeLists.txt
set(MIOSIX_BOARD stm32...)
# User config path and linker script selection are optional
# set(MIOSIX_USER_CONFIG_PATH ${CMAKE_SOURCE_DIR}/config)
# set(MIOSIX_LINKER_SCRIPT unikernel.ld)

# Include the Miosix kernel's project
add_subdirectory(${MIOSIX_KPATH} miosix EXCLUDE_FROM_ALL)

# Define a kernel level program
add_executable(main main.cpp)
# target_include_directories(main PRIVATE here_your_includes)
# target_compile_options(main PRIVATE here_your_compile_options)
# target_link_directories(main PRIVATE here_your_link_directories)
# target_link_libraries(main PRIVATE here_your_libraries)

# Link the main target with Miosix. When specifying PROGRAM_DEFAULT, the
# `program' target will be available to flash it (type `make program' to use it)
miosix_link_target(main PROGRAM_DEFAULT)

Initial configuration of CMake

The first line of the CMakeLists.txt sets the required version of CMake to 3.21. This enables features required by the Miosix CMake scripts; the version number cannot be lowered.

After this line, the script sets a few initial configuration variables that only take effect if set before the project() command is called.

Setting the path to the kernel and the toolchain file

The first thing the script does is to set a MIOSIX_KPATH variable to the absolute path of the Miosix kernel's directory. We recommend that this path (and all other paths in a CMake project) should remain absolute, for extra robustness of your scripts.

Note The variable MIOSIX_KPATH is not used by the Miosix kernel's CMake scripts, it is only a helper variable used by the default application script.

Then, the script sets CMAKE_TOOLCHAIN_FILE to the path of one of the toolchain scripts in Miosix's directory. This is required to force CMake to use an embedded toolchain. At the moment only the default gcc.cmake toolchain file is supported.

Setting the build type

The script sets the CMAKE_BUILD_TYPE to the default build type, Release. Change this line to set a different build type, or remove the line to allow setting the build type from the command line.

Tip The available build types in CMake (which also apply to Miosix) are Debug, Release and RelWithDebInfo and MinSizeRel. Miosix does not add custom build types.

Warning Variables in CMake are not all created equal. All variables assigned with set() outside of a function are local to the current directory scope and its children (a new directory scope is created by add_subdirectory). Global configuration options are instead called "cache" variables, and they are set using the CACHE option of the set() command.

Miosix declares a minimum CMake version of 3.21 in order to allow overriding "cache" variables with standard (non-CACHE) set() commands. We find this to be a significant simplification of the semantics of cache variables: it removes a lot of surprising behaviour for beginners, and makes CMake files more coincise. However, a cache variable overridden like this cannot be set from the command line anymore.

This is why the line which sets CMAKE_BUILD_TYPE must be removed to allow setting the build type from the command line.

See the CMake documentation for more information about this topic.

Creating the Miosix binary

The rest of the script imports the Miosix kernel as a subdirectory, and then create an executable that links with the Miosix kernel: your application. There are a few Miosix-specific variables and functions that are used to help with this task.

Setting the board

The target board for the application is chosen by setting the MIOSIX_BOARD variable to the name of the board. The board names are the same ones previously used for the Makefile-based build system, and some of the supported boards are documented here on the Wiki on the Board list page.

The Board list on the Wiki is not complete. There are several ways to see the full list of supported boards:

• Look at the contents of the miosix/arch/boards directory in the kernel's source tree. Each directory corresponds to a board, and the directory name is the same as the board name.
• Open the miosix/arch/CMakeLists.txt file. At the beginning of the file, the MIOSIX_BOARDS variable is set to the list of all supported boards.
• In your project's build directory, run cmake .. -DMIOSIX_PRINT_BOARD_LIST=ON.

The list of all supported boards is also printed if the board selected does not exist.

How to build Miosix with CMake

Building Miosix with CMake follows the standard workflow that you expect from any other CMake project. Change directory to the root of the Miosix application you want to build and execute the following commands:

mkdir build
cd build
cmake ..
make

These commands assume your CMake configuration uses Unix Makefiles as the default generator.

Configuration options

The Miosix CMake build system provides the following options, that can be set via the command line or by your application's CMakeLists.txt.

Variable	Explanation
MIOSIX_BOARD	Name of the board Miosix should be configured for. This variable has no default and must be set from the command line or from the application's CMake scripts.
MIOSIX_BOARD_VARIANT	Name of a board variant. A few boards define variants when there are jumpers, or different component fitting options, that are minor and do not warrant the definition of a different board. Default is the empty string, which is appropriate for most boards.
MIOSIX_LINKER_SCRIPT	The linker script to use when linking executables with Miosix using miosix_link_target(). The linker script choice also influences compiler options by adding/removing defines that are required for Miosix to work with that linker script. The standard linker script choices are: unikernel.ld Baseline unikernel configuration. Available for all boards. .text/.rodata in Flash, .data/.bss/heap in internal RAM. processes.ld Baseline fluid kernel configuration. .text/.rodata in Flash, .data/.bss/heap/process pool in internal RAM. unikernel-xram-heap.ld Unikernel configuration using external RAM only for the heap. .text/.rodata in Flash, .data/.bss in internal RAM, heap in external RAM. processes-xram.ld Fluid kernel configuration using external RAM only for the process pool. .text/.rodata in Flash, .data/.bss/heap in internal RAM, process pool in external RAM. unikernel-xram.ld Unikernel configuration using external RAM. .text/.rodata in Flash, .data/.bss/heap in external RAM. Internal RAM is used for a statically allocated IRQ stack (also used at boot before external RAM is enabled). processes-kernel-xram.ld Fluid kernel configuration using external RAM exclusively. .text/.rodata in Flash, .data/.bss/heap/process pool in external RAM. Internal RAM is used for a statically allocated IRQ stack (also used at boot before external RAM is enabled). unikernel-all-in-xram.ld Unikernel configuration for loading Miosix entirely into external RAM with a bootloader. All sections and the heap in external RAM. Some boards have additional linker scripts reserving parts of RAM for special purposes (i.e. Safeguard Memory, SGM).
MIOSIX_USER_CONFIG_PATH	Path to the config directory of your application. The default is ${CMAKE_SOURCE_DIR}/config. If this directory does not exist, the defaults will be picked up (as the default config is in the search path).
MIOSIX_USER_BOARD_SETTINGS_PATH	Path to the config directory of the selected board. The default is ${MIOSIX_USER_CONFIG_PATH}/board/${MIOSIX_BOARD}. If this directory does not exist, the defaults will be picked up (as the default config is in the search path).
MIOSIX_ASM_FLAGS MIOSIX_C_FLAGS MIOSIX_CXX_FLAGS MIOSIX_EXE_LINKER_FLAGS	Additional configuration flags that are passed to the compiler but are not necessary to build the kernel. You can customize these flags to change the warning level of compilers or linkers. Their use is not recommended.
MIOSIX_DISABLE_EXCEPTIONS	When set to ON, exceptions are disabled. Reduces code size. Default is OFF. Always use this flag instead of adding -fno-exceptions to C(XX)FLAGS, as it enables extra flags required by Miosix.
MIOSIX_ENABLE_LINKER_GC	Enables linker garbage collection (-ffunction-sections -fdata-sections). Default is ON (which is recommended for optimal code size).

Chip-defined internal variables

Each directory specific to a chip includes a CMakeLists.txt that defines a set of variables that describes that chip. This is the list of variables that these scripts need to define.

Variable	Explanation
MIOSIX_CPU_INC	Path of the directory with Miosix include files for the CPU in this chip. The source files associated with the correct CPU are included in the MIOSIX_CHIP_SRC variable.
MIOSIX_MULTILIB_PATH	Path of the GCC multilibs for this CPU. Use by clang/LLVM support, to be removed in the future.
MIOSIX_CPU_FLAGS	Compiler flags selecting the CPU. Passed to the C and C++ compilers, and to the assembler and the C++ compiler while linking too.
MIOSIX_CHIP_{C | CXX}_FLAGS	Additional flags for the chip. Usually includes a -D_CHIP_{CHIP_NAME} option to make Miosix aware of the chip choice.
MIOSIX_CHIP_SRC	List of chip and CPU specific files to be compiled with the Miosix kernel.