Sudeep Mohanty
1d56d59a82
The cmakev2/features/import_lib example now builds cleanly with clang. Restore it to the supported target matrix and re-enable it in CI.
Build System v2 Examples
This directory contains examples demonstrating ESP-IDF Build System v2 (cmakev2). Build System v2 is the next-generation build system for ESP-IDF, offering improved architecture, better CMake integration, and enhanced features. Build System v2 attempts to be backward compatible with Build System v1 applications and components as much as possible. More information about Build System v2 can be found in the ESP-IDF Programming Guide under API Guides → Build System v2.
Note: Build System v2 is currently a Technical Preview.
Getting Started
Migrating an Existing Project
Change your project's CMakeLists.txt from:
# Build System v1
cmake_minimum_required(VERSION 3.22)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my_project)
To:
# Build System v2
cmake_minimum_required(VERSION 3.22)
include($ENV{IDF_PATH}/tools/cmakev2/idf.cmake)
project(my_project C CXX ASM)
idf_project_default()
This update is sufficient for most ESP-IDF projects. Components and application code remain unchanged.
Building Examples
Building any cmakev2 example follows the standard workflow:
cd examples/build_system/cmakev2/get-started/<example_name>
idf.py set-target <target>
idf.py build
idf.py flash monitor
Get-Started Examples
These examples mirror the ones in examples/get-started/ but use Build System v2.
hello_world
The simplest ESP-IDF project with cmakev2. It prints "Hello World" and demonstrates the minimal project structure required: a CMakeLists.txt with idf_project_default() and a main component. Start here to understand how a basic v2 project is set up.
Build System Features Examples
These examples demonstrate advanced build system capabilities unique to or enhanced in cmakev2. The components used in the examples in this section are registered with idf_component_register, which ensures that newly written components remain compatible with Build System v1.
component_manager
Shows how to use the ESP Component Registry with cmakev2. Declares dependencies in idf_component.yml, which are automatically downloads from ESP Component Registry during the build.
import_lib
Demonstrates importing third-party CMake libraries using CMake's ExternalProject_Add() module. The example downloads and builds tinyxml2 from GitHub, wraps it as an IDF component, and uses it to parse XML data. This approach is recommended for C++ libraries that use exceptions, as it properly handles ESP-IDF's C++ runtime integration through PRIV_REQUIRES cxx. For simpler C libraries, see import_lib_direct which demonstrates direct integration without component wrappers.
import_prebuilt
Shows how to import pre-compiled static libraries into your project using add_prebuilt_library(). The example includes a prebuilt/ directory containing a component that gets compiled separately, with its output (libprebuilt.a and headers) consumed by the main application. Useful for distributing proprietary libraries or speeding up builds with pre-compiled components.
multi_config
Demonstrates building multiple configurations of a single application using CMake presets. The example defines development and production presets, each with different sdkconfig.defaults files, separate build directories, and conditional source file compilation. Useful for building binaries for different product variants or deployment environments from one codebase.
Build with presets:
idf.py --preset default build # Development build
idf.py --preset prod1 build # Product 1 build
idf.py --preset prod2 build # Product 2 build
plugins
Demonstrates link-time plugin registration using the WHOLE_ARCHIVE component property. Plugins register themselves automatically at startup using __attribute__((constructor)) functions, without requiring explicit function calls from the main application. The example shows both dynamic registration (constructor functions) and static registration (linker sections with KEEP()). Useful for building extensible applications where plugins can be added or removed by simply including or excluding components.
idf_as_lib
Shows how to use ESP-IDF components as a library in external CMake projects. The example showcases how a non-IDF project can invoke the ESP-IDF build system to create a library which the executable can link against.
cmakev2-Specific Examples
The following examples demonstrate capabilities that are unique to Build System v2 and cannot be achieved with Build System v1.
conditional_component
features/conditional_component/
Demonstrates conditional component inclusion driven by Kconfig options, with all components written as pure CMake static libraries (no idf_component_register).
multi_binary
Demonstrates building multiple independent firmware binaries from a single project in one build command. Each binary has its own entry point, component dependencies, and flash target.
The project defines two applications (app1 and app2) with shared and distinct components:
Build and flash:
idf.py build # Creates both app1.bin and app2.bin
idf.py app1-flash monitor # Flash and monitor app1
idf.py app2-flash monitor # Flash and monitor app2
This is useful for creating firmware variants with different features, manufacturing test firmware alongside production firmware, or modular applications where different binaries serve different purposes.
import_lib_direct
Demonstrates a cmakev2-specific capability of importing external CMake libraries directly at the project level using FetchContent without wrapping them as IDF components. The example downloads lwjson, a lightweight JSON parser, and links it directly to the main component using standard CMake target_link_libraries(). This pattern works well for pure C libraries and simplifies third-party library integration.
Further Reading
For comprehensive documentation on Build System v2 APIs, migration details, and advanced usage, see the Build System v2 guide in the ESP-IDF Programming Guide under API Guides → Build System v2.
Contributing
When adding new examples:
- Use
cmakev2APIs where applicable - Include a README.md explaining the example
- Test on multiple targets (esp32, esp32c3, esp32s3)
- Document which
cmakev2features are demonstrated