API Reference

This page is an automatically generated reference for the public API of Build System v2, extracted from the CMake source in tools/cmakev2. For how these are used in practice, see the guides on the Build System v2 page.

Functions 

add_prebuilt_library

add_prebuilt_library(<target> <lib>
                     [REQUIRES <component>...]
                     [PRIV_REQUIRES <component>...])

target[in]

Target name for the imported library.

lib[in]

Path to the prebuilt static library.

REQUIRES[in,opt]

Components this library depends on publicly.

PRIV_REQUIRES[in,opt]

Components this library depends on privately.

Import a prebuilt static library as a CMake target, optionally linking it against other ESP-IDF components. The resulting target can be linked into a component or executable like any other library.

idf_build_binary

idf_build_binary(<executable>
                 TARGET <target>
                 OUTPUT_FILE <file>
                 [ALL])

executable[in]

Executable target for which to generate a binary image file.

TARGET[in]

The name of the target that will be created for the generated binary image.

OUTPUT_FILE[in]

Output file path for storing the binary image file.

ALL[in,opt]

If specified, the target will be added to the default build target.

Create a binary image for the specified executable target and save it in the file specified with the OUTPUT_FILE option. A custom target named TARGET will be created for the generated binary image. The path of the generated binary image will be stored in the BINARY_PATH property and the executable target in the EXECUTABLE_TARGET property of the TARGET.

idf_build_executable

idf_build_executable(<executable>
                     [COMPONENTS <component>...]
                     [NAME <name>]
                     [SUFFIX <suffix>])

executable[in]

Name of the executable target to be created.

COMPONENTS[in,opt]

List of component names to add to the library.

NAME[in,opt]

Optional preferred generated binary name. If not provided, the executable name is used.

SUFFIX[in,opt]

Optional executable suffix.

MAPFILE_TARGET[in,opt]

Name of the target for the map file. If provided, the link map file is generated for the specified executable, and the MAPFILE_TARGET target name is created for it. The MAPFILE_PATH property with the link map file path is added to the MAPFILE_TARGET target. This can be used for other targets that depend on the link map file. The link map file is not generated on Darwin host, so the target MAPFILE_TARGET may not be created if link map file is not generated.

Create a new executable target using the name specified in the executable argument, and link it to the library created with the component names provided in the COMPONENTS option. If the COMPONENTS option is not set, all discovered components are added to the library. Optionally set the executable name and suffix. The executable library target name is added to the LIBRARY_INTERFACE executable property.

idf_build_generate_flasher_args

idf_build_generate_flasher_args()

Generate the flasher_args.json file for the global flash target for tools that require it.

idf_build_generate_metadata

idf_build_generate_metadata([BINARY <binary>]
                            [EXECUTABLE <executable>]
                            [OUTPUT_FILE <file>]
                            [HINTS_OUTPUT_FILE <file>])

BINARY[in,opt]

Binary target for which to generate a metadata file.

EXECUTABLE[in,opt]

Executable target for which to generate a metadata file.

OUTPUT_FILE[in,opt]

Optional output file path for storing the metadata. If not provided, the default path <build>/project_description.json is used.

HINTS_OUTPUT_FILE[in,opt]

Optional output file path for storing the merged hints YAML file. If not provided, hints generation is skipped entirely. This opt-in behaviour prevents hint files from different binaries overwriting each other in multi-binary projects.

Generate metadata for the specified binary or executable target and store it in the specified OUTPUT_FILE. If no OUTPUT_FILE is provided, the default location <build>/project_description.json will be used.

idf_build_get_compile_options

idf_build_get_compile_options(<variable>)

variable[out]

Variable in which the list of compile option generator expressions is stored.

Gather the compile options from the COMPILE_OPTIONS, C_COMPILE_OPTIONS, CXX_COMPILE_OPTIONS, and ASM_COMPILE_OPTIONS build properties into a single list of generator expressions, suitable for passing to target_compile_options.

idf_build_get_property

