This repository contains the first version of a possible RTEMS CMake build support. The intention is to provide most CMake configuration to perform cross-compiling of RTEMS applications and provide a decent starting point for developers which would like to build their RTEMS application with CMake. The support has been written as generic as possible and only requires a few lines of code in the application CMakeLists.txt file and some necessary variables set to determine compiler information.

It is assumed that the RTEMS tools and the BSPs have already been built. If you are a beginner and this is not the case, it is recommended to have a look at this demo or the QuickStart to get started with RTEMS.

The usual way to set up a cross-compile project in CMake is to specify a CMake toolchain file. The CMake RTEMS support uses a combination of the supplied RTEMS BSP, RTEMS version, RTEMS prefix and the pkgconfig utility to set up the RTEMS environment properly so that application developers can focus on their application.

This is still a prototype. Simple applications have been tested, but no larger projects have been compiled with this build support yet. The compilation of simple applications was tested on Windows 10 and Ubuntu 20.04. Improvements, suggestions and pull requests are welcome :-)

Clone this repository. This does not necesarilly have to be in the application root path, but the RTEMS configuration path (the folder containing the *.cmake files) needs to be specified in this case.

git clone https://github.com/rmspacefish/rtems-cmake.git

If you want to add this repository to another repository, add it as a submodule instead

git submodule add https://github.com/rmspacefish/rtems-cmake.git

After that, it is recommended to set the path to the RTEMS CMake support with the following line in the application CMakeLists.txt

set(RTEMS_CONFIG_DIR
	"<Path to RTEMS CMake support folder>"
	 CACHE FILEPATH "Directory containing the RTEMS *.cmake files"
)

We need to prepare some internal environmental variables for the CMake toolchain file and we also need to process information like the supplied RTEMS_BSP and RTEMS_PREFIX for the PKG config utility. Add the following lines of code before the project call in your CMakeLists.txt to call rtems_pre_project_config and pass RTEMS_PREFIX and RTEMS_BSP into the function call.

include(${RTEMS_CONFIG_DIR}/RTEMSPreProjectConfig.cmake)
rtems_pre_project_config(${RTEMS_PREFIX} ${RTEMS_BSP})

Now the CMake environment is prepared for the toolchan file. We set the CMAKE_TOOLCHAIN_FILE to CMake can set up the compilers and required RTEMS flags properly in the project call:

Add the following lines of code before the project call:

set(CMAKE_TOOLCHAIN_FILE ${RTEMS_CONFIG_DIR}/RTEMSToolchain.cmake) 

Finally, you can add the following lines to call the post-project configuration, passing the target name into the function call

include("${RTEMS_CONFIG_DIR}/RTEMSPostProjectConfig.cmake")
rtems_post_project_config(${TARGET_NAME})

This is not mandatory yet, but is useful for additional debug information (if RTEMS_VERBOSE is set to TRUE) and might become useful in the future if some additional target specific properties need to be set for RTEMS.

It is recommended to either hardcode mandatory values like the prefix and BSP path in the application CMakeLists.txt (especially when using the CMake GUI) or to supply them via command line and write scripts to ease this process.

The RTEMS CMake build support can be configured either by passing configuration options prepended with -D to the build command or by setting these build variables in the application CMakeLists.txt before calling the build support. Following options are available

• RTEMS_VERSION: Can be specified manually. If this is not specified, the CMake build support will attempt to extract the version number from the RTEMS prefix (last letter of path). This variable needs to be valid for the RTEMS support to work!
• RTEMS_VERBOSE: Enable additional diagnostic output.
• RTEMS_TOOLS: Can be specified if the RTEMS tools folder. Can be different from the prefix but will be equal to the prefix for most users.
• RTEMS_PATH: Folder containing the RTEMS installation (BSPs). Can be different from the prefix but will be equal to the prefix for most users.

A small python script is provided in the build support to allow easier configuration of the CMake build systems when using RTEMS. Call cmake_build_config.py --help to get some information how to configure a build. Python 3 has to be installed to use this script.

It is possible to read the pkfconfig files now, so extending the manual build configuration might not be necessary in the future.

If this becomes necessary after all, follow these steps:

Extract the necessary compiler and linker flags for the RTEMS build from the pkgconfig file for the specific BSP. This file will generally be located inside the lib/pkgconfig folder of the RTEMS tools folder. Add these flags manually before the project file call (see RTEMSToolchain.cmake for examples) for your specific BSP.

See https://github.com/rmspacefish/rtems-demo/tree/master/applications/hello for an example. This is the Hello World project taken from the RTEMS quick start guide, but compiled using RTEMS. The repository also contains instructions on how to build the RTEMS tools if required and all specific steps to build with CMake and a blinky example for the STM32H743ZI-Nucleo board.