Using CMake with FreeRTOS

You can use CMake to generate project build files from FreeRTOS application source code, and to build and run the source code.

You can also use an IDE to edit, debug, compile, flash, and run code on FreeRTOS-qualified devices. Each board-specific Getting Started guide includes instructions for setting up the IDE for a particular platform. If you prefer working without an IDE, you can use other third-party code editing and debugging tools for developing and debugging your code, and then use CMake to build and run the applications.

The following boards support CMake:

See the topics below for more information about using CMake with FreeRTOS.

Prerequisites

Make sure that your host machine meets the following prerequisites before continuing:

Developing FreeRTOS applications with third-party code editors and debugging tools

You can use a code editor and a debugging extension or a third-party debugging tool to develop applications for FreeRTOS.

If, for example, you use Visual Studio Code as your code editor, you can install the Cortex-Debug VS Code extension as a debugger. When you finish developing your application, you can invoke the CMake command-line tool to build your project from within VS Code. For more information about using CMake to build FreeRTOS applications, see Building FreeRTOS with CMake.

For debugging, you can provide a VS Code with debug configuration similar to the following:

"configurations": [
    {
        "name": "Cortex Debug",
        "cwd": "${workspaceRoot}",
        "executable": "./build/st/stm32l475_discovery/aws_demos.elf",
        "request": "launch",
        "type": "cortex-debug",
        "servertype": "stutil"
    }
]

Building FreeRTOS with CMake

CMake targets your host operating system as the target system by default. To use it for cross compiling, CMake requires a toolchain file, which specifies the compiler that you want to use. In FreeRTOS, we provide default toolchain files in freertos/tools/cmake/toolchains. The way to provide this file to CMake depends on whether you’re using the CMake command line interface or GUI. For more details, follow the Generating build files (CMake command-line tool) instructions below. For more information about cross-compiling in CMake, see CrossCompiling in the official CMake wiki.

Generating build files (CMake command-line tool)

You can use the CMake command-line tool (cmake) to generate build files for FreeRTOS. To generate the build files, you need to specify a target board, a compiler, and the location of the source code and build directory.

You can use the following options for cmake:

For example, if the vendor is Texas Instruments, and the board is the CC3220 Launchpad, and the compiler is GCC for ARM, you can issue the following command to build the source files from the current directory to a directory named build-directory:

cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory

cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory -G Ninja

cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory -G "MinGW Makefiles"

The regular expressions ${VENDOR}.* and ${BOARD}.* are used to search for a matching board, so you don't have to use the full names of the vendor and board for the VENDOR and BOARD options. Partial names work, provided there is a single match. For example, the following commands generate the same build files from the same source:

cmake -DVENDOR=ti -DCOMPILER=arm-ti -S . -B build-directory

cmake -DBOARD=cc3220 -DCOMPILER=arm-ti -S . -B build-directory

cmake -DVENDOR=t -DBOARD=cc -DCOMPILER=arm-ti -S . -B build-directory

You can use the CMAKE_TOOLCHAIN_FILE option if you want to use a toolchain file that is not located in the default directory cmake/toolchains. For example:

cmake -DBOARD=cc3220 -DCMAKE_TOOLCHAIN_FILE='/path/to/toolchain_file.cmake' -S . -B build-directory

If the toolchain file does not use absolute paths for your compiler, and you didn't add your compiler to the PATH environment variable, CMake might not be able to find it. To make sure that CMake finds your toolchain file, you can use the AFR_TOOLCHAIN_PATH option. This option searches the specified toolchain directory path and the toolchain's subfolder under bin. For example:

cmake -DBOARD=cc3220 -DCMAKE_TOOLCHAIN_FILE='/path/to/toolchain_file.cmake' -DAFR_TOOLCHAIN_PATH='/path/to/toolchain/' -S . -B build-directory

To enable debugging, set the CMAKE_BUILD_TYPE to debug. With this option enabled, CMake adds debug flags to the compile options, and builds FreeRTOS with debug symbols.

# Build with debug symbols
cmake -DBOARD=cc3220 -DCOMPILER=arm-ti -DCMAKE_BUILD_TYPE=debug -S . -B build-directory

You can also set the CMAKE_BUILD_TYPE to release to add optimization flags to the compile options.

Generating build files (CMake GUI)

You can use the CMake GUI to generate FreeRTOS build files.

Building FreeRTOS from generated build files

Building with native build system

You can build FreeRTOS with a native build system by calling the build system command from the output binaries directory.

For example, if your build file output directory is <build_dir>, and you are using Make as your native build system, run the following commands:

cd <build_dir>
make -j4

Building with CMake

You can also use the CMake command-line tool to build FreeRTOS. CMake provides an abstraction layer for calling native build systems. For example:

cmake --build build_dir

Here are some other common uses of the CMake command-line tool's build mode:

# Take advantage of CPU cores.
cmake --build build_dir --parallel 8

# Build specific targets.
cmake --build build_dir --target afr_kernel

# Clean first, then build.
cmake --build build_dir --clean-first

For more information about the CMake build mode, see the CMake documentation.