Advanced usage

This page will discuss how to customize your project beyond the functions provided with Arduino_Core_STM32, using some standard CMake features. Hence, knowledge of both CMake and the STM32 CMake framework is assumed. Regarding the latter, an insight() can be useful, namely LOGIC_STRUCTURE.

Below is the logic structure of the simplest example, the Blink sketch. The following sections may refer to it to illustrate their points.

Adding new settings to the build

Depending on the particular setting, CMake provides several functions:

• target_compile_definitions()
• target_compile_options()
• target_include_directories()
• target_link_directories()
• target_link_libraries()
• target_link_options()
• target_sources()

Most of these commands make use of the PUBLIC, INTERFACE or PRIVATE keywords.

• PUBLIC and INTERFACE will apply the setting to all the dependers of the target in question;
• INTERFACE and PRIVATE apply the setting to the target itself.

Here is a comprehensive list of commands that can be used in a project.

Where to add the settings

Several interface targets are of interest when the settings are to affect more than just the user sketch:

• base_config is depended upon by all the project (core, libraries, sketch);
• The targets ending in _usage contain settings that are propagated upwards through the tree; these are useful when the scope of the setting is more specific.

It is also possible to add PRIVATE build settings directly on the code targets; e.g., to the sketch target. However, a good practice is to instead create additional INTERFACE targets to put these flags in, and make it a dependency of other parts of the project, using target_link_libraries().

Some code part come in three targets, e.g., core, core_bin, core_usage. The actual source files always are in the _bin target; that is to say, when there are source files (think of precompiled Arduino libraries). *_usage gathers "public" settings to be used in that that target, and also by the dependers. Lastly, the bare name target is just a wrapper are the previous two.

Change the way CMake builds the project

Some variables affect the way CMake builds the project. They can be specified either in a CMakeLists.txt, or (preferably) on the command-line, with the following syntax:

cmake -S ... -B ... -DVARIABLE=VALUE

(The value is mandatory; use 1, ON or YES as boolean true value.)

A comprehensive list of such variables is defined in the CMake documentation; some of the most relevant ones are listed below.

• CMAKE_DISABLE_PRECOMPILE_HEADERS
• CMAKE_INCLUDE_CURRENT_DIR
• CMAKE_INTERPROCEDURAL_OPTIMIZATION (equivalent to the LTO switch in overall_settings())
• CMAKE_UNITY_BUILD
• EXECUTABLE_OUTPUT_PATH

CMake is also affected by some environment variables (doc here), e.g.:

• CMAKE_BUILD_PARALLEL_LEVEL
• CMAKE_GENERATOR (usful to omit the -G on each CMake call)
• CC, CXX, CFLAGS, CXXFLAGS, LDFLAGS with the same meaning as with make

Please note that not all features work, or even make sense, for embedded projects. Caution and testing are advised when dealing with the variables listed here.