extensions

Zephyr’s CMake extension commands.

This module defines the commands that Zephyr applications, Zephyr modules, and the build system itself use to describe what they build.

Many commands come in an _ifdef and an _ifndef flavour, taking a Kconfig option as their first argument, so that build rules can be made conditional without wrapping them in an if() block.

This module is loaded as part of find_package(Zephyr), which means that every command documented below is available in the CMakeLists.txt of any Zephyr application or module.

The following methods are for modifying the CMake library called zephyr. zephyr is a catch-all CMake library for source files that can be built purely with the include paths, defines, and other compiler flags that all zephyr source files use.

Example usage:

zephyr_sources(
  random_esp32.c
  utils.c
)

Is short for:

target_sources(zephyr PRIVATE
  ${CMAKE_CURRENT_SOURCE_DIR}/random_esp32.c
  ${CMAKE_CURRENT_SOURCE_DIR}/utils.c
)

As a very high-level introduction, here are two call graphs that are purposely minimalistic and incomplete.

zephyr_library_cc_option()
         |
         v
zephyr_library_compile_options()  -->  target_compile_options()

zephyr_cc_option()           --->  target_cc_option()
                                        |
                                        v
zephyr_cc_option_fallback()  --->  target_cc_option_fallback()
                                        |
                                        v
zephyr_compile_options()     --->  target_compile_options()

zephyr_sources(<sources>...)

Add sources to the zephyr library.

See target_sources for details.

zephyr_include_directories(<dirs>...)

Add include directories to the zephyr library.

See target_include_directories for details.

zephyr_system_include_directories(<dirs>...)

Add system include directories to the zephyr library.

See target_include_directories for details.

zephyr_compile_definitions(<defs>...)

Add compile definitions to the zephyr library.

See target_compile_definitions for details.

zephyr_compile_options(<options>...)

Add compile options to the zephyr library.

See target_compile_options for details.

zephyr_link_libraries(<item>...)

Add link libraries to the zephyr library.

See target_link_libraries for details.

zephyr_libc_link_libraries(<item> ...)

Add link libraries to the zephyr library’s LIBC_LINK_LIBRARIES property.

This function allows subsystems to define libraries which get added to the link command after all other libraries and modules. It’s useful when using a toolchain library, like libc or libgcc, as those can get added when processing the ‘lib’ directory, before any module libraries and hence might not get used to resolve symbols from modules.

zephyr_cc_option(<option>...)

Add compiler options to the zephyr library, if supported by the compiler.

This function checks if the compiler supports each option. If supported, it adds the option to the ‘zephyr’ library.

zephyr_cc_option_fallback(<option1> <option2>)

Add a compiler option to the zephyr library, falling back to a second option if the first is not supported.

This function checks if the compiler supports <option1>. If so, it is added. Otherwise, it checks <option2> and adds it if supported.

zephyr_ld_options(<options>...)

Add linker options to the zephyr library.

See target_ld_options() for details.

zephyr_get_include_directories_for_lang_as_string(<lang> <var> [STRIP_PREFIX])

Get include directories for a specific language as a string.

Writes the include directories for language <lang> to variable <var> as a string.