Glossary

This page defines the terms used throughout the Build System v2 documentation. The terms are local to Build System v2; where a term also has a more general meaning in ESP-IDF, the definition here is the one that applies in this documentation.

application (app)

The executable the build system produces from a set of components, together with the binary image flashed to the target. A project usually builds two applications: the project application (the firmware) and the bootloader. app is a synonym.

backward-compatible component

A component declared with idf_component_register. It builds under both Build System v1 and v2, as long as it stays within the features that v1 also supports. Contrast native component.

build event callback

A function a component registers with idf_component_register_build_event_callback to run at a defined point in the build. The only event currently supported is POST_ELF, fired after the executable is linked and before the binary image is generated. See Using Build Event Callbacks.

build property

A setting that is global to the project, stored on the idf_build_properties target and accessed with idf_build_get_property and idf_build_set_property. Contrast component property and library property.

common components

The core components, such as freertos and log, that the build system adds as dependencies of every component declared with idf_component_register, without an explicit REQUIRES. A native component receives nothing automatically and must include every component it uses, including these.

component

A reusable, separately compiled unit of code: a directory that contains a CMakeLists.txt file. The build system compiles each component into a library and links the ones the application needs. The component's name is the name of its directory.

component library target

The library target a component creates, typically with add_library, and whose name the build system passes to the component in the COMPONENT_TARGET variable (also available as COMPONENT_LIB). It holds the component's compiled code. Distinct from the interface target.

component property

A setting attached to a single component, stored on its interface target and accessed with idf_component_get_property and idf_component_set_property. Examples are WHOLE_ARCHIVE, LDFRAGMENTS, and LINKER_SCRIPTS.

component source

A location the build system searches for components, each with a precedence. From highest to lowest: project_components (the project's main and components directories), project_extra_components (directories in EXTRA_COMPONENT_DIRS), project_managed_components (fetched by the component manager), and idf_components (bundled with ESP-IDF). A component from a higher-precedence source shadows a same-named component from a lower one. See Design and Architecture.

configuration (sdkconfig)

The project's Kconfig-based settings, persisted in the sdkconfig file and exposed to source code and CMakeLists.txt files as CONFIG_* options. In v2 the configuration is generated from the Kconfig of every discovered component, not only the ones in the build. See Project Configuration.

discovery

Registering a component with the build system: recording its directory, Kconfig files, and project_include.cmake, and creating its interface target. A discovered component is known and configurable, but is not compiled. Contrast inclusion.

inclusion

Bringing a discovered component into the build by evaluating it: the build system calls add_subdirectory on it, which runs its CMakeLists.txt and creates its component library target. Only included components are compiled and linked. idf_component_include performs the inclusion. Contrast discovery.

interface alias

The idf::<name> alias of a component's interface target. It is the canonical, readable way for other components to refer to a component, for example idf::spi_flash.

interface target

The idf_<name> target created for a component at discovery. It carries the component's properties and is what other components link against, usually through its interface alias idf::<name>. Distinct from the component library target.

library

An interface library produced by idf_build_library that bundles a set of components and their transitive dependencies. Linking it into an executable brings in those components' code, include paths, and link options. Not to be confused with a component's own library target or the final binary image.

library property

A setting recorded for a single library produced by idf_build_library, such as the list of components it linked. Contrast build property and component property.

linker fragment

A file, contributed through a component's LDFRAGMENTS property, that the linker script generator uses to place a component's code and data into memory regions. Distinct from a linker script, which is added with LINKER_SCRIPTS. See 链接器脚本生成机制.

main component

The component named main from which idf_project_default builds the default application. Building from main is a convention of idf_project_default, not a requirement of the build system; a project that uses the lower-level API can build its application from any component.

native component

A component written as a plain CMake static library, created directly with add_library instead of idf_component_register. It has full access to native CMake, but on its own builds only under v2. Contrast backward-compatible component.

optional dependency

A dependency declared with idf_component_optional_requires that links another component only when it is part of the build. v2 resolves it in one of two modes, IMMEDIATE or DEFERRED; see The Behavior of idf_component_optional_requires has Changed.

project

A directory that contains a top-level CMakeLists.txt, usually a main component, and optionally a components directory with additional components. It builds into one or more applications. See Creating a New Project.

single-pass evaluation

The v2 design property that each component is evaluated exactly once, as ordinary CMake code. v1 instead evaluated components twice, with an early pass in CMake script mode. See Design and Architecture.

target

The chip the project is built for, for example esp32, selected with idf.py set-target and available as the IDF_TARGET build property and the CONFIG_IDF_TARGET option. The word "target" also refers to a CMake build target, as in interface target; this documentation uses "target" for the chip unless qualified.

此文档对您有帮助吗？