Chapter 4. API Guides
for all components. The order should be deterministic given the same set of components and component
dependencies.
• The value of BUILD_COMPONENTS is logged by CMake as “Component names: “
• Configuration is then evaluated for the components included in the build.
• Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the
component libraries to the build.
Component Dependency Order The order of components in the BUILD_COMPONENTS variable determines
other orderings during the build:
• Order that project_include.cmake files are included into the project.
• Order that the list of header paths is generated for compilation (via -I argument). (Note that for a given
component’s source files, only that component’s dependency’s header paths are passed to the compiler.)
4.4.9 Overriding Parts of the Project
project_include.cmake
For components that have build requirements which must be evaluated before any component CMakeLists files are
evaluated, you can create a file called project_include.cmake in the component directory. This CMake file
is included when project.cmake is evaluating the entire project.
project_include.cmake files are used inside ESP-IDF, for defining project-wide build features such as es-
ptool.py command line arguments and the bootloader “special app”.
Unlike component CMakeLists.txt files, when including a project_include.cmake file the current
source directory (CMAKE_CURRENT_SOURCE_DIR and working directory) is the project directory. Use the vari-
able COMPONENT_DIR for the absolute directory of the component.
Note that project_include.cmake isn’t necessary for the most common component uses - such as adding
include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the
CMakeLists.txt file itself. See Optional Project Variables for details.
project_include.cmake files are included in the order given in BUILD_COMPONENTS variable (as logged
by CMake). This means that a component’s project_include.cmake file will be included after it’s all
dependencies’project_include.cmake files, unless both components are part of a dependency cycle. This
is important if a project_include.cmake file relies on variables set by another component. See also above.
Take great care when setting variables or targets in a project_include.cmake file. As the values are included
into the top-level project CMake pass, they can influence or break functionality across all components!
KConfig.projbuild
This is an equivalent to project_include.cmake for Component Configuration KConfig files. If you want
to include configuration options at the top-level of menuconfig, rather than inside the “Component Configuration”
sub-menu, then these can be defined in the KConfig.projbuild file alongside the CMakeLists.txt file.
Take care when adding configuration values in this file, as they will be included across the entire project configuration.
Where possible, it’s generally better to create a KConfig file for Component Configuration.
project_include.cmake files are used inside ESP-IDF, for defining project-wide build features such as es-
ptool.py command line arguments and the bootloader “special app”.
4.4.10 Configuration-Only Components
Special components which contain no source files, only Kconfig.projbuild and KConfig, can have a one-line
CMakeLists.txt file which calls the function idf_component_register() with no arguments specified.
This function will include the component in the project build, but no library will be built and no header files will be
added to any include paths.
Espressif Systems 1282
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General