Improved handling of FIND_PACKAGE_ARGS in declarations

Allow the user to completely specify the additional find package arguments by implementing a "default to 'REQUIRED'" strategy: if nothing is specified a find_package(<content_name> REQUIRED) is run, otherwise the user has to specify the FULL argument set except <content_name>. For good measure a bit of validation is done. Updated the documentation accordingly.

CHANGELOG

- improved the handling of HFC's FIND_PACKAGE_ARGS in library declarations to allow more arguments to be passed (now search <version> can be specified among other things)

Change-Id: I213ae84308423de275bd701258b36ea7efcf0074

Author: pysco68

cmake/HermeticFetchContent.cmake

@@ -327,6 +327,36 @@ Commands
 
   Set the base directory for all the hermetic dependency build directory and related folders
 
+Fallback to system provided dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For use-cases in which you want to have the option to revert to a system provided library but still have the ability
+to build your own, you may set ``FORCE_SYSTEM_<content-name>`` to ``ON``. In this case Hermetic FetchContent will
+execute a CMake ``find_package(<content-name> REQUIRED)`` call during targets discovery. 
+
+If you need to specify arguments to ``find_package()`` you may add the ``FIND_PACKAGE_ARGS`` to the content declaration.
+
+  .. code-block:: cmake
+    set(FORCE_SYSTEM_boost ON) # <- take boost from the system, toggle this to OFF to have Boost built by your project
+    FetchContent_Declare(
+      boost
+      GIT_REPOSITORY https://github.com/boostorg/boost.git
+      GIT_TAG        ad09f667e61e18f5c31590941e748ac38e5a81bf   # that's v1.84
+    )
+
+    FetchContent_MakeHermetic(
+      boost
+      HERMETIC_BUILD_SYSTEM cmake
+      FIND_PACKAGE_ARGS "1.84 EXACT REQUIRED" # <- makes sure we take a 1.84 only from the system!
+    )
+
+    HermeticFetchContent_MakeAvailableAtBuildTime(boost)
+
+Note that in the special case of ``FORCE_SYSTEM_<content-name>=ON`` the context in which the find_package() will be
+run, will be slightly different from the normal context for hermetic builds. One major difference is that the Hermetic
+FetchContent will inject the project's ``CMAKE_MODULE_PATH`` into the toolchain extension in addition to forcing 
+``find_package()`` to search exclusively on the system through setting ``CMAKE_FIND_ROOT_PATH_MODE_*`` appropriately.
+
 Build introspection
 ^^^^^^^^^^^^^^^^^^^ 
 

cmake/modules/hfc_make_available_single.cmake

@@ -194,12 +194,22 @@ function(hfc_make_available_single content_name build_at_configure_time)
         HERMETIC_FIND_PACKAGES "${__PARAMS_HERMETIC_FIND_PACKAGES}"
         PROJECT_TOOLCHAIN_EXTENSION "${__PARAMS_HERMETIC_TOOLCHAIN_EXTENSION}"
         DESTINATION_TOOLCHAIN_PATH "${proxy_toolchain_path}"