idf_build_get_property(<var> <property> [GENERATOR_EXPRESSION])

variable[out]

Variable to store the value in.

property[in]

Property name to get the value of.

GENERATOR_EXPRESSION[in]

Obtain the generator expression for the property rather than the actual value.

Get the value of the specified property related to the ESP-IDF build.

idf_build_library

idf_build_library(<library>
                  [COMPONENTS <component>...])

library[in]

Name of the library interface to be created.

COMPONENTS[in,opt]

List of component names to add to the library.

Create a new library interface target with the name specified in the library option and link component targets to it based on the component names provided in the COMPONENTS option. If COMPONENTS option is not set, link component targets of all discovered components.

List of library properties

LIBRARY_COMPONENTS: List of component as specified by the COMPONENTS option.
LIBRARY_COMPONENTS_LINKED: List of component names linked to the library based on recursive evaluations of the INTERFACE_LINK_LIBRARIES and LINK_LIBRARIES target properties.
LIBRARY_COMPONENT_INTERFACES_LINKED: List of component interfaces linked to the library based on recursive evaluations of the INTERFACE_LINK_LIBRARIES and LINK_LIBRARIES target properties.

idf_build_set_property

idf_build_set_property(<property> <value> [APPEND])

property[in]

Property name.

value[in]

Property value.

APPEND

Append the value to the property's current value instead of replacing it.

Set the value of the specified property related to the ESP-IDF build. The property is also added to the internal list of build properties if it isn't already there.

idf_check_binary_size

idf_check_binary_size(<binary>)

binary[in]

Binary image target to which to add a partition size check. The binary target is created by the idf_build_binary or idf_sign_binary function.

Ensure that the generated binary image fits within the smallest available application partition. The file path of the binary image should be stored in the BINARY_PATH property of the binary target.

idf_component_get_property

idf_component_get_property(<variable> <component> <property> [GENERATOR_EXPRESSION])

variable[out]

Variable to store the value in.

component[in]

Component name, target, target alias or interface.

property[in]

Property name to get the value of.

GENERATOR_EXPRESSION

Obtain the generator expression for the property rather than the actual value.

Retrieve the value of the specified component property.

idf_component_include

idf_component_include(<name>
                      [OPTIONAL]
                      [INTERFACE <variable>])

name[in]

Component name.

OPTIONAL[opt]

If specified, the call is a silent no-op when the component is not known to the build, instead of aborting. When combined with INTERFACE, the output variable is set to the empty string on miss, so callers can use if(${variable}) as a truth check.

INTERFACE[out,opt]

Optional variable where the name of the target interface for the included component will be stored.

This is a core function of the build system, responsible for including the specified component, as indicated by the name option, into the build process. It does this by evaluating the component through the add_subdirectory call for the component's directory. The component is responsible for creating its own CMake target, with the target name provided via the COMPONENT_TARGET variable. This target is linked to the component's interface target, which is managed internally by the build system. The component's interface target is used by other components to establish their dependencies.

When the INTERFACE variable is provided, the name of the included component interface target will be stored in it.

By default, the function aborts the build if <name> is not known to the build system. Pass OPTIONAL to make the call non-fatal -- useful for integrations with components that may or may not be in the build, such as managed dependencies that only some board configurations pull in.

# Wire up an optional integration only when the component is present.
idf_component_include(button OPTIONAL INTERFACE button_iface)
if(button_iface)
    target_sources(${COMPONENT_TARGET} PRIVATE button_glue.c)
    target_link_libraries(${COMPONENT_TARGET} PRIVATE ${button_iface})
endif()

idf_component_mock

idf_component_mock([INCLUDE_DIRS <dir>...]
                   [MOCK_HEADER_FILES <file>...]
                   [REQUIRES <component>...]
                   [MOCK_SUBDIR <subdir>])

INCLUDE_DIRS[in,opt]

Include directories for the header files provided in MOCK_HEADER_FILES.

MOCK_HEADER_FILES[in,opt]

Header files from which CMock generates mock implementations.

