Merge pull request #615 from bartlettroscoe/enable-disable-doc-update…

…-2024-08-29 Refactor to improve clarity of tribits_adjust_package_enables() and update users/maintainers guide some
TriBITSPub · Sep 1, 2024 · 7cfa35a · 7cfa35a
2 parents 4743755 + 36a1fba
commit 7cfa35a
Show file tree

Hide file tree

Showing 3 changed files with 116 additions and 71 deletions.
diff --git a/tribits/core/package_arch/TribitsAdjustPackageEnables.cmake b/tribits/core/package_arch/TribitsAdjustPackageEnables.cmake
@@ -418,34 +418,44 @@ endmacro()
 #
 macro(tribits_disable_parents_subpackages  parentPackageName)
 
-  if(NOT ${PROJECT_NAME}_ENABLE_${parentPackageName}
-      AND (NOT ${PROJECT_NAME}_ENABLE_${parentPackageName} STREQUAL "")
-    )
+  tribits_package_is_explicitly_disabled(${PROJECT_NAME}_ENABLE_${parentPackageName}
+    parentPackageIsExplicityDisabled)
+
+  if(parentPackageIsExplicityDisabled)
 
     foreach(tap2_subPkgName   IN LISTS  ${parentPackageName}_SUBPACKAGES)
 
       set(subpkgFullName ${parentPackageName}${tap2_subPkgName})
 
-      if (NOT ${PROJECT_NAME}_ENABLE_${subpkgFullName} STREQUAL "OFF")
-        set(packageBeingDisabledVarName ${PROJECT_NAME}_ENABLE_${subpkgFullName})
+      set(subpkgBeingDisabledVarName ${PROJECT_NAME}_ENABLE_${subpkgFullName})
+      tribits_package_is_explicitly_disabled(${subpkgBeingDisabledVarName}
+        subpkgIExplicitlyDisabled)
+      if (NOT subpkgIsExplicitlyDisabled)
         message("-- "
-          "Setting subpackage enable ${packageBeingDisabledVarName}=OFF"
+          "Setting subpackage enable ${subpkgBeingDisabledVarName}=OFF"
           " because parent package ${PROJECT_NAME}_ENABLE_${parentPackageName}=OFF")
-        set(${packageBeingDisabledVarName} OFF)
+        set(${subpkgBeingDisabledVarName} OFF)
       endif()
 
     endforeach()
 
   endif()
 
 endmacro()
+#
+# NOTE: Above, we don't need to use the function
+# tribits_get_package_enable_status() because a subpackage in this context
+# will never be an external package and therefore the enable var name will
+# always be ${PROJECT_NAME}_ENABLE_${subpkgFullName}.  (At least I can't think
+# of a use case where that would occur.)
 
 
 # Macro that disables forward package that depends on the passed-in package
 #
 macro(tribits_disable_forward_required_dep_packages  packageName)
   tribits_get_package_enable_status(${packageName}  packageEnable  "")
