Raspberry Pico and CMake: Advanced Setup

CMake is the build system of the Raspberry Pico ecosystem. In the last article, I explained the CMake essentials from the perspective of a developer that is new to C. If you followed along, you should now feel comfortable to structure your programs with CMake.

Building on this foundation, this article covers additional techniques: Conditional configuration, preprocessor symbols, including third party libraries, and how to add tests.

This article originally appeared at my blog.

Example: Pico DHT11 library

This article explains the setup that I use in my libraries. A good and not too complex example is my library for reading temperature data from the DHT11 sensor: pico-dht11-lib.

The project has the following directory structure to which I will relate in the article. Also, check out the repo to see all techniques explained in this article.

Conditional Configuration

In some projects, you need to build a project with a specific case: Library only, example code, or tests. These cases have also different requirements, like which parts of your project they will use, to which other libraries you are linking, or even the use of a specific compiler or compiler options.

Conditional configuration can be achieved with CMake options: Defined in the root config file, they triple down you project to other config files and source code.

In the pico-dht11-lib, the conditional configuration BUILD_EXAMPLES and BUILD_TESTS are expressed as follows:

The keyword OPTIONS is followed by a symbol, a descriptive String, and a boolean value. Then, anywhere in your other CMake files, you can refer to this option name, and use expressions like if and elseif for branching the build options.

How do you invoke options? When calling cmake from the root directory, add the options and their boolean value:

Defining Preprocessor Symbols

Options are also helpful for passing preprocessor symbols to the source code files: Simple use the very same names.

In the pico-dht11-lib, the presence of either BUILD_TESTS or BUILD_EXAMPLES will determine if the Raspberry Pico SDK or a mock file will be included.

To pass options to the source code files, you need to modify the executable/library config file of the same folder by adding the directive target_compile_definitions. Check if a CMake option is active, and if yes, pass this to your library or executable file.

Include Third Party Libraries

CMake has a long history, and so it has a long list of commands that you can use to include other libraries. The Pico SDK uses git submodules. A very recent alternative, and the one that worked for me out of the box, is FetchContent. With a CMake file, you point to any other CMake project on Github, add options, and can then use it in your other CMake files.

The pico-dht11-lib uses the cmocka test framework. To include it in the project, the following file is used.

Then the test executable can be linked with the cmocka symbol.

Including Tests

The inclusion of tests is the sum of all the above step: Define a CMake option to conditionally configure & build your project, use the option name as a preprocessor symbol, and link your test code to the test library.

A simple test case in pico-dh11-lib is the configuration of the an DHT11 struct.

See my cmocka article to learn more about testing.

Conclusion

This article showed you advanced CMake techniques. First, we learned how to define CMake options in the root CMake file and how to use them for conditional configuration & building. Second, we saw how the CMake options, invoked with the cmake command, can be passed down to the source files as preprocessor symbols. Third, we saw how to use FetchContent command to include any other CMake project. Finally, we saw how all these techniques come together to include and build tests.

IT Project Manager & Developer

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store