diff --git a/test/doc/CMakeLists.txt b/test/doc/CMakeLists.txt index 6cc978641..26c550c0c 100644 --- a/test/doc/CMakeLists.txt +++ b/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,7 +6,7 @@ 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" @@ -21,7 +14,6 @@ tribits_add_advanced_test( sphinx_rst_generator_UnitTests 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 diff --git a/tribits/CHANGELOG.md b/tribits/CHANGELOG.md index ca6a8724d..d824c7810 100644 --- a/tribits/CHANGELOG.md +++ b/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 `.) However, - backward compatibility for users of TriBITS projects that set `-D - PYTHON_EXECUTABLE=` is provided. If a TriBITS project user sets `-D +* **Changed:** The TriBITS framework find operation for + Python[†](#tribits_python_support) 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 `.) However, backward compatibility + is provided for users confiugring TriBITS CMake projects which set `-D + PYTHON_EXECUTABLE=`. In this case, if user sets `-D PYTHON_EXECUTABLE=` in the cache, TriBITS will set that value `` - 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=` 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=` 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. + +† **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: diff --git a/tribits/doc/build_ref/TribitsBuildReferenceBody.rst b/tribits/doc/build_ref/TribitsBuildReferenceBody.rst index c7351ebe2..b8601d6e8 100644 --- a/tribits/doc/build_ref/TribitsBuildReferenceBody.rst +++ b/tribits/doc/build_ref/TribitsBuildReferenceBody.rst @@ -2238,11 +2238,11 @@ To set which Python interpreter is used, configure with:: -D Python3_EXECUTABLE= 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= + -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 diff --git a/tribits/refactoring/to-python3.sh b/tribits/refactoring/to-python3.sh index 2a295f5f6..4c40c0d67 100755 --- a/tribits/refactoring/to-python3.sh +++ b/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 # +# 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 {} ';'