diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index ffd59b277..d57a71209 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -1020,6 +1020,28 @@ Espressif's fork of `mbedtls `_. See its :co The CMake variable ``ESP_PLATFORM`` is set to 1 whenever the ESP-IDF build system is being used. Tests such as ``if (ESP_PLATFORM)`` can be used in generic CMake code if special IDF-specific logic is required. +Using Prebuilt Libraries with Components +======================================== + +.. highlight:: cmake + +The ESP-IDF build system provides a utility function ``add_prebuilt_library`` for users to be able to easily import and use +prebuilt libraries:: + + add_prebuilt_library(target_name lib_path [REQUIRES req1 req2 ...] [PRIV_REQUIRES req1 req2 ...]) + +where: + +- ``target_name``- name that can be used to reference the imported library, such as when linking to other targets +- ``lib_path``- path to prebuilt library; may be an absolute or relative path to the component directory + +Optional arguments ``REQUIRES`` and ``PRIV_REQUIRES`` specify dependency on other components. These have the same meaning as the arguments for ``idf_component_register``. + +Take note that the prebuilt library must have been compiled for the same target as the consuming project. Configuration relevant to the prebuilt +library must also match. If not paid attention to, these two factors may contribute to subtle bugs in the app. + +For an example, take a look at :example:`build_system/cmake/import_prebuilt`. + Using ESP-IDF in Custom CMake Projects ====================================== diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake index dcd4e9fbf..5d3a8ebc6 100644 --- a/tools/cmake/utilities.cmake +++ b/tools/cmake/utilities.cmake @@ -258,3 +258,26 @@ function(add_c_compile_options) add_compile_options($<$:${option}>) endforeach() endfunction() + + +function(add_prebuilt_library target_name lib_path) + cmake_parse_arguments(_ "" "" "REQUIRES;PRIV_REQUIRES" ${ARGN}) + + get_filename_component(lib_path "${lib_path}" + ABSOLUTE BASE_DIR "${CMAKE_CURRENT_LIST_DIR}") + + add_library(${target_name} STATIC IMPORTED) + set_property(TARGET ${target_name} PROPERTY IMPORTED_LOCATION ${lib_path}) + + foreach(req ${__REQUIRES}) + idf_component_get_property(req_lib "${req}" COMPONENT_LIB) + set_property(TARGET ${target_name} APPEND PROPERTY LINK_LIBRARIES "${req_lib}") + set_property(TARGET ${target_name} APPEND PROPERTY INTERFACE_LINK_LIBRARIES "${req_lib}") + endforeach() + + foreach(req ${__PRIV_REQUIRES}) + idf_component_get_property(req_lib "${req}" COMPONENT_LIB) + set_property(TARGET ${target_name} APPEND PROPERTY LINK_LIBRARIES "${req_lib}") + set_property(TARGET ${target_name} APPEND PROPERTY INTERFACE_LINK_LIBRARIES "$") + endforeach() +endfunction() \ No newline at end of file