The mesh library and example applications can be built with either SEGGER Embedded Studio or CMake. Before you start building, remember to set up the mesh development environment first. See Installing the toolchain for details.
Table of contents
SEGGER Embedded Studio (SES) provides a way of quickly getting the example code up and running with full debug capability.
Before building the 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:
SDK_ROOT
macro. It defaults to an nRF5 SDK instance unzipped right next to the mesh folder.SDK_ROOT
macro to a custom nRF5 SDK instance.To set the SDK_ROOT
macro manually in SEGGER Embedded Studio:
SDK_ROOT=<the path to nRF5 SDK instance>
.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.
To build an example with SEGGER Embedded Studio:
examples/
folder, for instance examples/light_switch/client/light_switch_client_nrf52832_xxAA_s132_6_1_1.emProject
.You can now run the example using SEGGER Embedded Studio.
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.
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 Configuring and performing DFU over Mesh in these cases. Example use: build $ ninja merge_light_switch_server_nrf52832_xxAA_s132_6.1.1
flash_<target>
for each of the example targets that runs 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_6.1.1
The following three steps are mandatory when building with CMake:
Using CMake for building also comes with useful additional options.
This section describes generating build files for the Ninja build tool.
-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:
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_6.1.1
SoftDevice and gccarmemb
toolchain:
build$ cmake -G Ninja ..
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.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
:
toolchain
gccarmemb
for the GNU ARM Embedded toolchainarmcc
for the Keil ARMCC toolchainclang
for the Clang compiler (with GNU ARM Embedded assembler and linker)platform
nrf51422_xxAC
(deprecated and no longer officially supported)nrf52810_xxAA
nrf52832_xxAA
nrf52840_xxAA
Example: To build 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:
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
.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_6.1.1
SoftDevice, run:
ninja light_switch_server_nrf52832_xxAA_s132_6.1.1
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.
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 v6.1.1 SoftDevice, run CMake in your build directory:
cmake -G Ninja -DGENERATE_SES_PROJECTS=ON -DPLATFORM=nrf52832_xxAA -DSOFTDEVICE=s132_6.1.1 ..
The following procedures can be useful when working with CMake:
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
.
To create a new build target:
examples/beaconing
to examples/my_app
.examples/CMakeLists.txt
with the add_subfolder("my_app")
command.examples/my_app/CMakeLists.txt
to set(target "my_app")
.build $ ninja my_app
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
.
To build units tests:
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
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 ..
nrf5_sdk_for_mesh
folder. If it is not located next to the mesh folder, you can specify its path by passing -DCMOCK_ROOT=<dir/cmock>
.-DUNITY_ROOT=<dir/unity>
.build_host $ ninja
To run the tests, you can either:
ctest
(bundled with CMake): build_host $ ctest # Run all unit tests
ninja test
in the build directory: build_host $ ninja test