Assert exported cache and local vars have same value (TriBITSPub#516)

Added macro tribits_assert_cache_and_local_vars_same_value(<cacheVarName>)
(with strong unit tests) to ensure that if any exported cache vars also has
local vars of the same name that they also have the same value.

This was done in response to review of PR TriBITSPub#520 from @KyleFromKitware.

test/core/CMakeLists.txt

@@ -131,7 +131,7 @@ tribits_add_advanced_test( TribitsWriteClientExportFiles_UnitTests
       -DCMAKE_CURRENT_LIST_DIR=${CMAKE_CURRENT_SOURCE_DIR}
       -P "${CMAKE_CURRENT_SOURCE_DIR}/TribitsWriteClientExportFiles_UnitTests.cmake"
     PASS_REGULAR_EXPRESSION_ALL
-      "Final UnitTests Result: num_run = 30"
+      "Final UnitTests Result: num_run = 33"
       "Final UnitTests Result: PASSED"
   )
 

test/core/TribitsWriteClientExportFiles_UnitTests.cmake

@@ -75,7 +75,46 @@ endmacro()
 
 
 #
-# A) Test basic package processing and reading dependencies
+# A) Misc unit tests
+#
+
+function(unittest_tribits_assert_cache_and_local_vars_same_value)
+
+  message("\n***")
+  message("*** tribits_assert_cache_and_local_vars_same_value()")
+  message("***\n")
+
+  set(MESSAGE_WRAPPER_UNIT_TEST_MODE  TRUE)
+
+  message("\nOnly cache var exists")
+  global_set(MESSAGE_WRAPPER_INPUT)
+  set(cacheVar1 "1st value" CACHE STRING "")
+  tribits_assert_cache_and_local_vars_same_value(cacheVar1)
+  unittest_compare_const(MESSAGE_WRAPPER_INPUT "")
+  unset(cacheVar1 CACHE)
+
+  message("\nCache var and local var with same values exist")
+  global_set(MESSAGE_WRAPPER_INPUT)
+  set(cacheVar2 "2nd value" CACHE STRING "")
+  set(cacheVar2 "2nd value")
+  tribits_assert_cache_and_local_vars_same_value(cacheVar2)
+  unittest_compare_const(MESSAGE_WRAPPER_INPUT "")
+  unset(cacheVar2 CACHE)
+
+  message("\nCache var and local var with different values exist")
+  global_set(MESSAGE_WRAPPER_INPUT)
+  set(cacheVar3 "3rd value" CACHE STRING "")
+  set(cacheVar3 "3rd value diff")
+  tribits_assert_cache_and_local_vars_same_value(cacheVar3)
+  unittest_compare_const(MESSAGE_WRAPPER_INPUT
+    "SEND_ERROR;ERROR: The cache variable cacheVar3 with the; cache var value '3rd value' is not the same value as the local; variable cacheVar3 with value '3rd value diff'!")
+  unset(cacheVar3 CACHE)
+
+endfunction()
+
+
+#
+# B) Test basic package processing and reading dependencies
 #
 
 
@@ -255,8 +294,10 @@ unittest_initialize_vars()
 # Run the unit tests
 #
 
+unittest_tribits_assert_cache_and_local_vars_same_value()
+
 unittest_write_specialized_package_export_makefile_rtop_before_libs()
 unittest_write_specialized_package_export_makefile_rtop_after_libs()
 
 # Pass in the number of expected tests that must pass!
-unittest_final_result(30)
+unittest_final_result(33)

tribits/core/package_arch/TribitsGeneralMacros.cmake

@@ -426,3 +426,27 @@ function(tribits_trace_file_processing  TYPE_IN  PROCESSING_TYPE_IN  FILE_PATH)
   endif()
 
 endfunction()
+
+
+# @MACRO: tribits_assert_cache_and_local_vars_same_value()
+#
+# Asset that a cache variable and a possible local variable (if it exists)
+# have the same value.
+#
+# Usage::
+#
+#   tribits_assert_cache_and_local_vars_same_value(<cacheVarName>)
+#
+# If the local var ``<cacheVarName>`` and the cache var ``<cacheVarName>``
+# both exist but have different values, then ``message(SEND_ERROR ...)`` is
+# called with an informative error message.
+#
+macro(tribits_assert_cache_and_local_vars_same_value  cacheVarName)
+  set(cacheVarValue "$CACHE{${cacheVarName}}")
+  set(localValue "${${cacheVarName}}")
+  if (NOT localValue STREQUAL cacheVarValue)
+    message_wrapper(SEND_ERROR "ERROR: The cache variable ${cacheVarName} with the"
+      " cache var value '${cacheVarValue}' is not the same value as the local"
+      " variable ${cacheVarName} with value '${localValue}'!")
+  endif()
+endmacro()

tribits/core/package_arch/TribitsWriteClientExportFiles.cmake

@@ -581,11 +581,13 @@ function(tribits_append_dependent_package_config_file_includes_and_enables packa
     "\n# Exported cache variables\n")
   if (NOT "${${packageName}_PARENT_PACKAGE}" STREQUAL "")
     foreach(exportedCacheVar IN LISTS ${${packageName}_PARENT_PACKAGE}_PKG_VARS_TO_EXPORT)
+      tribits_assert_cache_and_local_vars_same_value(${exportedCacheVar})
       string(APPEND configFileStr
         "set(${exportedCacheVar} \"${${exportedCacheVar}}\")\n")
     endforeach()
   endif()
   foreach(exportedCacheVar IN LISTS ${packageName}_PKG_VARS_TO_EXPORT)
+    tribits_assert_cache_and_local_vars_same_value(${exportedCacheVar})
     string(APPEND configFileStr
       "set(${exportedCacheVar} \"${${exportedCacheVar}}\")\n")
   endforeach()

tribits/doc/guides/TribitsMacroFunctionDocTemplate.rst

@@ -14,6 +14,7 @@
 @FUNCTION: tribits_add_test() +
 @MACRO:    tribits_add_test_directories() +
 @FUNCTION: tribits_allow_missing_external_packages() +
+@MACRO:    tribits_assert_cache_and_local_vars_same_value() +
 @FUNCTION: tribits_configure_file() +
 @FUNCTION: tribits_copy_files_to_binary_dir() +
 @FUNCTION: tribits_ctest_driver() +