FindTclsh: Add Tclsh_VERSION

This deprecates the TCLSH_VERSION_STRING result variable.

Issue: #27088

Help/release/dev/find-modules.rst

@@ -99,6 +99,9 @@ Find Modules
   result variable.  The ``Subversion_VERSION_SVN`` result variable is
   deprecated.
 
+* The :module:`FindTclsh` module now provides a ``Tclsh_VERSION`` result
+  variable.  The ``TCLSH_VERSION_STRING`` result variable is deprecated.
+
 * The :module:`FindTIFF` module now provides a ``TIFF_VERSION`` result
   variable.  The ``TIFF_VERSION_STRING`` result variable is deprecated.
 

Modules/FindTCL.cmake

@@ -79,8 +79,8 @@ endblock()
 include(${CMAKE_CURRENT_LIST_DIR}/FindTclsh.cmake)
 include(${CMAKE_CURRENT_LIST_DIR}/FindWish.cmake)
 
-if(TCLSH_VERSION_STRING)
+if(Tclsh_VERSION)
-  set(TCL_TCLSH_VERSION "${TCLSH_VERSION_STRING}")
+  set(TCL_TCLSH_VERSION "${Tclsh_VERSION}")
 else()
   get_filename_component(TCL_TCLSH_PATH "${TCL_TCLSH}" PATH)
   get_filename_component(TCL_TCLSH_PATH_PARENT "${TCL_TCLSH_PATH}" PATH)

Modules/FindTclsh.cmake

@@ -10,7 +10,7 @@ Finds the Tcl shell command-line executable (``tclsh``), which includes the Tcl
 
 .. code-block:: cmake
 
-  find_package(Tclsh [...])
+  find_package(Tclsh [<version>] [...])
 
 Result Variables
 ^^^^^^^^^^^^^^^^
@@ -18,9 +18,14 @@ Result Variables
 This module defines the following variables:
 
 ``Tclsh_FOUND``
-  Boolean indicating whether the ``tclsh`` executable (and the requested
+  Boolean indicating whether the (requested version of) ``tclsh`` executable
-  version, if specified) is found.  For backward compatibility, the
+  is found.  For backward compatibility, the ``TCLSH_FOUND`` variable is
-  ``TCLSH_FOUND`` variable is also set to the same value.
+  also set to the same value.
+
+``Tclsh_VERSION``
+  .. versionadded:: 4.2
+
+  The version of ``tclsh`` found.
 
 Cache Variables
 ^^^^^^^^^^^^^^^
@@ -30,14 +35,30 @@ The following cache variables may also be set:
 ``TCL_TCLSH``
   The path to the ``tclsh`` executable.
 
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+The following variables are provided for backward compatibility:
+
+``TCLSH_VERSION_STRING``
+  .. deprecated:: 4.2
+    Use ``Tclsh_VERSION``, which has the same value.
+
+  The version of ``tclsh`` found.
+
 Examples
 ^^^^^^^^
 
-Finding the ``tclsh`` command-line executable:
+In the following example, this module is used to find the ``tclsh``
+command-line executable, which is then executed in a process to evaluate
+TCL code from the script file located in the project source directory:
 
 .. code-block:: cmake
 
   find_package(Tclsh)
+  if(Tclsh_FOUND)
+    execute_process(COMMAND ${TCL_TCLSH} example-script.tcl)
+  endif()
 
 See Also
 ^^^^^^^^
@@ -108,9 +129,10 @@ find_program(TCL_TCLSH
 if(TCL_TCLSH)
   execute_process(COMMAND "${CMAKE_COMMAND}" -E echo puts "\$tcl_version"
                   COMMAND "${TCL_TCLSH}"
-                  OUTPUT_VARIABLE TCLSH_VERSION_STRING
+                  OUTPUT_VARIABLE Tclsh_VERSION
                   ERROR_QUIET
                   OUTPUT_STRIP_TRAILING_WHITESPACE)
+  set(TCLSH_VERSION_STRING "${Tclsh_VERSION}")
 endif()
 
 include(FindPackageHandleStandardArgs)
@@ -124,7 +146,7 @@ if (CMAKE_FIND_PACKAGE_NAME STREQUAL "TCL" OR
 endif ()
 find_package_handle_standard_args(Tclsh
                                   REQUIRED_VARS TCL_TCLSH
-                                  VERSION_VAR TCLSH_VERSION_STRING)
+                                  VERSION_VAR Tclsh_VERSION)
 unset(FPHSA_NAME_MISMATCHED)
 
 mark_as_advanced(TCL_TCLSH)

Tests/CMakeOnly/AllFindModules/CMakeLists.txt

@@ -104,7 +104,7 @@ foreach(
     LIBLZMA LIBXML2 LIBXSLT LTTNGUST
     PERL PKG_CONFIG PNG PostgreSQL
     SDL
-    TIFF
+    TCLSH TIFF
     wxWidgets
     ZLIB
 )
@@ -127,7 +127,7 @@ foreach(
     Perl PerlLibs PkgConfig PNG PostgreSQL Protobuf
     Ruby RUBY
     SDL SWIG
-    TIFF
+    Tclsh TIFF
     wxWidgets
     ZLIB
 )