refactor(ulp): provide a ulp_project.cmake subproject wrapper API

Build ULP full subprojects through a dedicated entry file,
components/ulp/cmake/ulp_project.cmake, that wraps tools/cmakev2/idf.cmake
and layers a small ULP API on top, mirroring the cmakev2 layering:

  ulp_project_init      like idf_project_init (init, detect the ULP type,
                        reset the compile/link options inherited from the app)
  ulp_build_executable  like idf_build_executable, plus the embeddable
                        .bin/.h/.ld artifacts
  ulp_project_default   like idf_project_default (single-executable case)

A child project now includes this one file instead of idf.cmake and calls
these helpers directly, so idf_build_executable is used as-is for the
multi-binary case and the module-path indirection (include(IDFULPProject)
resolved via -DCMAKE_MODULE_PATH) is gone.

As a result:
- IDFULPProjectv2.cmake is removed; its setup moves into the wrapper.
- IDFULPProject.cmake becomes the CMake v1-only entry point.
- The ULP component no longer registers a POST_ELF callback; the binary
  artifacts are produced by ulp_build_executable.
- The v2 full-subproject examples (lp_core, riscv, fsm, multi_binary,
  combined) are updated to the new API.
- The ULP subproject API is documented in build-system-v2.rst.

Also fix a latent bug this exercises: idf_build_library emitted linker
scripts as "-T <name>" relying on a following "-L" search directory. GNU
ld only searches -L directories that precede -T, so the direct
esp32ulp-elf-ld link used for ULP FSM failed to open the script. Emit the
absolute path instead, matching what the CMake v1 ULP build already does.

Finally, replace the parent-argument bypass loop that used to live in
IDFULPProjectv2.cmake with --no-warn-unused-cli on the child configure,
and stop passing the unused IDF_PARENT_BUILD_DIR.

Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
This commit is contained in:
Frantisek Hrbata
2026-07-15 09:34:05 +09:00
committed by Renz Bagaporo
parent ceaa0b7a3d
commit a9ea4f1105
13 changed files with 233 additions and 142 deletions
@@ -1,8 +1,7 @@
cmake_minimum_required(VERSION 3.22)
include(${IDF_PATH}/tools/cmakev2/idf.cmake)
include(${IDF_PATH}/components/ulp/cmake/ulp_project.cmake)
project(${IDF_DEFAULT_PROJECT_NAME} ASM)
include(IDFULPProject)
ulp_project_default()
@@ -1,8 +1,7 @@
cmake_minimum_required(VERSION 3.22)
include(${IDF_PATH}/tools/cmakev2/idf.cmake)
include(${IDF_PATH}/components/ulp/cmake/ulp_project.cmake)
project(${IDF_DEFAULT_PROJECT_NAME} C CXX ASM)
include(IDFULPProject)
ulp_project_default()
@@ -1,8 +1,7 @@
cmake_minimum_required(VERSION 3.22)
include(${IDF_PATH}/tools/cmakev2/idf.cmake)
include(${IDF_PATH}/components/ulp/cmake/ulp_project.cmake)
project(${IDF_DEFAULT_PROJECT_NAME} ASM)
include(IDFULPProject)
ulp_project_default()
@@ -1,8 +1,7 @@
cmake_minimum_required(VERSION 3.22)
include(${IDF_PATH}/tools/cmakev2/idf.cmake)
include(${IDF_PATH}/components/ulp/cmake/ulp_project.cmake)
project(${IDF_DEFAULT_PROJECT_NAME} C CXX ASM)
include(IDFULPProject)
ulp_project_default()
@@ -3,11 +3,22 @@
# ULP LP-Core Multi-Binary Build System Example
This example demonstrates a CMake v2 ULP full subproject that builds multiple ULP binaries from one ULP child project. The ULP project uses the lower-level IDF build APIs instead of `ulp_project_default()`: it calls `idf_project_init()`, prepares the child build with `ulp_prepare_build()`, creates a shared ULP component library with `idf_build_library()`, and creates two ULP executables with `idf_build_executable()`. The `ulp` component generates the binary artifacts for each executable.
This example demonstrates a CMake v2 ULP full subproject that builds multiple
ULP binaries from one ULP child project. The ULP project uses the lower-level
ULP build APIs instead of `ulp_project_default()`: it calls
`ulp_project_init()`, creates two ULP executables with
`ulp_build_executable()`, and generates the binary artifacts for each
executable with `ulp_build_binary()`.
The main application embeds both generated ULP binaries, runs the first one to calculate an addition result, then loads and runs the second one to calculate a multiplication result.
The main application embeds both generated ULP binaries, runs the first one to
calculate an addition result, then loads and runs the second one to calculate a
multiplication result.
Both ULP binaries define a global variable named `result`. Because no explicit `PREFIX` is passed to `ulp_add_project()`, the build system gives each binary a binary-scoped default symbol prefix, so the parent app can read `ulp_add_result` and `ulp_multiply_result` without the generated linker exports colliding.
Both ULP binaries define a global variable named `result`. Because no explicit
`PREFIX` is passed to `ulp_add_project()`, the build system gives each binary a
binary-scoped default symbol prefix, so the parent app can read
`ulp_add_result` and `ulp_multiply_result` without the generated linker exports
colliding.
## Example Output
@@ -1,23 +1,17 @@
cmake_minimum_required(VERSION 3.22)
include(${IDF_PATH}/tools/cmakev2/idf.cmake)
include(${IDF_PATH}/components/ulp/cmake/ulp_project.cmake)
project(${IDF_DEFAULT_PROJECT_NAME} C CXX ASM)
include(IDFULPProject)
ulp_project_init()
idf_project_init()
ulp_prepare_build()
idf_build_library(ulp_shared_library
COMPONENTS ulp_shared)
idf_build_executable(add
COMPONENTS ulp_add_main
ulp_build_executable(add
COMPONENTS ulp_add_main ulp_shared
MAPFILE_TARGET add_mapfile)
target_link_libraries(add PRIVATE ulp_shared_library)
ulp_build_binary(add)
idf_build_executable(multiply
COMPONENTS ulp_multiply_main
ulp_build_executable(multiply
COMPONENTS ulp_multiply_main ulp_shared
MAPFILE_TARGET multiply_mapfile)
target_link_libraries(multiply PRIVATE ulp_shared_library)
ulp_build_binary(multiply)
@@ -1,8 +1,7 @@
cmake_minimum_required(VERSION 3.22)
include(${IDF_PATH}/tools/cmakev2/idf.cmake)
include(${IDF_PATH}/components/ulp/cmake/ulp_project.cmake)
project(${IDF_DEFAULT_PROJECT_NAME} C CXX ASM)
include(IDFULPProject)
ulp_project_default()