-      ) 
+      )
+
+      if(__PARAMS_FIND_PACKAGE_ARGS)
+        set(findpackage_args "${__PARAMS_FIND_PACKAGE_ARGS}")
+      else()
+        set(findpackage_args "REQUIRED")
+      endif()
+
+      if(NOT findpackage_args MATCHES "REQUIRED")
+        hfc_log(WARNING "The FIND_PACKAGE_ARGS provided in the content declaration of ${content_name} do not contain the REQUIRED flag. This might cause the resulting targets to be empty if the dependency cannot be resolve. (Valud of FIND_PACKAGE_ARGS='${__PARAMS_FIND_PACKAGE_ARGS}')")
+      endif()
 
       get_hermetic_target_cache_file_path(${content_name} target_cache_file)
       hfc_targets_cache_create_isolated(
         ${content_name}
-        LOAD_TARGETS_CMAKE "[==[find_package(${content_name} REQUIRED ${__PARAMS_FIND_PACKAGE_ARGS} ) \n]==]"
+        LOAD_TARGETS_CMAKE "[==[find_package(${content_name} ${findpackage_args}) \n]==]"
         CACHE_DESTINATION_FILE "${target_cache_file}"
         TEMP_DIR "${HERMETIC_FETCHCONTENT_INSTALL_DIR}/targets_dump_tmp"
         TOOLCHAIN_FILE ${proxy_toolchain_path}

docs/modules/HermeticFetchContent.html

@@ -69,8 +69,9 @@ <h3>Navigation</h3>
 <ul>
 <li><p><a class="reference internal" href="#overview" id="id2">Overview</a></p></li>
 <li><p><a class="reference internal" href="#commands" id="id3">Commands</a></p></li>
-<li><p><a class="reference internal" href="#build-introspection" id="id4">Build introspection</a></p></li>
-<li><p><a class="reference internal" href="#rationale" id="id5">Rationale</a></p></li>
+<li><p><a class="reference internal" href="#fallback-to-system-provided-dependencies" id="id4">Fallback to system provided dependencies</a></p></li>
+<li><p><a class="reference internal" href="#build-introspection" id="id5">Build introspection</a></p></li>
+<li><p><a class="reference internal" href="#rationale" id="id6">Rationale</a></p></li>
 </ul>
 </li>
 </ul>
@@ -360,9 +361,22 @@ <h2><a class="toc-backref" href="#id3" role="doc-backlink">Commands</a><a class=
 <p>Set the base directory for all the hermetic dependency build directory and related folders</p>
 </dd></dl>
 
+</section>
+<section id="fallback-to-system-provided-dependencies">
+<h2><a class="toc-backref" href="#id4" role="doc-backlink">Fallback to system provided dependencies</a><a class="headerlink" href="#fallback-to-system-provided-dependencies" title="Permalink to this heading">¶</a></h2>
+<p>For use-cases in which you want to have the option to revert to a system provided library but still have the ability
+to build your own, you may set <code class="docutils literal notranslate"><span class="pre">FORCE_SYSTEM_&lt;content-name&gt;</span></code> to <code class="docutils literal notranslate"><span class="pre">ON</span></code>. In this case Hermetic FetchContent will
+execute a CMake <code class="docutils literal notranslate"><span class="pre">find_package(&lt;content-name&gt;</span> <span class="pre">REQUIRED)</span></code> call during targets discovery.</p>
+<p>If you need to specify arguments to <code class="docutils literal notranslate"><span class="pre">find_package()</span></code> you may add the <code class="docutils literal notranslate"><span class="pre">FIND_PACKAGE_ARGS</span></code> to the content declaration.</p>
+<blockquote>
+<div></div></blockquote>
+<p>Note that in the special case of <code class="docutils literal notranslate"><span class="pre">FORCE_SYSTEM_&lt;content-name&gt;=ON</span></code> the context in which the find_package() will be
+run, will be slightly different from the normal context for hermetic builds. One major difference is that the Hermetic
+FetchContent will inject the project's <code class="docutils literal notranslate"><span class="pre">CMAKE_MODULE_PATH</span></code> into the toolchain extension in addition to forcing 
+<code class="docutils literal notranslate"><span class="pre">find_package()</span></code> to search exclusively on the system through setting <code class="docutils literal notranslate"><span class="pre">CMAKE_FIND_ROOT_PATH_MODE_*</span></code> appropriately.</p>
 </section>
 <section id="build-introspection">
-<h2><a class="toc-backref" href="#id4" role="doc-backlink">Build introspection</a><a class="headerlink" href="#build-introspection" title="Permalink to this heading">¶</a></h2>
+<h2><a class="toc-backref" href="#id5" role="doc-backlink">Build introspection</a><a class="headerlink" href="#build-introspection" title="Permalink to this heading">¶</a></h2>
 <p>HermeticFetchContent adds a number of cmake build targets to the build system that can be executed after the project configuration to enable
 some build introspection:</p>
 <dl class="cmake command">
@@ -417,7 +431,7 @@ <h2><a class="toc-backref" href="#id4" role="doc-backlink">Build introspection</
 <p>Prints the list of executables of <code class="docutils literal notranslate"><span class="pre">${content_name}</span></code> on the console.</p>
 </section>
 <section id="rationale">
-<h2><a class="toc-backref" href="#id5" role="doc-backlink">Rationale</a><a class="headerlink" href="#rationale" title="Permalink to this heading">¶</a></h2>
+<h2><a class="toc-backref" href="#id6" role="doc-backlink">Rationale</a><a class="headerlink" href="#rationale" title="Permalink to this heading">¶</a></h2>
 <dl class="simple">
 <dt>Ressembling add_subdirectory through external cmake execution is key to providing reusable install trees :</dt><dd><ul class="simple">
 <li><p>One project depending on a library can reuse the library built by another project</p></li>
@@ -450,6 +464,7 @@ <h3><a href="../index.html">Table of Contents</a></h3>
 <li><a class="reference internal" href="#">FetchContent_MakeHermetic</a><ul>
 <li><a class="reference internal" href="#overview">Overview</a></li>
 <li><a class="reference internal" href="#commands">Commands</a></li>
+<li><a class="reference internal" href="#fallback-to-system-provided-dependencies">Fallback to system provided dependencies</a></li>
 <li><a class="reference internal" href="#build-introspection">Build introspection</a></li>
 <li><a class="reference internal" href="#rationale">Rationale</a></li>
 </ul>

docs/searchindex.js

@@ -56,7 +56,15 @@ namespace hfc::test {
     targets_cache_test_data_set{ "hfc_targets_cache/autotools_export_declaration", "Iconv.cmake", true },
     targets_cache_test_data_set{ "hfc_targets_cache/cmake_no_install", "mathslib.cmake", false },
     targets_cache_test_data_set{ "hfc_targets_cache/alternate_exports_naming", "mathslib.cmake", true },
-    targets_cache_test_data_set{ "hfc_targets_cache/alternate_exports_naming", "mathslib.cmake", false, false /* expect configure failure */, false, "-DHFCTEST_NEGATIVE_CASE=ON" /* enable the negative test in the project */ }
+    targets_cache_test_data_set{ "hfc_targets_cache/alternate_exports_naming", "mathslib.cmake", false, false /* expect configure failure */, false, "-DHFCTEST_NEGATIVE_CASE=ON" /* enable the negative test in the project */ },
+
+    // check that FIND_PACKAGE_ARGS are correctly forwarded to the underlying find_package() call
+    // > the cases below are just FORCE_SYSTEM_Iconv[ON;OFF] * TEST_INJECT_FIND_PACKAGE_ARGS[ON;OFF] 
+    // > to have the neg cases to validate the test code behavior IRT to expected outcomes
+    targets_cache_test_data_set{ "hfc_targets_cache/FORCE_SYSTEM_find_pagacke_args", "Iconv.cmake", false, false, false, "-DFORCE_SYSTEM_Iconv=OFF -DTEST_INJECT_FIND_PACKAGE_ARGS=ON" },   // neg test
+    targets_cache_test_data_set{ "hfc_targets_cache/FORCE_SYSTEM_find_pagacke_args", "Iconv.cmake", false, false, false, "-DFORCE_SYSTEM_Iconv=ON -DTEST_INJECT_FIND_PACKAGE_ARGS=OFF" },   // neg test
+    targets_cache_test_data_set{ "hfc_targets_cache/FORCE_SYSTEM_find_pagacke_args", "Iconv.cmake", false, false, false, "-DFORCE_SYSTEM_Iconv=OFF -DTEST_INJECT_FIND_PACKAGE_ARGS=OFF" },  // neg test
+    targets_cache_test_data_set{ "hfc_targets_cache/FORCE_SYSTEM_find_pagacke_args", "Iconv.cmake", true,  true, true, "-DFORCE_SYSTEM_Iconv=ON -DTEST_INJECT_FIND_PACKAGE_ARGS=ON" }    
   };
 
   static auto TEST_DATA_hfc_makeAvailableAt_type = {

test/targets_cache_test.cpp

@@ -0,0 +1,87 @@
+#
+# Check if arguments injected through HFC's FIND_PACKAGE_ARGS make it
+# to the underlying find_package() call 
+#
+# WORD OF CAUTION:
+# ================
+# we're overriding the find_package() function in the toolchain extension to this end. 
+# The whole execution is fundamentally broken for any other purpose than checking the 
+# arguments being forwarded!
+#
+
+cmake_minimum_required(VERSION 3.27.6)
+project(
+  ModernCMakeExample
+  VERSION 1.0
+  LANGUAGES CXX)
+
+
+set(CMAKE_MODULE_PATH
+  "${CMAKE_CURRENT_SOURCE_DIR}/cmake"
+  "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules"
+  ${CMAKE_MODULE_PATH}
+)
+
+include(FetchContent)
+include(HermeticFetchContent)
+
+
+# this is set by the test program, just making sure we have a value
+# when set to ON this should ensure we get to use the FindIconv.cmake module found under ./projectCmakeModules/
+if(NOT DEFINED FORCE_SYSTEM_Iconv)
+  message(FATAL_ERROR "FORCE_SYSTEM_Iconv not defined")
+endif()
+
+
+if(NOT DEFINED TEST_INJECT_FIND_PACKAGE_ARGS)
+  message(FATAL_ERROR "TEST_INJECT_FIND_PACKAGE_ARGS not defined")
+endif()
+
+if(TEST_INJECT_FIND_PACKAGE_ARGS)
+  set(find_package_args_value "REQUIRED HFC_TEST_FLAG")
+else()
+  set(find_package_args_value "REQUIRED")
+endif()
+
+
+FetchContent_Declare(
+  Iconv
+  GIT_REPOSITORY "https://github.com/tipi-build/unittest-autotools-sample.git"
+  GIT_TAG "ad80b024eeda8f4c0a96eedf669dc453ed33a094"
+)
+
+FetchContent_MakeHermetic(
+  Iconv
+  FIND_PACKAGE_ARGS "${find_package_args_value}"
+  HERMETIC_TOOLCHAIN_EXTENSION 
+  [=[
+
+  # override find_package with one that can check if HFC_TEST_FLAG was set
+  function(find_package)
+    # check if HFC_TEST_FLAG was set
+    if(NOT "HFC_TEST_FLAG" IN_LIST ARGN)
+      message(FATAL_ERROR "Flag HFC_TEST_FLAG was not passed...")
+    endif()
+
+    include(FindIconv) # yeah...
+
+    #_find_package(${ARGN})
+  endfunction()
+      
+  ]=]
+  HERMETIC_CMAKE_EXPORT_LIBRARY_DECLARATION 
+  [=[
+    message(FATAL_ERROR "This should never be run in this test")
+  ]=]
+  HERMETIC_BUILD_SYSTEM autotools
+)
+
+HermeticFetchContent_MakeAvailableAtConfigureTime("Iconv")
+
+
+if(NOT TARGET Iconv::Iconv)
+  message(FATAL_ERROR "Could not find target Iconv::Iconv")
+endif()
+
+add_executable(MyExample simple_example.cpp)
+target_link_libraries(MyExample PRIVATE Iconv::Iconv)

test/test_project_templates/hfc_targets_cache/FORCE_SYSTEM_find_pagacke_args/CMakeLists.txt

@@ -0,0 +1,3 @@
+int main() {
+    return 0;
+}