# 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_project_add_default_build_component

      idf_project_add_default_build_component(<component>...)

  component[in]

  > Component name to include in the executable created by idf_project_default.

  Add components to the default project executable. This is intended for components that need to be built based on sdkconfig alone, for example to provide linker-section registrations, without making another component depend on them. This is e.g. the case with coredump which is simply enabled based on CONFIG_ESP_COREDUMP_ENABLE option, but no other components depend it.

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_DEFAULT_EXTRA_COMPONENTS

  Internal list of additional components to include in the executable created by `idf_project_default`. Components should use `idf_project_add_default_build_component` rather than modifying this property directly.

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.

NO_KASAN

  When set to a true value, the component is compiled without Kernel Address Sanitizer instrumentation (`-fno-sanitize=kernel-address`) while `CONFIG_COMPILER_KASAN` is enabled. Set it on a component that runs before the sanitizer shadow is initialised, executes with the flash cache disabled, or is otherwise too low-level to instrument.

  The low-level ESP-IDF components are excluded already; the built-in set is defined in `tools/cmake/kasan.cmake` and shared with the CMake-based build system v1, which honours this property as well.

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.

此文档对您有帮助吗？

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

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