Merge pull request #617 from TriBITSPub/610-python3-2

Fixup for change to find_package(Python3) (#610)

test/doc/CMakeLists.txt

@@ -1,10 +1,3 @@
-if (PYTHON_VERSION_MAJOR GREATER_EQUAL 3)
-  set(HAS_PYTHON3 TRUE)
-else()
-  set(HAS_PYTHON3 FALSE)
-endif()
-
-
 advanced_set( ${PROJECT_NAME}_ENABLE_DOC_GENERATION_TESTS OFF
   CACHE BOOL
   "Enable testing for the build of the documentation, including using Sphinx.  Requires docutils, sphinx, and sphinx-rd-theme and will blow away and rebuild the existing documentation in the source tree since the documentation builds in place.  Therefore, one must be careful to not blow away non-tracked files." )
@@ -13,15 +6,14 @@ advanced_set( ${PROJECT_NAME}_ENABLE_DOC_GENERATION_TESTS OFF
 tribits_add_advanced_test( sphinx_rst_generator_UnitTests
   OVERALL_WORKING_DIRECTORY TEST_NAME
   OVERALL_NUM_MPI_PROCS 1
-  EXCLUDE_IF_NOT_TRUE HAS_PYTHON3
+  EXCLUDE_IF_NOT_TRUE Python3_EXECUTABLE
   TEST_0 CMND ${Python3_EXECUTABLE}
     ARGS ${CMAKE_CURRENT_SOURCE_DIR}/sphinx_rst_generator_UnitTests.py -v
     PASS_REGULAR_EXPRESSION "OK"
     ALWAYS_FAIL_ON_NONZERO_RETURN
   DISABLED "Test is broken for long time, see commit c477daa1"
   )
 
-
 tribits_add_advanced_test( build_docs
   EXCLUDE_IF_NOT_TRUE ${PROJECT_NAME}_ENABLE_DOC_GENERATION_TESTS
     GIT_EXECUTABLE

tribits/CHANGELOG.md

@@ -4,25 +4,43 @@ ChangeLog for TriBITS
 
 ## 2024-10-08:
 
-* **Changed:** The internal TriBITS framework find operation for Python has
-  been changed from calling `find_package(PythonInterp)` (using the deprecated
-  `FindPythonInterp.cmake` module) to calling `find_package(Python3)`, which
-  will find `python3` in the path automatically.  The internal 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 for users of TriBITS projects that set `-D
-  PYTHON_EXECUTABLE=<path>` is provided.  If a TriBITS project user sets `-D
+* **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 `Python3_EXECUTABLE` and avoid the call to `find_package(Python3)`;
-  however, a deprecation warning we be issued by default.  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](https://github.com/TriBITSPub/TriBITS/issues/610)
-  for more details.
+  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:
 

tribits/doc/build_ref/TribitsBuildReferenceBody.rst

@@ -2238,11 +2238,11 @@ To set which Python interpreter is used, configure with::
   -D Python3_EXECUTABLE=<python-path>
 
 Otherwise, Python will be found automatically by default using
-``find_python(Python3)`` internally.
+``find_python(Python3)`` internally (see `FindPython3.cmake`_).
 
-To disable the finding and usage of Python, configure with::
+To disable the finding and usage of Python, configure with (empty)::
 
-  -D Python3_EXECUTABLE=<python-path>
+  -D Python3_EXECUTABLE=
 
 
 Outputting package dependency information
@@ -4505,4 +4505,7 @@ dashboard``.
 
 .. _xSDK Community Package Policies: https://doi.org/10.6084/m9.figshare.4495136
 
+.. _FindPython3.cmake: https://cmake.org/cmake/help/latest/module/FindPython3.html
+
+
 ..  LocalWords:  templated instantiation Makefiles CMake

tribits/refactoring/to-python3.sh

@@ -1,12 +1,23 @@
 #!/bin/sh
 #
+# Refactor a TriBITS project's CMake files for the change from
+# find_package(PythonInterp) to find_package(Python3) (see CHANGELOG.md entry
+# for 2024-10-08).
+#
 # Usage:
 #
 #   to-python3.sh <base-dir>
 #
+# NOTES:
+# * This is safe to run multiple times on the same set of files.
+# * This is safe to run from the base project source tree.
+# * This will exclude any files under '.git/'
+# * This will exclude any files under 'tribits/' directories (so it will not mess up TriBITS)
+#
 
 _SCRIPT_DIR=`echo $0 | sed "s/\(.*\)\/to-python3[.]sh/\1/g"`
 baseDir=$1
 find ${baseDir} -type f \
   \( -name CMakeLists.txt -or -name "*.cmake" -or -name "*.cmake.in" -or -name "*.rst" \) \
+  ! -wholename "*/.git/*" ! -wholename  "*/tribits/*" \
   -exec $_SCRIPT_DIR/token-replace.py -t PYTHON_EXECUTABLE -r Python3_EXECUTABLE -f {} ';'