feat(cmakev2): Added import_prebuilt example for cmakev2

This commit updates the examples/build_system/cmake/import_prebuilt example for the new build system and adds the newly created example at examples/build_system/cmakev2/features/import_prebuilt.
2026-10-02 03:00:34 +03:00 · 2026-02-24 11:21:19 +01:00
parent 5d7fdc7c78
commit d9aa6adbfc
12 changed files with 150 additions and 1 deletions
@@ -109,7 +109,7 @@ Demonstrates using ESP-IDF component manager with `cmakev2`
 ---

 ### import_lib
-**Location:** [import_lib/](.feature/import_lib/)
+**Location:** [import_lib/](./features/import_lib/)

 Demonstrates importing external third-party libraries using CMake's `ExternalProject` module.

@@ -119,6 +119,17 @@ Demonstrates importing external third-party libraries using CMake's `ExternalPro

 ---

+### import_prebuilt
+**Location:** [import_prebuilt/](./features/import_prebuilt/)
+
+Demonstrates importing a prebuilt static library in the ESP-IDF build system with `cmakev2`.
+
+**Key Concepts:** `add_prebuilt_library()`, cross-project component sharing, dependency management
+
+**When to use:** When you have a pre-compiled component library that you want to use in your project.
+
+---
+
 ## Build System v2 API Quick Reference

 ### Project Setup
@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.22)
+
+include($ENV{IDF_PATH}/tools/cmakev2/idf.cmake)
+project(import_prebuilt C CXX ASM)
+idf_project_default()
@@ -0,0 +1,40 @@
+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 | ESP32-S31 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- | --------- |
+
+# Import Prebuilt Library Example
+
+This example illustrates how to import a prebuilt static library in the ESP-IDF build system.
+
+## Example Flow
+
+Users need to first build the project in the [prebuilt](prebuilt) subdirectory:
+
+```
+cd prebuilt
+idf.py build
+```
+
+This builds a component named [prebuilt](prebuilt/components/prebuilt), which has private dependency on ESP-IDF components `spi_flash`, `log` and `app_update` (see [its CMakeLists.txt](prebuilt/components/prebuilt/CMakeLists.txt)). Once built, the archive file `libprebuilt.a`, along with the header file `prebuilt.h`, is automatically copied to the [`main` component](main) of this example project. 
+
+The [`main` component's CMakeLists.txt](main/CMakeLists.txt) demonstrates how to import `libprebuilt.a` and link it to `main` so that the definitions inside can be used. 
+It also demonstrates how to specify the same dependencies the original component had so as to properly resolve symbols used inside the prebuilt library.
+
+Users can then return to this directory and build the main example:
+
+```
+cd ..
+idf.py build
+```
+
+
+### Output
+
+The example simply outputs the current running partition.
+
+```
+I (319) prebuilt: The running partition is 'factory'!
+```
+
+---
+
+There is a discussion on importing prebuilt libraries in the programming guide under `API Guides` -> `Build System` -> `Using Prebuilt Libraries with Components`
@@ -0,0 +1,10 @@
+idf_component_register(SRCS "main.c"
+                    INCLUDE_DIRS ".")
+
+# Import the library, specifying a target name and the library path.
+# The private dependencies of the library is also specified.
+add_prebuilt_library(prebuilt "libprebuilt.a"
+             PRIV_REQUIRES spi_flash app_update log)
+
+# `main` calls a function from the library, so link it to `main`
+target_link_libraries(${COMPONENT_LIB} PRIVATE prebuilt)
@@ -0,0 +1,14 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+
+// Include the prebuilt library's header file so as to be able
+// to reference `prebuilt_func` here.
+#include "prebuilt.h"
+
+void app_main(void)
+{
+    prebuilt_func();
+}
@@ -0,0 +1,16 @@
+# For users checking this example, ignore the following code. This is so that
+# the prebuilt project is built automatically in ESP-IDF CI.
+if("$ENV{CI}")
+    # otherwise these file won't be rebuilt when switching the built target within the same job
+    file(REMOVE
+                ${CMAKE_SOURCE_DIR}/prebuilt/sdkconfig
+                ${CMAKE_SOURCE_DIR}/main/libprebuilt.a
+                ${CMAKE_SOURCE_DIR}/main/prebuilt.h
+        )
+    file(REMOVE_RECURSE ${CMAKE_SOURCE_DIR}/prebuilt/build)
+
+    idf_build_get_property(python PYTHON)
+    idf_build_get_property(idf_path IDF_PATH)
+    execute_process(COMMAND ${python} "${idf_path}/tools/idf.py" build
+                    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/prebuilt)
+endif()
@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.22)
+
+include($ENV{IDF_PATH}/tools/cmakev2/idf.cmake)
+project(prebuilt C CXX ASM)
+idf_project_default()
@@ -0,0 +1,10 @@
+idf_component_register(SRCS prebuilt.c
+                       INCLUDE_DIRS "."
+                       PRIV_REQUIRES app_update spi_flash log)
+
+# After build, copy the archive file and header file to parent example directory's main component
+add_custom_command(TARGET ${COMPONENT_LIB}
+                  POST_BUILD
+                  COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_FILE:${COMPONENT_LIB}> ${CMAKE_SOURCE_DIR}/../main
+                  COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_LIST_DIR}/prebuilt.h ${CMAKE_SOURCE_DIR}/../main
+                  COMMENT "Copying built archive file and header to parent example directory...")
@@ -0,0 +1,16 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+#include "esp_ota_ops.h"
+#include "esp_partition.h"
+#include "esp_log.h"
+
+const char *TAG = "prebuilt";
+
+void prebuilt_func(void)
+{
+    const esp_partition_t* running_partition = esp_ota_get_running_partition();
+    ESP_LOGI(TAG, "The running partition is '%s'!", running_partition->label);
+}
@@ -0,0 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+#pragma once
+
+void prebuilt_func(void);
@@ -0,0 +1,3 @@
+idf_component_register(SRCS "main.c"
+                    PRIV_REQUIRES prebuilt esptool_py
+                    INCLUDE_DIRS "")
@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+#include <stdio.h>
+
+void app_main(void)
+{
+    printf("Hello World!\n");
+}