From 989dac1e6450fab93685208e7ad5ec2ba6a7c079 Mon Sep 17 00:00:00 2001
From: Renz Christian Bagaporo <renz@espressif.com>
Date: Thu, 28 Nov 2019 14:38:16 +0800
Subject: [PATCH] cmake: implement utility to import prebuilt libraries

---
 docs/en/api-guides/build-system.rst | 22 ++++++++++++++++++++++
 tools/cmake/utilities.cmake         | 23 +++++++++++++++++++++++
 2 files changed, 45 insertions(+)

diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst
index ffd59b2777..d57a712096 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 <https://github.com/ARMmbed/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 dcd4e9fbf5..5d3a8ebc69 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -258,3 +258,26 @@ function(add_c_compile_options)
         add_compile_options($<$<COMPILE_LANGUAGE:C>:${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 "$<LINK_ONLY:${req_lib}>")
+    endforeach()
+endfunction()
\ No newline at end of file