REQUIRES[in,opt]

Additional components required by the mock component.

MOCK_SUBDIR[in,opt]

Subdirectory under the mocks output where generated files are placed.

Create a mock component using CMock and register it with the build system. This is a compatibility shim matching the v1 idf_component_mock function in tools/cmake/component.cmake. It generates Mock*.c and Mock*.h files from the given headers using Ruby + CMock, then delegates to idf_component_register so the mock participates in normal dependency resolution.

idf_component_optional_requires

idf_component_optional_requires(<type> <component>...)

type[in]

Type of dependency: PRIVATE, PUBLIC or INTERFACE

component[in]

The component name that should be added as a dependency to the evaluated component. It may be provided multiple times.

Add a dependency on a specific component only if the component is recognized by the build system. The behavior is controlled by the IDF_COMPONENT_OPTIONAL_REQUIRES_MODE build property:

IMMEDIATE (default): Include the component and link it to the caller if it is discovered. Safe for multi-library projects but may pull in more components than strictly needed.
DEFERRED: Do not include or link immediately; record the request and resolve it in idf_build_library so that the component is linked only when it is part of the library's dependency graph. Matches v1 semantics and reduces unnecessary components, but must not be used when building multiple libraries (see docs).

备注

This function should be avoided in cmakev2, where dependencies should be added based on configuration options. This is purely for backward compatibility with cmakev1.

警告

In multi-library projects with DEFERRED mode, optional requires resolved when processing a later library apply globally to shared component targets. Earlier libraries then link that optional component too, but their per-library metadata (e.g. linker fragments) was already computed and is not updated. DEFERRED mode is therefore disallowed when more than one library is built.

idf_component_register

idf_component_register([SRCS <file>..]
                       [SRC_DIRS <dir>...]
                       [EXCLUDE_SRCS <file>...]
                       [INCLUDE_DIRS <dir>...]
                       [PRIV_INCLUDE_DIRS <dir>...]
                       [LDFRAGMENTS <file>...]
                       [REQUIRES <component>...]
                       [PRIV_REQUIRES <component>...]
                       [REQUIRED_IDF_TARGETS <target>...]
                       [EMBED_FILES <file>...]
                       [EMBED_TXTFILES <file>...]
                       [WHOLE_ARCHIVE])

SRCS[in,opt]

List of source files for the component.

SRC_DIRS[in,opt]

List of source directories to search for source files (.c, .cpp, .S); ignored when SRCS is specified.

EXCLUDE_SRCS[in,opt]

List of source files to exclude from the designated source directories.

INCLUDE_DIRS[in,opt]

List of public include directories for the created component library.

PRIV_INCLUDE_DIRS[in,opt]

List of private include directories for the newly created component library.

LDFRAGMENTS[in,opt]

List of linker script fragments for the component.

REQUIRES[in,opt]

List of publicly required components based on usage requirements.

PRIV_REQUIRES[in,opt]

List of privately required components based on usage requirements.

REQUIRED_IDF_TARGETS[in,opt]

List of IDF build targets supported exclusively by the component.

EMBED_FILES[in,opt]

List of binary files to embed with the component.

EMBED_TXTFILES[in,opt]

List of text files to embed with the component.

WHOLE_ARCHIVE[in,opt]

Link the component as --whole-archive.

Register a new component with the build system using the provided options. This function also automatically links all commonly required and managed components to the component's target.

idf_component_register_build_event_callback

idf_component_register_build_event_callback(EVENT <event> CALLBACK <function-name>)

EVENT[in]

Build lifecycle event at which the callback will be invoked. Currently only POST_ELF is supported.

CALLBACK[in]

Name of a CMake function defined in the component's project_include.cmake file. The build system calls this function with the primary CMake target as its argument at the specified event point. For POST_ELF this is the executable target.

Example:

# project_include.cmake
function(my_component_post_elf_hook target)
    add_custom_command(TARGET ${target} POST_BUILD
        COMMAND my_tool "$<TARGET_FILE:${target}>")
