TriBITS: Transition to find_package(Python3) (TriBITSPub/TriBITS#610)

cmake/tribits/CHANGELOG.md

@@ -2,6 +2,46 @@
 ChangeLog for TriBITS
 ----------------------------------------
 
+## 2024-10-08:
+
+* **Changed:** The TriBITS framework find operation for
+  Python<sup>[&dagger;](#tribits_python_support)</sup> has been changed from
+  calling `find_package(PythonInterp)` (which uses the deprecated
+  `FindPythonInterp.cmake` module) to calling `find_package(Python3)` (which
+  uses [FindPython3.cmake]).  In the process, the internal CMake cache
+  variable set by this operation was changed from `PYTHON_EXECUTABLE` to
+  `Python3_EXECUTABLE`, and TriBITS projects need make that change as well
+  when upgrading TriBITS.  (This change can be made automatically in all of
+  the project's CMake files by running the script
+  `tribits/refactoring/to-python3.sh <dir>`.)  However, backward compatibility
+  is provided for users confiugring TriBITS CMake projects which set `-D
+  PYTHON_EXECUTABLE=<path>`.  In this case, if user sets `-D
+  PYTHON_EXECUTABLE=<path>` in the cache, TriBITS will set that value `<path>`
+  to the variable `Python3_EXECUTABLE` and avoid the call to
+  `find_package(Python3)` (however, a deprecation warning we be issued by
+  default, see [tribits_deprecated()] and [adjusting CMake DEPRECATION
+  warnings]).  TriBITS project users should change to use `-D
+  Python3_EXECUTABLE=<path>` instead, or just remove setting
+  `PYTHON_EXECUTABLE` or `Python3_EXECUTABLE` altogether and just make sure
+  that the desired `python3` executable is in the path.  See issue
+  [TriBITSPub/TriBITS#610] for more details.
+
+<a name="tribits_python_support"/>&dagger; **TriBITS Python Support**: See "Find Python" at [Full Processing of TriBITS Project Files], [Python Support] and [Setting or disabling Python]
+
+[FindPython3.cmake]: https://cmake.org/cmake/help/latest/module/FindPython3.html
+
+[Full Processing of TriBITS Project Files]: https://tribitspub.github.io/TriBITS/users_guide/index.html#full-tribits-project-configuration
+
+[Python Support]: https://tribitspub.github.io/TriBITS/users_guide/index.html#python-support
+
+[Setting or disabling Python]: https://tribitspub.github.io/TriBITS/build_ref/index.html#setting-or-disabling-python
+
+[tribits_deprecated()]: https://tribitspub.github.io/TriBITS/users_guide/index.html#tribits-deprecated
+
+[Adjusting CMake DEPRECATION warnings]: https://tribitspub.github.io/TriBITS/build_ref/index.html#adjusting-cmake-deprecation-warnings
+
+[TriBITSPub/TriBITS#610]: https://github.com/TriBITSPub/TriBITS/issues/610
+
 ## 2023-06-22:
 
 * **Added:** Packages are now determined to be missing if their dependencies

cmake/tribits/LICENSE

@@ -1,3 +1,5 @@
+SPDX-License-Identifier: BSD-3-Clause
+
 Copyright (c) 2013 NTESS and the TriBITS contributors.
 
 Redistribution and use in source and binary forms, with or without

cmake/tribits/ci_support/TribitsDependencies.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 # @HEADER
 # *****************************************************************************

cmake/tribits/ci_support/TribitsWriteXmlDependenciesFiles.cmake

@@ -52,7 +52,7 @@ macro(tribits_write_xml_dependency_files)
       " ${${PROJECT_NAME}_DEPS_HTML_OUTPUT_FILE} ..." )
     set(tribitsCiSupportDir "${${PROJECT_NAME}_TRIBITS_DIR}/${TRIBITS_CI_SUPPORT_DIR}")
     execute_process(
-      COMMAND ${PYTHON_EXECUTABLE}
+      COMMAND ${Python3_EXECUTABLE}
         ${tribitsCiSupportDir}/dump-package-dep-table.py
         --input-xml-deps-file=${${PROJECT_NAME}_DEPS_XML_OUTPUT_FILE}
         --output-html-deps-file=${${PROJECT_NAME}_DEPS_HTML_OUTPUT_FILE} )
@@ -70,7 +70,7 @@ macro(tribits_write_xml_dependency_files)
       "${${PROJECT_NAME}_TRIBITS_DIR}/${TRIBITS_CTEST_DRIVER_DIR}")
     if (EXISTS "${tribitsCtestDriverDir}")
       execute_process(
-        COMMAND ${PYTHON_EXECUTABLE}
+        COMMAND ${Python3_EXECUTABLE}
           ${tribitsCtestDriverDir}/dump-cdash-deps-xml-file.py
           --input-xml-deps-file=${${PROJECT_NAME}_DEPS_XML_OUTPUT_FILE}
           --output-cdash-deps-xml-file=${${PROJECT_NAME}_CDASH_DEPS_XML_OUTPUT_FILE})

cmake/tribits/ci_support/cdash_analyze_and_report.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 # @HEADER
 # *****************************************************************************

cmake/tribits/ci_support/cdash_build_testing_date.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 # @HEADER
 # *****************************************************************************

cmake/tribits/ci_support/checkin-test.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 # @HEADER
 # *****************************************************************************

cmake/tribits/ci_support/clone_extra_repos.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 # @HEADER
 # *****************************************************************************

cmake/tribits/ci_support/dump-package-dep-table.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 # @HEADER
 # *****************************************************************************

cmake/tribits/ci_support/filter-packages-list.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 # @HEADER
 # *****************************************************************************

cmake/tribits/ci_support/get-tribits-packages-from-last-tests-failed.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 # @HEADER
 # *****************************************************************************

cmake/tribits/ci_support/get-tribits-packages.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 # @HEADER
 # *****************************************************************************

cmake/tribits/ci_support/is_checkin_tested_commit.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 # @HEADER
 # *****************************************************************************

cmake/tribits/core/common/TribitsConstants.cmake

@@ -14,8 +14,9 @@ set(TRIBITS_CMAKE_MINIMUM_REQUIRED 3.23.0)
 macro(tribits_asesrt_minimum_cmake_version)
 
   if (CMAKE_VERSION VERSION_LESS ${TRIBITS_CMAKE_MINIMUM_REQUIRED})
-    message(FATAL_ERROR "Error, TriBiTS must have version"
-        " ${TRIBITS_CMAKE_MINIMUM_REQUIRED} or higher!")
+    message(FATAL_ERROR "Error, this TriBITS project ${PROJECT_NAME} must have a"
+      " version of CMake ${TRIBITS_CMAKE_MINIMUM_REQUIRED} or higher but was"
+      " only provided CMake version ${CMAKE_VERSION}!" )
   endif()
 
 endmacro()

cmake/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}="