Build System `cmakev2` - Technical Preview (IDFGH-16748)

[dobairoland]

We are excited to announce the availability of the ESP-IDF Build System v2 in Technical Preview state. This new build system is designed to address limitations in the current build system while providing better integration capabilities for developers working with CMake-based ecosystems.

Build System v2 represents a significant evolution of the ESP-IDF build infrastructure, focusing on improved compatibility with standard CMake practices and enhanced flexibility for advanced use cases. While maintaining backward compatibility with components written for the current build system (v1), v2 introduces architectural improvements that make it easier to integrate ESP-IDF into larger CMake-based projects and frameworks.

Key Features

The most significant enhancement in Build System v2 is the ability to use Kconfig configuration variables to specify component dependencies. This allows components to conditionally declare their requirements based on project configuration, providing much greater flexibility in component composition.

Build System v2 also supports writing components using a native CMake approach, giving developers more control and enabling them to leverage standard CMake patterns and best practices. Components can now be created using standard CMake functions like add_library() and target_link_libraries(), while still benefiting from ESP-IDF's component management infrastructure.

At present, Build System v2 offers essential functionality that is sufficient to begin experimenting with it. The system is designed with extensibility in mind and is planned to provide additional features in the future, such as building multiple libraries and binaries from a single project configuration.

Comparison with the current default build system of ESP-IDF

The current default build system (v1) uses a two-stage component evaluation process. In the first stage, components are evaluated early using CMake script mode to build a dependency graph. This early evaluation phase imposes certain restrictions: components cannot express dependencies based on Kconfig variables because configuration values are not yet available, and the script mode limits which CMake commands can be used.

Build System v2 eliminates this early component evaluation phase entirely. Components are now evaluated on-demand as they are needed, using standard CMake add_subdirectory() calls. This change removes the restrictions on when and how components can declare dependencies, allowing for more dynamic and configuration-driven component composition.

The removal of early evaluation also simplifies the build system architecture. In v1, components are collected in the BUILD_COMPONENTS build property during early evaluation, then evaluated again later. In v2, components are discovered and evaluated in a single pass, making the build process more straightforward and predictable.

While v2 aims to maintain backward compatibility with v1 components, there are some design differences that may require adjustments for certain advanced use cases. Most components written for v1 should work without modification, but components that rely on v1-specific behaviors (such as the BUILD_COMPONENTS property or early evaluation timing) will need updates to work with v2.

Availability

Build System v2 is available in:

• Latest master branch,
• release/v6.0 branch,
• the future v6.0 release.

To use Build System v2, include tools/cmakev2/idf.cmake in your project's CMakeLists.txt instead of the standard build system files.

How to Try It

Getting started with Build System v2 is straightforward. The minimal project CMakeLists.txt file looks like this:

cmake_minimum_required(VERSION 3.22)
include($ENV{IDF_PATH}/tools/cmakev2/idf.cmake)
project(myProject C CXX ASM)
idf_project_default()

The order of commands is important: first specify the CMake minimum version, then include the v2 build system file, then call project(), and finally call idf_project_default() to set up the default project executable.

For creating components, you can continue using idf_component_register() for compatibility with both v1 and v2, or you can use the native CMake approach with add_library() and idf_component_include() for v2-only components.

We encourage you to read the Build System v2 documentation to learn more about the available features, API reference, and migration guidance. You can also browse the implementation in the tools/cmakev2 directory to understand how the system works under the hood.

Feedback and Discussion

Build System v2 is currently available as a Technical Preview intended for testing and evaluation. We are actively seeking feedback from the community, especially from embedded developers who are integrating ESP-IDF into their CMake-based ecosystems, advanced users, component maintainers, and maintainers who integrate ESP-IDF into their frameworks.

Please try Build System v2 with your projects and share your experience. We are particularly interested in:

• Feedback: What works well? What doesn't?
• Suggestions: How can we improve the build system?
• Questions: What aspects need clarification?
• Use cases: What scenarios are not currently addressed?

Your input will help shape the future development of Build System v2. Please leave your comments, questions, and feedback in this issue thread.

[franz-ms-muc]

is #16013 addressed by this System ?