-  if ((NOT packageEnable) AND (NOT "${packageEnable}" STREQUAL ""))
+  tribits_package_is_explicitly_disabled(packageEnable  packageIsExplicitlyDisabled)
+  if (packageIsExplicitlyDisabled)
     foreach(fwdDepPkg  IN LISTS  ${packageName}_FORWARD_LIB_DEFINED_DEPENDENCIES)
       if (${fwdDepPkg}_LIB_DEP_REQUIRED_${packageName})
         tribits_private_disable_required_package_enables(${fwdDepPkg}
@@ -475,13 +485,13 @@ macro(tribits_enable_parents_subpackages  parentPackageName)
     foreach(tap2_subPkgName  IN LISTS  ${parentPackageName}_SUBPACKAGES)
 
       set(subpkgFullName ${parentPackageName}${tap2_subPkgName})
+      tribits_package_is_explicitly_disabled(${PROJECT_NAME}_ENABLE_${subpkgFullName}
+	subpkgIsExplicitlyDisabled)
 
-      if (NOT ${PROJECT_NAME}_ENABLE_${subpkgFullName} AND
-        NOT "${${PROJECT_NAME}_ENABLE_${subpkgFullName}}" STREQUAL ""
-        )
-        # The subpackage is already disabled and is not just empty!
+      if (subpkgIsExplicitlyDisabled)
+        # The subpackage is already explicitly disabled
       elseif (${PROJECT_NAME}_ENABLE_${subpkgFullName})
-        # The subpackage is already enabled so there is no reason to enable it!
+        # The subpackage is already enabled so there is no reason to enable it
       else()
         # The subpackage is not hard off or on so turn it on by default
         tribits_implicit_package_enable_is_allowed( "" ${subpkgFullName}
@@ -513,7 +523,7 @@ macro(tribits_apply_all_package_enables  packageName)
   tribits_implicit_package_enable_is_allowed( "" ${packageName}
     processThisPackageEnable )
   if (packageIsPmpp  AND  processThisPackageEnable)
-    tribits_set_package_enable_based_on_project_enable(
+    tribits_enable_package_based_on_project_enable_on(
       ${PROJECT_NAME}_ENABLE_ALL_PACKAGES  ${PROJECT_NAME}_ENABLE_${packageName} )
   endif()
 endmacro()
@@ -548,8 +558,9 @@ endmacro()
 # ${parentPackageName)_ENABLE_TESTS is explicitly disabled.
 #
 macro(tribits_apply_package_examples_disable  parentPackageName)
-  if ( (NOT ${parentPackageName}_ENABLE_TESTS)
-      AND (NOT "${${parentPackageName}_ENABLE_TESTS}" STREQUAL "")
+  tribits_package_is_explicitly_disabled(${parentPackageName}_ENABLE_TESTS
+    parentPackageTestsIsExplicitlyDisabled)
+  if (parentPackageTestsIsExplicitlyDisabled
       AND ("${${parentPackageName}_ENABLE_EXAMPLES}" STREQUAL "")
     )
     message("-- " "Setting"
@@ -574,7 +585,9 @@ macro(tribits_apply_subpackage_tests_or_examples_disables  parentPackageName
     testsOrExamples
   )
   set(parentPkgEnableVar ${parentPackageName}_ENABLE_${testsOrExamples})
-  if ((NOT ${parentPkgEnableVar}) AND (NOT "${${parentPkgEnableVar}}" STREQUAL ""))
+  tribits_package_is_explicitly_disabled(${parentPkgEnableVar}
+    parentPkgIsExplicitlyDisabled)
+  if (parentPkgIsExplicitlyDisabled)
     foreach(subpkgName  IN LISTS  ${parentPackageName}_SUBPACKAGES)
       set(fullSpkgName ${parentPackageName}${subpkgName})
       if (${PROJECT_NAME}_ENABLE_${fullSpkgName})
@@ -599,9 +612,9 @@ macro(tribits_apply_test_example_enables  packageName)
   if (${PROJECT_NAME}_ENABLE_${packageName})
     tribits_is_primary_meta_project_package(${packageName}  packageIsPmmp)
     if (packageIsPmmp)
-      tribits_set_package_enable_based_on_project_enable_on(
+      tribits_enable_package_based_on_project_enable_on(
         ${PROJECT_NAME}_ENABLE_TESTS  ${packageName}_ENABLE_TESTS )
-      tribits_set_package_enable_based_on_project_enable_on(
+      tribits_enable_package_based_on_project_enable_on(
         ${PROJECT_NAME}_ENABLE_EXAMPLES  ${packageName}_ENABLE_EXAMPLES )
     endif()
   endif()
@@ -936,26 +949,28 @@ macro(tribits_private_disable_required_package_enables
     fwdDepPkgName  packageName  libraryDep
   )
   tribits_get_package_enable_status(${fwdDepPkgName}  ""  fwdDepPkgEnableVarName)
-  if (${fwdDepPkgEnableVarName} OR "${${fwdDepPkgEnableVarName}}" STREQUAL "")
+  tribits_package_is_enabled_or_unset(${fwdDepPkgEnableVarName}
+    fwdDepPkgIsEnabledOrUnset)
+  if (fwdDepPkgIsEnabledOrUnset)
     if ("${libraryDep}" STREQUAL "TRUE")
       tribits_private_print_disable_required_package_enable(
         ${packageName}  ${fwdDepPkgEnableVarName}
         ${fwdDepPkgName} "library" )
       set(${fwdDepPkgEnableVarName}  OFF)
     else()
       set(depTypeStr "test/example")
-      if (${fwdDepPkgName}_ENABLE_TESTS
-        OR "${${fwdDepPkgName}_ENABLE_TESTS}" STREQUAL ""
-        )
+      tribits_package_is_enabled_or_unset(${fwdDepPkgName}_ENABLE_TESTS
+	fwdDepPkgEnableTestsIsEnabledOrUnset)
+      if (fwdDepPkgEnableTestsIsEnabledOrUnset)
         tribits_private_print_disable_required_package_enable(
           ${packageName} ${fwdDepPkgName}_ENABLE_TESTS
           ${fwdDepPkgName} "${depTypeStr}" )
         set(${fwdDepPkgName}_ENABLE_TESTS OFF)
       endif()
 
-      if (${fwdDepPkgName}_ENABLE_EXAMPLES
-        OR "${${fwdDepPkgName}_ENABLE_EXAMPLES}" STREQUAL ""
-        )
+      tribits_package_is_enabled_or_unset(${fwdDepPkgName}_ENABLE_EXAMPLES
+	fwdDepPkgEnableExamplesIsEnabledOrUnset)
+      if (fwdDepPkgEnableExamplesIsEnabledOrUnset)
         tribits_private_print_disable_required_package_enable(
           ${packageName} ${fwdDepPkgName}_ENABLE_EXAMPLES
           ${fwdDepPkgName} "${depTypeStr}" )
@@ -1013,9 +1028,9 @@ endfunction()
 
 macro(tribits_private_disable_optional_package_enables  fwdDepPkgName  packageName)
 
-  if (${fwdDepPkgName}_ENABLE_${packageName}
-      OR "${${fwdDepPkgName}_ENABLE_${packageName}}" STREQUAL ""
-    )
+  tribits_package_is_enabled_or_unset(${fwdDepPkgName}_ENABLE_${packageName}
+    fwdDepPkgEnablePackageIsEnabledOrUnset)
+  if (fwdDepPkgEnablePackageIsEnabledOrUnset)
     # Always disable the conditional enable but only print the message if the
     # package is enabled or if a disable overrides an enable
     if (${PROJECT_NAME}_ENABLE_${fwdDepPkgName})
@@ -1032,10 +1047,9 @@ macro(tribits_private_disable_optional_package_enables  fwdDepPkgName  packageNa
           " on disabled package ${packageName}")
       endif()
     endif()
-    if (${fwdDepPkgName}_ENABLE_${packageName}
-        AND (NOT ${PROJECT_NAME}_ENABLE_${packageName})
-        AND (NOT "${${PROJECT_NAME}_ENABLE_${packageName}}" STREQUAL "")
-      )
+    tribits_package_is_explicitly_disabled(${PROJECT_NAME}_ENABLE_${packageName}
+      packageIsExplicitlyDisabled)
+    if (${fwdDepPkgName}_ENABLE_${packageName} AND packageIsExplicitlyDisabled)
       message("-- " "NOTE: ${fwdDepPkgName}_ENABLE_${packageName}="
         "${${fwdDepPkgName}_ENABLE_${packageName}} but"
         " ${PROJECT_NAME}_ENABLE_${packageName}="
@@ -1048,37 +1062,10 @@ macro(tribits_private_disable_optional_package_enables  fwdDepPkgName  packageNa
 endmacro()
 
 
-# Set an individual package variable enable variable (to ON or OFF) based on a
-# global enable value
-#
-macro(tribits_set_package_enable_based_on_project_enable  projectEnableVar
-    packageEnableVar
-  )
-
-  if ("${${packageEnableVar}}" STREQUAL "")
-    if (${projectEnableVar})
-      message("-- " "Setting ${packageEnableVar}=ON")
-      set(${packageEnableVar} ON)
-    elseif ( (NOT ${projectEnableVar})
-        AND (NOT "${projectEnableVar}" STREQUAL "")
-      )
-      message("-- " "Setting ${packageEnableVar}=OFF")
-      set(${packageEnableVar} OFF)
-    else()
-      # Otherwise, we will leave it up the the individual package
-      # to decide?
-    endif()
-  else()
-    # "${packageEnableVar} not at the default empty ''
-  endif()
-
-endmacro()
-
-
 # Set an individual package test or examples enable to on only if global
 # enable var is on
 #
-macro(tribits_set_package_enable_based_on_project_enable_on  projectEnableVar
+macro(tribits_enable_package_based_on_project_enable_on  projectEnableVar
     packageEnableVar
   )
   if (("${${packageEnableVar}}" STREQUAL "") AND ${projectEnableVar})
@@ -1133,7 +1120,9 @@ endmacro()
 macro(tribits_private_postprocess_optional_package_enable  packageName  optDepPkg)
 
   tribits_get_package_enable_status(${optDepPkg}  optDepPkgEnable  optDepPkgEnableVar)
-  tribits_get_package_enable_status(${packageName} packageEnable  packageEnableVar)
+  tribits_get_package_enable_status(${packageName}  packageEnable  packageEnableVar)
+  tribits_package_is_explicitly_disabled(${packageName}_ENABLE_${optDepPkg}
+    package_Enable_OptDeptPkg_IsExplicitlyDisabled)
 
   if (${packageName}_ENABLE_${optDepPkg}  AND  optDepPkgEnable)
     message("-- " "NOTE:"
@@ -1149,10 +1138,7 @@ macro(tribits_private_postprocess_optional_package_enable  packageName  optDepPk
       message("-- " "NOT setting ${packageName}_ENABLE_${optDepPkg}=ON"
        " since ${optDepPkg} is NOT enabled at this point!")
     endif()
-  elseif ((NOT "${${packageName}_ENABLE_${optDepPkg}}" STREQUAL "")
-      AND (NOT ${packageName}_ENABLE_${optDepPkg})
-      AND optDepPkgEnable
-    )
+  elseif (package_Enable_OptDeptPkg_IsExplicitlyDisabled  AND  optDepPkgEnable)
     message("-- " "NOTE: ${packageName}_ENABLE_${optDepPkg}="
       "${${packageName}_ENABLE_${optDepPkg}} is already set so not enabling even"
       " though ${optDepPkgEnableVar}="

diff --git a/tribits/core/package_arch/TribitsGetPackageEnableStatus.cmake b/tribits/core/package_arch/TribitsGetPackageEnableStatus.cmake
@@ -10,8 +10,8 @@
 
 # @FUNCTION: tribits_get_package_enable_status()
 #
-# Function that determines if a given external or internal package's enable
-# status (e.g. 'ON' or 'OFF')
+# Function that determines a given external or internal package's enable
+# status (e.g. 'ON' or 'OFF' or any valid CMake bool)
 #
 # Usage::
 #
@@ -21,8 +21,8 @@
 # On return, if non-empty, the variable ``<packageEnableOut>`` will contain
 # the actual value of ``${${PROJECT_NAME}_ENABLE_<packageName>}`` or
 # ``${TPL_ENABLE_<packageName>}`` or will return empty "".  If
-# ``${packageName}_PACKAGE_BUILD_STATUS == "INTERNAL", then only the value of
-# ``${PROJECT_NAME}_ENABLE_<packageName>`` will be considered.
+# ``${packageName}_PACKAGE_BUILD_STATUS == "INTERNAL"``, then only the value
+# of ``${PROJECT_NAME}_ENABLE_<packageName>`` will be considered.
 #
 # On return, if non-empty, the variable ``<packageEnableVarNameOut>`` will be
 # either ``${${PROJECT_NAME}_ENABLE_<packageName>}`` or
@@ -61,6 +61,62 @@ function(tribits_get_package_enable_status  packageName  packageEnableOut
 endfunction()
 
 
+# @FUNCTION: tribits_package_is_enabled_or_unset()
+#
+# Function that determines if a package's enable variable evaluates to true or
+# is unset.
+#
+# Usage::
+#
+#   tribits_package_is_enabled_or_unset((<packageEnableVarName>
+#     <packageIsEnabledOrUnsetOut>)
+#
+# On return, the value of ``<packageIsEnabledOrUnsetOut>`` will set to
+# ``TRUE`` if the variable ``<packageEnableVarName>`` evaluates to true and
+# or is empty "".  Otherwise, ``<packageIsEnabledOrUnsetOut>`` will set
+# to ``FALSE`` on return.
+#
+function(tribits_package_is_enabled_or_unset  packageEnableVarName
+    packageIsEnabledOrUnsetOut
+  )
+  if (${packageEnableVarName} OR ("${${packageEnableVarName}}" STREQUAL ""))
+    set(packageIsEnabledOrUnset TRUE)
+  else()
+    set(packageIsEnabledOrUnset FALSE)
+  endif()
+  set(${packageIsEnabledOrUnsetOut} ${packageIsEnabledOrUnset}
+    PARENT_SCOPE)
+endfunction()
+
+
+# @FUNCTION: tribits_package_is_explicitly_disabled()
+#
+# Function that determines if a package's enable variable is
+# explicitly disabled (i.e. evaluates to false but is not emapty).
+#
+# Usage::
+#
+#   tribits_package_is_explicitly_disabled((<packageEnableVarName>
+#     <packageIsExplicitlyDisabledOut>)
+#
+# On return, the value of ``<packageIsExplicitlyDisabledOut>`` will set to
+# ``TRUE`` if the variable ``<packageEnableVarName>`` evaluates to false and
+# is not empty "".  Otherwise, ``<packageIsExplicitlyDisabledOut>`` will set
+# to ``FALSE`` on return.
+#
+function(tribits_package_is_explicitly_disabled  packageEnableVarName
+    packageIsExplicitlyDisabledOut
+  )
+  if ((NOT ${packageEnableVarName}) AND (NOT "${${packageEnableVarName}}" STREQUAL ""))
+    set(packageIsExplicitlyDisabled TRUE)
+  else()
+    set(packageIsExplicitlyDisabled FALSE)
+  endif()
+  set(${packageIsExplicitlyDisabledOut} ${packageIsExplicitlyDisabled}
+    PARENT_SCOPE)
+endfunction()
+
+
 # @FUNCTION: tribits_assert_package_enable_status()
 #
 # Function that asserts that if both ``${PROJECT_NAME}_ENABLE_${packageName}``

diff --git a/tribits/doc/guides/TribitsMacroFunctionDocTemplate.rst b/tribits/doc/guides/TribitsMacroFunctionDocTemplate.rst
@@ -31,16 +31,19 @@
 @FUNCTION: tribits_find_most_recent_binary_file_timestamp() +
 @FUNCTION: tribits_find_most_recent_file_timestamp() +
 @FUNCTION: tribits_find_most_recent_source_file_timestamp() +
+@FUNCTION: tribits_get_package_enable_status() +
 @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() +
 @MACRO:    tribits_package_define_dependencies() +
+@MACRO:    tribits_process_enabled_standard_tpl() +
+@FUNCTION: tribits_package_is_enabled_or_unset() +
+@FUNCTION: tribits_package_is_explicitly_disabled() +
 @MACRO:    tribits_package_postprocess() +
 @MACRO:    tribits_process_subpackages() +
-@MACRO:    tribits_process_enabled_standard_tpl() +
 @MACRO:    tribits_project() +
 @MACRO:    tribits_project_define_extra_repositories() +
 @MACRO:    tribits_project_enable_all() +