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 CMakeLists.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, or set build types in CMakeLists.txt.

To update the CMakeLists.txt file, either edit it directly or use … t.b.d. (TBD) IDE.

Editing CMakeLists.txt directly 

Add all files that your application uses to the target_sources function in CMakeLists.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 CMakeLists.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 Build System (CMake) in the Zephyr documentation for more information about how to edit CMakeLists.txt.

Maintaining CMakeLists.txt in … t.b.d. (TBD) IDE 

t.b.d.

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 Write your devicetree 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 Kconfig configuration values in the Zephyr documentation for information on how to edit the prj.conf file.

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. While it is possible to edit the .config file directly, you should use 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.

See Interactive Kconfig interfaces 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 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 One-Time CMake Arguments for more information.

Configuring build types 

Build types enable you to use different sets of configuration options for each board. You can create several build type .conf files per board and select one of them when building the application. This means that you do not have to use one prj.conf file for your project and modify it each time to fit your needs.

Note

Creating build types and selecting them is optional.

Creating build type files 

To create custom build type files for your application instead of using a single prj.conf file, complete the following steps:

During application development, follow the procedure for creating the application until after the step where you create the CMakeLists.txt file.
In the CMakeLists.txt file, define the file name pattern for configuration files. For example:
```
set(CONF_FILE "app_${CMAKE_BUILD_TYPE}.conf")
```
In this define, CMAKE_BUILD_TYPE will be used for selecting the build type.
Optionally, include an if statement that checks for the presence of the selected build type configuration files. .. For an example, see applications/bridle_desktop/CMakeLists.txt.
Continue the application creation procedure by setting the Kconfig configuration options.
Save the .conf file in the application directory with a name that matches the file name pattern defined in CMakeLists. For example, app_ZRelease.conf. In this file name, ZRelease is the build type name.

You can now select build types from command line.

Selecting a build type from command line 

To select the build type when building the application from command line, specify the build type by adding the following parameter to the west build command:

-- -DCMAKE_BUILD_TYPE=selected_build_type

For example, you can replace the selected_build_type variable to build the ZRelease firmware for PCA20041 by running the following command in the project directory:

west build -b bridle_board -d build_board -- -DCMAKE_BUILD_TYPE=ZRelease

The build_board parameter specifies the output directory for the build files.