endfunction()

idf_component_register_build_event_callback(
    EVENT    POST_ELF
    CALLBACK my_component_post_elf_hook)

idf_component_set_property

idf_component_set_property(<component> <property> <value> [APPEND])

component[in]

Component name, target, target alias or interface.

property[in]

Property name.

value[in]

Property value.

APPEND

Append the value to the property's current value instead of replacing it.

Set the value of the specified component property. The property is also added to the internal list of component properties if it isn't already there.

idf_create_confserver

idf_create_confserver(<executable>
                      TARGET <target>)

executable[in]

Executable target for which to create the confserver target.

TARGET[in]

Name of the confserver target to be created.

Create a confserver target with the name specified by the TARGET option for an executable.

idf_create_menuconfig

idf_create_menuconfig(<executable>
                      TARGET <target>)

executable[in]

Executable target for which to create the menuconfig target.

TARGET[in]

Name of the menuconfig target to be created.

Create a menuconfig target with the name specified by the TARGET option for an executable.

When esp-idf-kconfig >= MENUCONFIG_INLINE_MIN_KCONFIG_VERSION, the target runs a single kconfgen --menuconfig invocation (fused UI and post-processing). Older installs fall back to the legacy three-step flow.

idf_dbg

idf_dbg(<msg>...)

msg[in]

Message to print.

Print debug <msg>. Multiple messages are concatenated into a single message with no separator between them.

idf_die

idf_die(<msg>...)

msg[in]

Message to print.

Print error <msg> and abort the build process. Multiple messages are concatenated into a single message with no separator between them.

idf_flash_binary

idf_flash_binary(<binary>
                 TARGET <target>
                 [NAME <name>]
                 [FLASH])

binary[in]

Binary image target for which to create flash target. The binary target is created by the idf_build_binary function or idf_sign_binary.

TARGET[in]

The name of the flash target that will be created for the binary image.

NAME[in,opt]

An optional name to be used as a prefix for the file containing arguments for esptool, and as a logical name for the binary in flasher_args.json. If not specified, the name of the TARGET is used.

FLASH[in,opt]

If specified, the binary will also be added to the global flash target.

Create a new flash target for binary using the name specified in the TARGET option. The file path of the binary image should be stored in the BINARY_PATH property of the binary target.

idf_msg

idf_msg(<msg>...)

msg[in]

Message to print.

Print status <msg>. Multiple messages are concatenated into a single message with no separator between them.

idf_warn

idf_warn(<msg>...)

msg[in]

Message to print.

Print warning <msg>. Multiple messages are concatenated into a single message with no separator between them.

Macros 

idf_project_default

idf_project_default()

Create a default project executable based on the main component and its transitive dependencies. The executable name is derived from the PROJECT_NAME variable, which by default uses the CMAKE_PROJECT_NAME value specified in the CMake's project() call.

Generate the binary image for the executable, signed or unsigned based on the configuration, and add flash targets for it.

idf_project_init

idf_project_init()

Initialize settings that need to be configured after the project() function is called. This must occur after the project() function and before any other build system functions. It initializes the PROJECT_NAME and PROJECT_VER build properties, as well as all default C, CXX, and ASM compile options, link options, and compile definitions.

This macro also includes project_include.cmake files for the discovered components, as these files define project-wide functionality that needs to be available before any component's CMakeLists.txt is evaluated. The project_include.cmake files should be evaluated in the global scope. Therefore, this is defined as a macro and should be called only from the global scope or from within another macro.

Variables 

COMPONENT_LIB: The cmakev1-compatible alias of COMPONENT_TARGET. It holds the same value and refers to the same library target.

COMPONENT_NAME: The name of the component being evaluated, which is the name of its directory.

COMPONENT_TARGET: The name of the library target that the component must create, for example with add_library. The build system sets this variable in the component's scope when the component is evaluated, and links the created target into the component's interface target so that other components can depend on it.

