FindEXPAT: Add EXPAT_VERSION

This deprecates the EXPAT_VERSION_STRING result variable, which was
previously not documented.

Issue: #27088

Help/release/dev/find-modules.rst

@@ -7,6 +7,9 @@ Find Modules
 * The :module:`FindBZip2` module now provides a ``BZip2_VERSION`` result
   variable.  The ``BZIP2_VERSION`` result variable is deprecated.
 
+* The :module:`FindEXPAT` module now provides a ``EXPAT_VERSION`` result
+  variable.  The ``EXPAT_VERSION_STRING`` result variable is deprecated.
+
 * The :module:`FindPostgreSQL` module now provides a ``PostgreSQL_VERSION``
   result variable.  The ``PostgreSQL_VERSION_STRING`` result variable is
   deprecated.

Modules/FindEXPAT.cmake

@@ -5,8 +5,13 @@
 FindEXPAT
 ---------
 
-Finds the native Expat headers and library.  Expat is a stream-oriented XML
-parser library written in C.
+Finds the native Expat headers and library:
+
+.. code-block:: cmake
+
+  find_package(EXPAT [<version>] [...])
+
+Expat is a stream-oriented XML parser library written in C.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
@@ -24,13 +29,20 @@ Result Variables
 
 This module sets the following variables:
 
+``EXPAT_FOUND``
+  Boolean indicating whether (the requested version of) Expat is found.
+
+``EXPAT_VERSION``
+  .. versionadded:: 4.2
+
+  The version of Expat found.
+
 ``EXPAT_INCLUDE_DIRS``
   Include directories containing ``expat.h`` and related headers needed to use
   Expat.
+
 ``EXPAT_LIBRARIES``
   Libraries needed to link against to use Expat.
-``EXPAT_FOUND``
-  Boolean indicating whether the Expat is found.
 
 Hints
 ^^^^^
@@ -46,6 +58,17 @@ This module accepts the following variables:
 
     Implemented on non-Windows platforms.
 
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+The following variables are provided for backward compatibility:
+
+``EXPAT_VERSION_STRING``
+  .. deprecated:: 4.2
+    Superseded by the ``EXPAT_VERSION``.
+
+  The version of Expat found.
+
 Examples
 ^^^^^^^^
 
@@ -135,25 +158,26 @@ if(EXPAT_INCLUDE_DIR AND EXISTS "${EXPAT_INCLUDE_DIR}/expat.h")
   file(STRINGS "${EXPAT_INCLUDE_DIR}/expat.h" expat_version_str
     REGEX "^#[\t ]*define[\t ]+XML_(MAJOR|MINOR|MICRO)_VERSION[\t ]+[0-9]+$")
 
-  unset(EXPAT_VERSION_STRING)
+  unset(EXPAT_VERSION)
   foreach(VPART MAJOR MINOR MICRO)
     foreach(VLINE ${expat_version_str})
       if(VLINE MATCHES "^#[\t ]*define[\t ]+XML_${VPART}_VERSION[\t ]+([0-9]+)$")
         set(EXPAT_VERSION_PART "${CMAKE_MATCH_1}")
-        if(EXPAT_VERSION_STRING)
-          string(APPEND EXPAT_VERSION_STRING ".${EXPAT_VERSION_PART}")
+        if(EXPAT_VERSION)
+          string(APPEND EXPAT_VERSION ".${EXPAT_VERSION_PART}")
         else()
-          set(EXPAT_VERSION_STRING "${EXPAT_VERSION_PART}")
+          set(EXPAT_VERSION "${EXPAT_VERSION_PART}")
         endif()
       endif()
     endforeach()
   endforeach()
+  set(EXPAT_VERSION_STRING ${EXPAT_VERSION})
 endif()
 
 include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(EXPAT
                                   REQUIRED_VARS EXPAT_LIBRARY EXPAT_INCLUDE_DIR
-                                  VERSION_VAR EXPAT_VERSION_STRING)
+                                  VERSION_VAR EXPAT_VERSION)
 
 # Copy the results to the output variables and target.
 if(EXPAT_FOUND)

Tests/CMakeOnly/AllFindModules/CMakeLists.txt

@@ -115,6 +115,7 @@ foreach(
     BISON Boost BZip2 BZIP2
     CUDA
     DOXYGEN
+    EXPAT
     FLEX
     GIF GTK2
     HDF5

Tests/FindEXPAT/Test/CMakeLists.txt

@@ -4,7 +4,7 @@ include(CTest)
 
 find_package(EXPAT REQUIRED)
 
-add_definitions(-DCMAKE_EXPECTED_EXPAT_VERSION="${EXPAT_VERSION_STRING}")
+add_definitions(-DCMAKE_EXPECTED_EXPAT_VERSION="${EXPAT_VERSION}")
 
 add_executable(testexpat_tgt main.c)
 target_link_libraries(testexpat_tgt EXPAT::EXPAT)