From About CMake:

CMake is an extensible, open-source system that manages the build process in an operating system and in a compiler-independent manner.

In other words, CMake does not build from the source directly, but generates the native build tool files (for example, a set of Makefiles or a build.ninja configuration). Which build tool to target is controlled via the -G argument, for example: -G Ninja, -G "Unix Makefiles" and many more. CMake can generate IDE project files for IDEs such as Eclipse as well. However, this guide only targets Ninja and GNU Make.

Important: All examples built by the CMake-generated build system do not include the SoftDevice as part of the generated HEX files. Therefore, the SoftDevice must already be present on the device before flashing the HEX file for the example mesh application.

Tip: There is a merge_<target> for each of the example targets that uses mergehex to generate a hexfile with the application and SoftDevice merged. Be aware that special care has to be taken with the order of programming when the application has bootloader support. Follow the DFU quick start guide in these cases. Example use:
build $ ninja merge_light_switch_server_nrf52832_xxAA_s132_6.0.0

Tip 2: There is also a flash_<target> for each of the example target that will run an interactive programming tool. This requires the nRFx Command Line tools and Python 3 to be installed. Example use:
build $ ninja flash_light_switch_server_nrf52832_xxAA_s132_6.0.0

Generating build files

Important: In this section, we are generating build files for the Ninja build tool. On Debian/Linux, you may drop the -G Ninja argument as the default generator is for Unix Makefiles and use the make command instead of ninja.

Good practice is to create a build folder in the root directory for the mesh stack repository, where all artifacts generated by the Ninja build system are stored, such as:

nrf5_sdk_for_mesh $ mkdir build
nrf5_sdk_for_mesh $ cd build

Before you can build with Ninja, you must generate the correct build files with CMake.

Calling cmake -G Ninja with no parameters:

build$ cmake -G Ninja ..

will default to the nrf52832_xxAA platform with the s132_6.0.0 SoftDevice and gccarmemb toolchain.

Tip: You can also use the cmake-gui -GNinja .. command to open the CMake graphical user interface when configuring the SDK. Press the <Configure> and then <Generate> buttons to generate the build files.

You can specify the required TOOLCHAIN and PLATFORM name to CMAKE. The build system will ensure a valid BOARD and SOFTDEVICE combination for each given platform.

build$ cmake -G Ninja -DTOOLCHAIN=<toolchain> -DPLATFORM=<platform> ..

Possible options for the PLATFORM and TOOLCHAIN are as follows:

TOOLCHAIN
- gccarmemb for the GNU ARM Embedded toolchain
- armcc for the Keil ARMCC toolchain
- clang for the Clang compiler (with GNU ARM Embedded assembler and linker)
PLATFORM
- nrf51422_xxAC (deprecated and no longer officially supported)
- nrf52832_xxAA
- nrf52840_xxAA

For example, to build mesh stack for nRF52 DK with GNU ARM Embedded toolchain, use:

build$ cmake -G Ninja -DTOOLCHAIN=gccarmemb -DPLATFORM=nrf52832_xxAA ..

If to want, you can customize BOARD and SOFTDEVICE options with -D command line switches as follows:

BOARD: valid board combination based on platform type. You can choose one of the values from nrf5_sdk_for_mesh/CMake/board.
SOFTDEVICE: valid SoftDevice based on platform type. You can choose one of the values from nrf5_sdk_for_mesh/CMake/softdevice.

Building the stack and examples

After the Ninja build files are generated, running ninja will build all the targets (examples and libraries). If you have PC-Lint installed, the sources can be linted using the ninja lint command. To see a list of available build targets, run the following command:

build $ ninja help

To build a specific target from this list, run, for example, ninja light_switch_server_nrf52832_xxAA_s132_6.0.0 if the current platform is nrf52832_xxAA with the s132_6.0.0 SoftDevice.

CMake generates Ninja build files in the folder in which CMake is run, so all targets must be built from that directory. In other words, in-directory building is not supported and running ninja in one of the example folders will result in an error message generated by the Ninja build system.

Generating SEGGER Embedded Studio project files

Warning: The generator will overwrite any existing projects, please back up existing projects before running the generator.

It is possible to generate SEGGER Embedded Studio project files using the CMake build system. With the option GENERATE_SES_PROJECTS enabled, CMake will generate a SEGGER Embedded Studio project based on the current settings. For example, to generate a project for nrf52832_xxAA using the S132 v6.0.0 SoftDevice, run CMake in your build directory like this:

cmake -G Ninja -DGENERATE_SES_PROJECTS=ON -DPLATFORM=nrf52832_xxAA -DSOFTDEVICE=s132_6.0.0 ..

Useful CMake command line options

CMake allows you to generate project files in release or debug configurations. To do so, use the -DCMAKE_BUILD_TYPE option:

build $ cmake -DCMAKE_BUILD_TYPE=Release ..      # Generates build files in release mode
build $ cmake -DCMAKE_BUILD_TYPE=Debug ..        # Generates build files in debug mode
build $ cmake -DCMAKE_BUILD_TYPE=MinSizeRel ..   # Generates build files optimized for size

The default build type is Debug if the CMake project is a Git repository (contains a .git directory), otherwise it is set to RelWithDebInfo.

Creating a new build target

The easiest way to make a new build target is to:

Copy one of the example folders, e.g., examples/beaconing to examples/my_app.
Add the folder to the examples/CMakeLists.txt with a add_subfolder("my_app") command.
Modify the target name in the first line of examples/my_app/CMakeLists.txt to set(target "my_app").
Build your new target with
```
 build $ ninja my_app
```

Building the documentation

Important: Building documentation requires additional command line tools. See Installing the toolchain.

To build all documentation (API documentation and internal documentation), call the build system with the target doc.

build $ ninja doc

The Doxygen documentation is generated in <build folder>/doc/offline/html.

Unit test build (host)

The nRF5 SDK for Mesh contains a set of unit tests that verify module behavior. These unit tests run on the host system (i.e. PC, not the nRF5 device), and are built with GCC. See Installing the toolchain for toolchain requirements.

The nRF5 SDK for Mesh depends on two frameworks for unit testing:

Unity is the unit testing framework that is used for running the tests.
CMock is used by the unit tests to generate mocks.

Note that an installation of Git is required to download these modules.

CMock bundles Unity as a submodule, thus in the same directory as the nRF5 SDK for Mesh, make sure to clone the CMock repository recursively:

$ git clone https://github.com/ThrowTheSwitch/CMock.git --recursive cmock

The directory structure should now look like this:

.
+-- cmock/
+-- nrf5_sdk_for_mesh/

Enter the nrf5_sdk_for_mesh directory, and make a new build directory, e.g. build_host:

nrf5_sdk_for_mesh $ mkdir -p build_host && cd build_host

To build for host, so that the unit tests can be run, set the option BUILD_HOST to ON and provide the path to CMock using the CMOCK_ROOT option. Note that all paths given to CMake must use forward slashes ('/') as directory separators.

build_host $ cmake -G Ninja -DBUILD_HOST=ON -DCMOCK_ROOT=<dir/cmock> ..

If a different version of Unity from the one included as a submodule in CMock is wanted, this can be specified by passing -DUNITY_ROOT=<dir/unity> to CMake. Note that the two paths can be set permanently with environmental variables (UNITY_ROOT and CMOCK_ROOT), and CMake is set up to look for CMock in the directory above the nrf5_sdk_for_mesh, so if the instructions above have been followed, both these variables are redundant.

Build all the unit tests with ninja:

build_host $ ninja

To run the tests, run ctest (bundled with CMake) or call ninja test in the build directory.

build_host $ ctest # Run all unit tests