Chapter 4. API Guides
4.4.17 Writing Pure CMake Components
The ESP-IDF build system“wraps”CMake with the concept of“components”, and helper functions to automatically
integrate these components into a project build.
However, underneath the concept of “components”is a full CMake build system. It is also possible to make a
component which is pure CMake.
Here is an example minimal “pure CMake”component CMakeLists file for a component named json:
add_library(json STATIC
cJSON/cJSON.c
cJSON/cJSON_Utils.c)
target_include_directories(json PUBLIC cJSON)
• This is actually an equivalent declaration to the IDF json component /components/json/CMakeLists.txt.
• This file is quite simple as there are not a lot of source files. For components with a large number of files, the
globbing behaviour of ESP-IDF’s component logic can make the component CMakeLists style simpler.)
• Any time a component adds a library target with the component name, the ESP-IDF build system will auto-
matically add this to the build, expose public include directories, etc. If a component wants to add a library
target with a different name, dependencies will need to be added manually via CMake commands.
4.4.18 Using Third-Party CMake Projects with Components
CMake is used for a lot of open-source C and C++ projects —code that users can tap into for their applications.
One of the benefits of having a CMake build system is the ability to import these third-party projects, sometimes
even without modification! This allows for users to be able to get functionality that may not yet be provided by a
component, or use another library for the same functionality.
Importing a library might look like this for a hypothetical library foo to be used in the main component:
# Register the component
idf_component_register(...)
# Set values of hypothetical variables that control the build of `foo`
set(FOO_BUILD_STATIC OFF)
set(FOO_BUILD_TESTS OFF)
# Create and import the library targets
add_subdirectory(foo)
# Publicly link `foo` to `main` component
target_link_libraries(main PUBLIC foo)
For an actual example, take a look at build_system/cmake/import_lib. Take note that what needs to be done in order
to import the library may vary. It is recommended to read up on the library’s documentation for instructions on
how to import it from other projects. Studying the library’s CMakeLists.txt and build structure can also be helpful.
It is also possible to wrap a third-party library to be used as a component in this manner. For example, the mbedtls
component is a wrapper for Espressif’s fork of mbedtls. See its component CMakeLists.txt .
The CMake variable ESP_PLATFORM is set to 1 whenever the ESP-IDF build system is being used. Tests such as
if (ESP_PLATFORM) can be used in generic CMake code if special IDF-specific logic is required.
Using ESP-IDF components from external libraries
The above example assumes that the external library foo (or tinyxml in the case of the import_lib example)
doesn’t need to use any ESP-IDF APIs apart from common APIs such as libc, libstdc++, etc. If the external library
needs to use APIs provided by other ESP-IDF components, this needs to be specified in the external CMakeLists.txt
file by adding a dependency on the library target idf::<componentname>.
Espressif Systems 1289
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General