ESP_PLATFORM: Set to 1 on any build driven by idf.py, which passes -DESP_PLATFORM=1 to CMake as a cache variable. It is therefore defined throughout the project, in both the top-level and component CMakeLists.txt files, and is also added as a compile definition so that source code can test it with #ifdef ESP_PLATFORM. Use it to detect that the build is driven by ESP-IDF, for example to guard ESP-IDF-specific code in a project that can also build as a plain host application.

IDF_BUILD_V2: Set to y when the project is built with the CMake-based build system v2. Use it to write component code that works with both v1 and v2, for example if(IDF_BUILD_V2). It is also exported as an environment variable and stored as a build property.

IDF_BUILD_VER: The major version number of the build system, 2 for v2.

IDF_BUILD_VER_TAG: The build system version tag, v2 for v2.

Build Properties 

Build properties are global to the project and are read and written with idf_build_get_property and idf_build_set_property.

ASM_COMPILE_OPTIONS: Compile options applied to all components, for assembly only.

BUILD_DIR: Absolute path to the build directory.

COMPILE_DEFINITIONS: Preprocessor definitions applied to all components.

COMPILE_OPTIONS: Compile options applied to all components, for all languages.

COMPONENTS_DISCOVERED: List of the names of all discovered components.

COMPONENTS_INCLUDED: List of the components that have been included (evaluated) in the build.

COMPONENT_INTERFACES: List of the interface targets of all discovered components.

CXX_COMPILE_OPTIONS: Compile options applied to all components, for C++ only.

C_COMPILE_OPTIONS: Compile options applied to all components, for C only.

IDF_COMPONENT_MANAGER: Whether the component manager is enabled (1) or disabled (0).

IDF_COMPONENT_OPTIONAL_REQUIRES_MODE: How idf_component_optional_requires is resolved, IMMEDIATE or DEFERRED.

IDF_PATH: Absolute path to the ESP-IDF directory.

IDF_TARGET: The target chip the project is built for, for example esp32.

IDF_TARGET_ARCH: The architecture of the target, xtensa or riscv (empty for the Linux host build).

IDF_TOOLCHAIN: The selected toolchain, gcc or clang.

IDF_VER: The ESP-IDF version string.

INCLUDE_DIRECTORIES: Include directories applied to all components.

LINKER_TYPE: The linker family, GNU or Darwin.

LINK_OPTIONS: Link options applied when linking the application.

PROJECT_DIR: Absolute path to the project directory.

PROJECT_NAME: The project name. Defaults to the name passed to CMake's project() command.

PROJECT_VER: The project version.

PYTHON: Path to the Python interpreter used by the build.

SDKCONFIG: Path to the project sdkconfig file.

SDKCONFIG_CMAKE: Path to the generated sdkconfig.cmake with the CONFIG_* CMake variables.

SDKCONFIG_DEFAULTS: List of sdkconfig.defaults files applied to the configuration.

SDKCONFIG_HEADER: Path to the generated sdkconfig.h with C and C++ preprocessor defines.

SDKCONFIG_JSON: Path to the generated sdkconfig.json.

Component Properties 

Component properties are attached to a single component and are read and written with idf_component_get_property and idf_component_set_property.

LDFRAGMENTS: List of linker fragment files contributed by the component. They are processed by the linker script generator. See 链接器脚本生成机制.

LINKER_SCRIPTS: List of linker script files added to the link command (with -T) for the component.

WHOLE_ARCHIVE: When set to a true value, every object file from the component's static library is kept in the final binary (linked with --whole-archive on GNU or -force_load on Apple). Useful for link-time registration, where object files may have no directly referenced symbols.

此文档对您有帮助吗？

反馈已收到，谢谢！
如果您有其他意见，欢迎填写乐鑫文档反馈表。

我们重视您的反馈。
您可以填写乐鑫文档反馈表告诉我们如何改进该文档。

API Reference

Functions

Macros

Variables

Build Properties

Component Properties

Functions 

Macros 

Variables 

Build Properties 

Component Properties 