diff --git a/examples/build_system/cmakev2/README.md b/examples/build_system/cmakev2/README.md index cc8c6dcdf8f..e480b8d1a8c 100644 --- a/examples/build_system/cmakev2/README.md +++ b/examples/build_system/cmakev2/README.md @@ -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 diff --git a/examples/build_system/cmakev2/features/import_prebuilt/CMakeLists.txt b/examples/build_system/cmakev2/features/import_prebuilt/CMakeLists.txt new file mode 100644 index 00000000000..e4e7d0a254f --- /dev/null +++ b/examples/build_system/cmakev2/features/import_prebuilt/CMakeLists.txt @@ -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() diff --git a/examples/build_system/cmakev2/features/import_prebuilt/README.md b/examples/build_system/cmakev2/features/import_prebuilt/README.md new file mode 100644 index 00000000000..9175b149a93 --- /dev/null +++ b/examples/build_system/cmakev2/features/import_prebuilt/README.md @@ -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` diff --git a/examples/build_system/cmakev2/features/import_prebuilt/main/CMakeLists.txt b/examples/build_system/cmakev2/features/import_prebuilt/main/CMakeLists.txt new file mode 100644 index 00000000000..6c0888f23c2 --- /dev/null +++ b/examples/build_system/cmakev2/features/import_prebuilt/main/CMakeLists.txt @@ -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) diff --git a/examples/build_system/cmakev2/features/import_prebuilt/main/main.c b/examples/build_system/cmakev2/features/import_prebuilt/main/main.c new file mode 100644 index 00000000000..7ba461af7c7 --- /dev/null +++ b/examples/build_system/cmakev2/features/import_prebuilt/main/main.c @@ -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(); +} diff --git a/examples/build_system/cmakev2/features/import_prebuilt/main/project_include.cmake b/examples/build_system/cmakev2/features/import_prebuilt/main/project_include.cmake new file mode 100644 index 00000000000..a724d85f901 --- /dev/null +++ b/examples/build_system/cmakev2/features/import_prebuilt/main/project_include.cmake @@ -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() diff --git a/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/CMakeLists.txt b/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/CMakeLists.txt new file mode 100644 index 00000000000..db665b1db05 --- /dev/null +++ b/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/CMakeLists.txt @@ -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() diff --git a/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/components/prebuilt/CMakeLists.txt b/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/components/prebuilt/CMakeLists.txt new file mode 100644 index 00000000000..b58f0b3f062 --- /dev/null +++ b/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/components/prebuilt/CMakeLists.txt @@ -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 $ ${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...") diff --git a/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/components/prebuilt/prebuilt.c b/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/components/prebuilt/prebuilt.c new file mode 100644 index 00000000000..46fad63131f --- /dev/null +++ b/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/components/prebuilt/prebuilt.c @@ -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); +} diff --git a/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/components/prebuilt/prebuilt.h b/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/components/prebuilt/prebuilt.h new file mode 100644 index 00000000000..9f0abe05825 --- /dev/null +++ b/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/components/prebuilt/prebuilt.h @@ -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); diff --git a/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/main/CMakeLists.txt b/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/main/CMakeLists.txt new file mode 100644 index 00000000000..6ee0c4445ae --- /dev/null +++ b/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/main/CMakeLists.txt @@ -0,0 +1,3 @@ +idf_component_register(SRCS "main.c" + PRIV_REQUIRES prebuilt esptool_py + INCLUDE_DIRS "") diff --git a/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/main/main.c b/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/main/main.c new file mode 100644 index 00000000000..7fc141a1315 --- /dev/null +++ b/examples/build_system/cmakev2/features/import_prebuilt/prebuilt/main/main.c @@ -0,0 +1,11 @@ +/* + * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Unlicense OR CC0-1.0 + */ +#include + +void app_main(void) +{ + printf("Hello World!\n"); +}