Add support exporting package cache vars in <Package>Config.cmake (Tr…

…iBITSPub#516)

This provides a mechanism for packages to provide information about how they
were configured to downstream CMake projects.

Any cache vars set with tribits_add_option_and_define() are exported
automatically but TriBITS packages can call
tribits_pkg_export_cache_var(<cacheVarName>) to export any cache vars.

See updated documentation for details.

tribits/CHANGELOG.md

@@ -2,6 +2,12 @@
 ChangeLog for TriBITS
 ----------------------------------------
 
+## 2022-08-22:
+
+* **Added:** Added support for exporting cache variables for packages in their
+    `<Package>Config.cmake` files using the new function
+    `tribits_pkg_export_cache_var()`.
+
 ## 2022-08-18:
 
 * **Changed:** Made setting parent package tests/examples enable/disable

tribits/core/package_arch/TribitsAddOptionAndDefine.cmake

@@ -58,6 +58,9 @@ include(GlobalSet)
 #
 #   #cmakedefine <macroDefineName>
 #
+# NOTE: This also calls `tribits_pkg_export_cache_var()`_ to export the
+# variables ``<userOptionName>`` and ``<macroDefineName>``.
+#
 macro(tribits_add_option_and_define  USER_OPTION_NAME  MACRO_DEFINE_NAME
   DOCSTRING  DEFAULT_VALUE
   )
@@ -70,6 +73,10 @@ macro(tribits_add_option_and_define  USER_OPTION_NAME  MACRO_DEFINE_NAME
       global_set(${MACRO_DEFINE_NAME} OFF)
     endif()
   endif()
+  if (COMMAND tribits_pkg_export_cache_var)
+    tribits_pkg_export_cache_var(${USER_OPTION_NAME})
+    tribits_pkg_export_cache_var(${MACRO_DEFINE_NAME})
+  endif()
 endmacro()
 
 # 2008/10/05: rabartl: ToDo: Add an option to automatically add the macro

tribits/core/package_arch/TribitsPackageMacros.cmake

@@ -78,6 +78,47 @@ macro(tribits_define_linkage_vars PACKAGE_NAME_IN)
 endmacro()
 
 
+# Macro that sets up data-structures for variables to be exported
+#
+macro(tribits_pkg_init_exported_vars  PACKAGE_NAME_IN)
+  global_set(${PACKAGE_NAME_IN}_PKG_VARS_TO_EXPORT "")
+endmacro()
+
+
+# @MACRO: tribits_pkg_export_cache_var()
+#
+# Macro that registers a package-level cache var to be exported in the
+# ``<Package>Config.cmake`` file
+#
+# Usage::
+#
+#   tribits_pkg_export_cache_var(<cacheVarName>)
+#
+# where ``<cacheVarName>`` must be the name of a cache variable (or an error
+# will occur).
+#
+# NOTE: This will also export this variable to the
+# ``<Package><Spkg>Config.cmake`` file for every enabled subpackage (if this
+# is called from a ``CMakeLists.txt`` file of a top-level package that has
+# subpackages).  That way, any top-level package cache vars are provided by
+# any of the subpackages' ``<Package><Spkg>Config.cmake`` files.
+#
+macro(tribits_pkg_export_cache_var  cacheVarName)
+  if (DEFINED ${PACKAGE_NAME}_PKG_VARS_TO_EXPORT)
+    # Assert this is a cache var
+    get_property(cacheVarIsCacheVar  CACHE ${cacheVarName} PROPERTY  VALUE  SET)
+    if (NOT cacheVarIsCacheVar)
+      message(SEND_ERROR
+        "ERROR: The variable ${cacheVarName} is NOT a cache var and cannot"
+        " be exported!")
+    endif()
+    # Add to the list of package cache vars to export
+    append_global_set(${PACKAGE_NAME}_PKG_VARS_TO_EXPORT
+      ${cacheVarName})
+  endif()
+endmacro()
+
+
 # Macro that defines variables that create global targets
 #
 macro(tribits_define_target_vars PARENT_PACKAGE_NAME_IN)
@@ -218,6 +259,7 @@ macro(tribits_package_decl PACKAGE_NAME_IN)
   #
 
   tribits_set_common_vars(${PACKAGE_NAME_IN})
+  tribits_pkg_init_exported_vars(${PACKAGE_NAME_IN})
 
   set(${PACKAGE_NAME_IN}_DISABLE_STRONG_WARNINGS OFF
      CACHE BOOL
@@ -459,6 +501,9 @@ endmacro()
 # typically called in the package's `<packageDir>/CMakeLists.txt`_ file (see
 # the example ``SimpleCxx/CMakeLists.txt``).
 #
+# NOTE: This also calls `tribits_pkg_export_cache_var()`_ to export the
+# variable ``${PACKAGE_NAME}_ENABLE_DEBUG``.
+#
 macro(tribits_add_debug_option)
   tribits_add_option_and_define(
     ${PACKAGE_NAME}_ENABLE_DEBUG

tribits/core/package_arch/TribitsSubPackageMacros.cmake

@@ -88,6 +88,7 @@ macro(tribits_subpackage SUBPACKAGE_NAME_IN)
   # Now override the package-like variables
   tribits_set_common_vars(${SUBPACKAGE_FULLNAME})
   tribits_define_linkage_vars(${SUBPACKAGE_FULLNAME})
+  tribits_pkg_init_exported_vars(${SUBPACKAGE_FULLNAME})
 
   tribits_append_package_specific_compiler_flags()
   if(${PROJECT_NAME}_VERBOSE_CONFIGURE)

tribits/core/package_arch/TribitsWriteClientExportFiles.cmake

@@ -577,6 +577,20 @@ function(tribits_append_dependent_package_config_file_includes_and_enables packa
       "set(${EXPORT_FILE_VAR_PREFIX}_ENABLE_${depPkg} ${enableVal})\n")
   endforeach()
 
+  # Put in set() statements for exported cache vars
+  string(APPEND configFileStr
+    "\n# Exported cache variables\n")
+  if (NOT "${${packageName}_PARENT_PACKAGE}" STREQUAL "")
+    foreach(exportedCacheVar IN LISTS ${${packageName}_PARENT_PACKAGE}_PKG_VARS_TO_EXPORT)
+      string(APPEND configFileStr
+        "set(${exportedCacheVar} \"${${exportedCacheVar}}\")\n")
+    endforeach()
+  endif()
+  foreach(exportedCacheVar IN LISTS ${packageName}_PKG_VARS_TO_EXPORT)
+    string(APPEND configFileStr
+      "set(${exportedCacheVar} \"${${exportedCacheVar}}\")\n")
+  endforeach()
+
   # Include configurations of dependent packages
   string(APPEND configFileStr
     "\n# Include configuration of dependent packages\n")

tribits/doc/guides/TribitsMacroFunctionDocTemplate.rst

@@ -30,6 +30,7 @@
 @FUNCTION: tribits_find_most_recent_source_file_timestamp() +
 @FUNCTION: tribits_install_headers() +
 @MACRO:    tribits_include_directories() +
+@MACRO:    tribits_pkg_export_cache_var() +
 @MACRO:    tribits_package() +
 @MACRO:    tribits_package_decl() +
 @MACRO:    tribits_package_def() +

tribits/examples/TribitsExampleProject/packages/simple_cxx/CMakeLists.txt

@@ -8,6 +8,7 @@ tribits_package( SimpleCxx  ENABLE_SHADOWING_WARNINGS  CLEANED )
 #
 include(CheckFor__int64)
 check_for___int64(HAVE_SIMPLECXX___INT64)
+tribits_pkg_export_cache_var(HAVE_SIMPLECXX___INT64)
 
 #
 # C) Set up package-specific options

tribits/examples/TribitsExampleProject/packages/with_subpackages/a/A.cpp

@@ -1,4 +1,5 @@
 #include "A.hpp"
+#include "WithSubpackagesA_config.h"
 
 #include "SimpleCxx_HelloWorld.hpp"
 
@@ -9,3 +10,7 @@ std::string WithSubpackages::getA() {
 std::string WithSubpackages::depsA() {
   return "SimpleCxx "+SimpleCxx::deps();
 }
+
+int WithSubpackages::specialValue() {
+  return WITHSUBPACKAGESA_SPECIAL_VALUE;
+}

tribits/examples/TribitsExampleProject/packages/with_subpackages/a/A.hpp

@@ -11,6 +11,9 @@ namespace WithSubpackages {
   // return a string describing the dependencies of "A", recursively
   std::string depsA();
 
+  // return speical value
+  int specialValue();
+
 }
 
 

tribits/examples/TribitsExampleProject/packages/with_subpackages/a/CMakeLists.txt

@@ -6,18 +6,22 @@ tribits_subpackage(A)
 #
 # B) Set up subpackage-specific options
 #
-# Typically there are none or are few as most options are picked up from the
-# parent package's CMakeLists.txt file!
+
+set(${PACKAGE_NAME}_SPECIAL_VALUE  3  CACHE STRING "Integer special value")
+tribits_pkg_export_cache_var(${PACKAGE_NAME}_SPECIAL_VALUE)
 
 #
 # C) Add the libraries, tests, and examples
 #
 
+tribits_configure_file(${PACKAGE_NAME}_config.h)
+
+include_directories(${CMAKE_CURRENT_BINARY_DIR})
+
 include_directories(${CMAKE_CURRENT_SOURCE_DIR})
 tribits_add_library(pws_a
   SOURCES A.cpp
-  HEADERS A.hpp
-  NOINSTALLHEADERS 
+  HEADERS A.hpp ${CMAKE_CURRENT_BINARY_DIR}/${PACKAGE_NAME}_config.h
 )
 
 tribits_add_test_directories(tests)

tribits/examples/TribitsExampleProject/packages/with_subpackages/a/cmake/WithSubpackagesA_config.h.in

@@ -0,0 +1,6 @@
+#ifndef WITHSUBPACKAGESA_CONFIG_H
+#define WITHSUBPACKAGESA_CONFIG_H
+
+#define WITHSUBPACKAGESA_SPECIAL_VALUE ${WithSubpackagesA_SPECIAL_VALUE}
+
+#endif // WITHSUBPACKAGESA_CONFIG_H

tribits/examples/TribitsExampleProject/packages/with_subpackages/a/tests/CMakeLists.txt

@@ -6,4 +6,5 @@ tribits_add_advanced_test( test_of_a
     PASS_REGULAR_EXPRESSION_ALL 
       "A label is: A"
       "A deps are: ${EXPECTED_SIMPLECXX_AND_DEPS}"
+      "A speical value: ${WithSubpackagesA_SPECIAL_VALUE}"
   )

tribits/examples/TribitsExampleProject/packages/with_subpackages/a/tests/a_test.cpp

@@ -3,13 +3,11 @@
 
 #include "A.hpp"
 
-using namespace WithSubpackages;
-
 int main() {
-  std::string label_A = getA();
-  std::string deps_A  = depsA();
+  std::string label_A = WithSubpackages::getA();
+  std::string deps_A  = WithSubpackages::depsA();
   std::cout << "A label is: " << label_A << std::endl;
   std::cout << "A deps are: " << deps_A << std::endl;
-
+  std::cout << "A speical value: " << WithSubpackages::specialValue() << std::endl;
   return 0;
 }