Modifying a sample application

After programming and testing a sample application, you probably want to make some modifications to the application, for example, add your own files with additional functionality, change compilation options, or update the default configuration.

Adding files and changing compiler settings

All files that your application uses must be specified in the CMakeList.txt file. By default, most samples include only the main application file src/main.c. This means that you must add all other files that you are using.

You can also configure compiler options, application defines, or include directories in CMakeList.txt.

To update the CMakeList.txt file, either edit it directly or use SEGGER Embedded Studio (SES) to maintain it.

Editing CMakeList.txt directly

Add all files that your application uses to the target_sources function in CMakeList.txt. To include several files, it can be useful to specify them with a wildcard. For example, to include all .c files from the src folder, add the following lines to your CMakeList.txt:

FILE(GLOB app_sources src/*.c)
target_sources(app PRIVATE ${app_sources})

Instead of specifying each file (explicitly or with a wildcard), you can include all files from a folder by adding that folder as include folder:

target_include_directories(app PRIVATE src)

See the CMake documentation and CMake Details in the Zephyr documentation for more information about how to edit CMakeList.txt.

Maintaining CMakeList.txt in SES

To add a file in SES, right-click Project ‘app/libapp.a’ in the Project Explorer. Select either Add new file to CMakeLists.txt to create a file and add it or Add existing file to CMakeLists.txt to add a file that already exists.

Adding files in SES

Adding files in SES

To edit compilation options in SES, right-click Project ‘app/libapp.a’ in the Project Explorer and select Edit Compile Options in CMakeLists.txt.

In the window that is displayed, you can define compilation options for the project.

Setting compiler defines, includes, and options in SES

Note

These compilation options apply to the application project only. To manage Zephyr and other subsystems, go to Project > Configure nRF Connect SDK Project.

SES tags in CMakeLists.txt

To be able to manage CMakeLists.txt with SES, the CMake commands that are specific to the nRF Connect SDK application must be marked so SES can identify them. Therefore, they must be surrounded by # NORDIC SDK APP START and # NORDIC SDK APP END tags.

The following CMake commands can be managed by SES, if they target the app library:

  • target_sources

  • target_compile_definitions

  • target_include_directories

  • target_compile_options

The CMakeLists.txt files for the sample applications in the nRF Connect SDK are tagged as required. Therefore, if you always use SES to maintain them, you do not need to worry about tagging. Typically, the CMakeLists.txt files include at least the main.c file as source:

# NORDIC SDK APP START
target_sources(app PRIVATE src/main.c)
# NORDIC SDK APP END

Configuring your application

If your application uses a provided library or targets a specific board, you might want to change the default configuration of the library or board. There are different ways of doing this, but not all will store your configuration permanently.

The default configuration for a library is specified in its Kconfig file. Similarly, the default configuration for a board is specified in its *_defconfig file (and its Kconfig.defconfig file, see Default board configuration in the Zephyr documentation for more information). The configuration for your application, which might override some default options of the libraries or the board, is specified in a prj.conf file in the application directory.

For detailed information about configuration options, see Kconfig Configuration in the Zephyr documentation.

Changing the configuration permanently

To configure your application and maintain the configuration when you clean the build directory, add your changes to the prj.conf file in your application directory. In this file, you can specify different values for configuration options that are defined by a library or board, and you can add configuration options that are specific to your application.

See Setting Application Configuration Values in the Zephyr documentation for information on how to edit the prj.conf file.

If you work with SES, the prj.conf file is read when you open a project. This means that after you edit this file, you must re-open your project.

Note

It is possible to change the default configuration for a library by changing the Kconfig file of the library. However, best practice is to override the configuration in the application configuration file prj.conf.

Changing the configuration temporarily

When building your application, the different Kconfig and *_defconfig files and the prj.conf file are merged together. The combined configuration is saved in a zephyr/.config file in your build directory. This means that this file is available when building the application, but it is deleted when you clean the build directory.

To quickly test different configuration options, or to build your application in different variants, you can update the .config file in the build directory. Changes are picked up immediately, and you do not need to re-open the project in SES.

While it is possible to edit the .config file directly, you should use SES or a tool like menuconfig or guiconfig to update it. These tools present all available options and allow you to select the ones that you need.

To edit the file in SES, select Project > Configure nRF Connect SDK Project. If your application contains more than one image (see Multi-image builds), you must select the correct target. To configure the parent image (the main application), select menuconfig. The other options allow you to configure the child images.

See Overriding the Default Configuration in the Zephyr documentation for instructions on how to run menuconfig or guiconfig.

To locate a specific configuration option, use the filter (Jump to in menuconfig and guiconfig). The documentation for each configuration option also lists the menu path where the option can be found.

Important

All changes to the .config file are lost when you clean your build directory. You can save it to another location, but you must then manually copy it back to your build directory.

Providing CMake options

You can provide additional options for building your application to the CMake process, which can be useful, for example, to switch between different build scenarios. These options are specified when CMake is run, thus not during the actual build, but when configuring the build.

If you work with SES, this configuration takes place when you open an nRF Connect SDK project, and you must therefore provide the CMake options before you open the project. To specify CMake options, click Tools > Options, select the nRF Connect tab, and specify a value for Additional CMake options.

If you work on the command line, pass the additional options to the west build command. The options must be added after a -- at the end of the command. See Additional CMake Arguments for more information.