This document lists all the functions defined in the/cmake folder in this project.It would be a good idea to add this folder to the "CMake search path" in your project :

list(APPENDCMAKE_MODULE_PATH${CORE_PATH}/cmake)

(done by default in thequickstart template.)

All the functions are defined in a CMake module of the same name. Therefore, you have to include said module before calling the function:

include(foo)foo()

(Of course, this doesnot apply to the CMake built-in functions as described inIntroduction to CMake. These can be called directly.)

Syntax:

build_sketch(TARGET<targetName>SOURCES<sourcefile...>[DEPENDS<dependency...>])

This is the main function that encapsulates most of the automation of Arduino. It should only be calledafteroverall_settings andset_board.

• targetName is the name of thebinary target that will be created as a result of this function; this is a handle that may be reused in later calls, to e.g.,insights().
• sourcefile... is a list of sources files to be compiled. This does not comprise header files (.h).You are strongly advised to hard-code the list of files directly in the CMakeLists.txt. Usingwildcards is possible, but not guaranteed to work in all cases.
• the optionaldependencies are targets, usually Arduino libraries such as created byexternal_library(), that the sketch dedends on.The CMake build model makes it awkward at best to automatically handle dependencies the way Arduino does, so they have to be specified explicitly.

What this function does is the following:

• Include the parts of Arduino_Core_STM32 needed for the project (core + right variant);
• Preprocess the sources: turn the.ino files to.cpp;
• Create the binary executable target;
• Bind the target to its dependencies (core + "DEPENDS");
• Add post-build hooks to:
  • Display the size report message ("Sketch uses xxx bytes of program storage space. Maximum is yyy bytes...";
  • Convert the binary to.bin and.hex.

Syntax:

external_library(PATH<path_to_lib>[DEPENDS<dependency...>][FORCE])

This function is used to add a third-party library in the build description. It takes as arguments:

• the path to the library to parse;
• as withbuild_sketch(), an optional list of dependencies of the library;
• optionally, theFORCE keyword; read below about it.

Most third-party libraries do not ship with a CMakeLists.txt.Therefore, one needs to be generated before that library can be used in a CMake build.This function wraps the generation of the CMakeLists.txt and the subsequentadd_subdirectory() to actually add the library to the build.

If no CMakeLists.txt is found, it is autogenerated by a Python script after readinglibrary.properties.TheFORCE keyword lets you override this behavior and overwrite the CMakeLists.txt unconditionally.

In the default case, the autogenerated CMakeLists.txt will create for the librarya target with the same name as the folder name.You can then use this target as a dependency of another library or of your sketch.

Syntax:

insights(TARGET<targetName>[DIRECT_INCLUDES][TRANSITIVE_INCLUDES][SYMBOLS][ARCHIVES][LOGIC_STRUCTURE])

This function lets you produce insights about the build process.It uses Graphviz to generate SVG files in order to better understand what happens throughout the build: configuration, compilation, linking.The mandatory TARGET argument is the name of the element to analyze, usually your sketch target (created withbuild_sketch()).Each insight keyword is optional; even when provided, they are not built by default, you have to explicitly generate them with the build tool (e.g.,ninja symbols.svg).

Note: Enabling some of these graphs can hinder performances much (in the order of +50% build time).

Syntax:

overall_settings([STANDARD_LIBC][PRINTF_FLOAT][SCANF_FLOAT][DEBUG_SYMBOLS][LTO][NO_RELATIVE_MACRO][UNDEF_NDEBUG][CORE_CALLBACK][OPTIMIZATION<optLevel>][BUILD_OPT<path_to_build.opt>][DISABLE_HAL_MODULES<modules...>])

This function replaces, with additions, some of the options of the menu bar of Arduino IDE.All the keywords are optional; the default behavior is selected on fallback. The order of the keywords does not matter.

Keywords that take no argument:

• STANDARD_LIBC: switch to Newlib Standard as the runtime library, instead of Newlib Nano;
• PRINTF_FLOAT: enable%f inprintf (Newlib Nano only);
• SCANF_FLOAT: enable%f inscanf (Newlib Nano only);
• DEBUG_SYMBOLS: add-g to GCC (for debug);
• LTO: enable Link-Time Optimizations (-flto);
• NO_RELATIVE_MACRO: make__FILE__ yield absolute paths; the default is the oppisite, for size and security reasons;
• UNDEF_NDEBUG: do not define theNDEBUG macro; use this keyword for debug builds;
• CORE_CALLBACK: define theCORE_CALLBACK macro; read about use caseshere.

Keywords that take a single argument:

• OPTIMIZATION: takes an optimization level (one of0123gs); this will then be passed to GCC's as a-O flag;
• BUILD_OPT: add the specified file to GCC's command line, as a@file. The file is usually named "build.opt", hence the keyword name. Note: with Arduino IDE, the file is taken by default into account; with CMake, it is not, only this keyword triggers this.

Keyword that takes several arguments:

• DISABLE_HAL_MODULES: lets you disable any unused HAL modules as an optimization.Read about iton the wiki.The supported HAL modules are:
  • ADC
  • I2C
  • RTC
  • SPI
  • TIM
  • DAC
  • EXTI
  • ETH
  • SD
  • QSPIDisabling them all (when possible) yields a significant additional size gain.

Syntax:

set_board(<boardName>[SERIAL<serialSetting>][USB<usbSetting>][XUSB<usbSpeed>][VIRTIO<virtioSetting>][BOOTLOADER<bootloader>])

This function replaces the options of the menu bar of Arduino IDE that are related to board-specific features.It manages to stay up-to-date with what Arduino IDE would offer by parsingboard.txt/platform.txt as needed,and caches the result in a CMake-readable database.

The first argument to this function must be the board codename, as used in boards.txt.E.g., "GENERIC_L010RBTX", not "Generic L010RBTx" (the latter being what the IDE displays).Then come any number of the five keywords, in any order. As withoverall_settings, default values are used on fallback.Depending on your board, not all features may be meaningful. Note: the values for each keyword are case-sensitive!

• SERIAL: Serial support. Usually one ofgeneric,disabled,none (standing for "Enabled (no generic 'Serial')");
• USB: USB support. Usually one ofnone,CDCgen,CDC,HID;
• XUSB: USB speed. Usually one ofFS,HS,HSFS;
• VIRTIO: virtIO support. Usually one ofdisable,generic,enabled;
• BOOTLOADER: third-party bootloader impacting the build (link step). Usually one ofhid,dfuo,dfu2.