nRF5 SDK for Mesh v5.0.0
Building the stack and examples

The Bluetooth mesh library and example applications can be built with SEGGER Embedded Studio, Ninja or make. Regardless of your choice, you first need to generate build files with CMake.

Before you start building, remember to set up the Bluetooth mesh development environment first. See Installing the toolchain for details.

Note
The building process changes slightly if you are adding custom examples.

Table of contents

Generating build files with CMake

CMake provides the possibility to build both for host (unit tests) and target.

CMake is "an extensible, open-source system that manages the build process in an operating system and in a compiler-independent manner" (as stated on the CMake website).

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). The choice of which build tool is to be targeted is controlled with 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.

SoftDevice requirement
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 Bluetooth mesh application.
mergehex exception
There is a merge_<target> for each of the example targets that uses mergehex to generate a hexfile with the application and SoftDevice merged. Take special care with the order of programming when the application has bootloader support. Follow the procedure in Configuring and performing DFU over Mesh in these cases.
  • Example use: 
      build $ ninja merge_light_switch_server_nrf52832_xxAA_s132_7.2.0
Interactive programming tool requirement
There is a flash_<target> for each of the example targets that run an interactive programming tool. This requires the nRFx Command Line tools and Python 3 to be installed (see Installing the toolchain).
  • Example use: 
      build $ ninja flash_light_switch_server_nrf52832_xxAA_s132_7.2.0

There is also an app_flash_<target> that runs the interactive programming tool in --sectorerase mode. In this mode, the flashing procedure does not touch UICR, SoftDevice, or other flash pages that are not occupied by the application hex file. This target is useful for testing application changes without having to reprovision the device.

You can generate build files with CMake in the following variants:

Using CMake for building also comes with useful command line options.

Generating Ninja or make build files

Note
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 Bluetooth mesh stack repository, where all artifacts generated by the build system are stored: 

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 will default to the nrf52832_xxAA platform with the s132_7.2.0 SoftDevice and gccarmemb toolchain: 

build$ cmake -G Ninja ..
Note
You can also use the cmake-gui -GNinja .. command to open the CMake graphical user interface when configuring the SDK. Press Configure and then Generate to generate the build files.

Customization

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 toolchain and platform:

Example: To build Bluetooth mesh stack for nRF52 DK with GNU ARM Embedded toolchain, use: 

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

You can also customize BOARD and SOFTDEVICE options with -D command line switches:

Generating SEGGER Embedded Studio project files

Warning
The generator will overwrite any existing projects. 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 SES project based on the current settings.

Example: To generate a project for nrf52832_xxAA using the S132 v7.2.0 SoftDevice, run CMake in your build directory: 

cmake -G Ninja -DGENERATE_SES_PROJECTS=ON -DPLATFORM=nrf52832_xxAA -DSOFTDEVICE=s132_7.2.0 ..

Generating build files for unit tests (host)

Note
Building unit tests is optional and requires additional tools. See the table of required tools on Installing the toolchain page.

To build units tests:

  1. Enter the nrf5_sdk_for_mesh directory and make a new build directory, for example build_host: 
     nrf5_sdk_for_mesh $ mkdir -p build_host && cd build_host

  2. Set the option BUILD_HOST to ON and CMAKE_BUILD_TYPE to Debug: 

     build_host $ cmake -G Ninja -DBUILD_HOST=ON -DCMAKE_BUILD_TYPE=Debug ..

    You can modify this command in the following ways:

    • CMake is set up to look for CMock in the directory above the nrf5_sdk_for_mesh folder. If it is not located next to the nRF5 SDK for Mesh folder, you can specify its path by passing -DCMOCK_ROOT=<dir/cmock>.
    • If a different version of Unity is used than the one included as a submodule in CMock, you can specify its path by passing -DUNITY_ROOT=<dir/unity>. Make sure you are using the CMock master repository with the commit hash mentioned on the Installing the toolchain page.
    • All paths given to CMake must use forward slashes ('/') as directory separators.

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.

Building stack and examples using Ninja

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

Example: To build a specific target from this list with the current platform nrf52832_xxAA and the s132_7.2.0 SoftDevice, run: 

ninja light_switch_server_nrf52832_xxAA_s132_7.2.0

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 results in an error message generated by the Ninja build system.

Building stack and examples using make

After the make build files are generated, running make will build all the targets (examples and libraries).

Building using make is similar to building using Ninja. The information in the Ninja sections apply to make as well, which means that you can use the make command instead of ninja for example for building unit tests.

Building with SEGGER Embedded Studio

SEGGER Embedded Studio (SES) provides a way of quickly getting the example code up and running with full debug capability.

First time setup

Before building the Bluetooth mesh examples with SEGGER Embedded Studio for the first time, you must complete a one-time setup of the SDK_ROOT macro in SEGGER Embedded Studio. This macro is used to find the nRF5 SDK files.

You can either:

To set the SDK_ROOT macro manually in SEGGER Embedded Studio:

  1. Go to Tools -> Options.
  2. Select Building.
  3. Under Build in the configuration list, edit Global macros to contain SDK_ROOT=<the path to nRF5 SDK instance>.
  4. Save the configuration.

You can verify the path by opening one of the source files under the nRF5 SDK file group. If the macro is set correctly, the file opens in the editor window. If not, an error message is displayed with information that the file cannot be found.

For more info on SEGGER Embedded Studio macros, see the SES Project macros page.

Building with SES

By default, the nRF5 SDK for Mesh package includes the SES project files for all examples. This allows you to quickly start building examples with SES.

However, if you make changes to any of the CMakeLists.txt files, you must generate the SES project files again using CMake.

To build an example with SEGGER Embedded Studio:

  1. Open the desired project file located in the examples/ folder, for instance examples/light_switch/client/light_switch_client_nrf52832_xxAA_s132_7_0_1.emProject.
  2. Go to Build -> Build < name of the emProject file>, for instance Build light_switch_client_nrf52832_xxAA_s132_7.2.0.
  3. Wait for the compilation to finish.

You can now run the example using SEGGER Embedded Studio.

Build unit tests with Ninja

To build all the unit tests with Ninja, run the following command: 

    build_host $ ninja

To run the tests, you can use one of the following options:

Building documentation with Ninja

Note
Building documentation requires additional command line tools. See the list on Installing the toolchain page.

To locally 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.

Documentation feedback | Developer Zone | Subscribe | Updated