FindLibXml2: Add LibXml2_VERSION

This deprecates the LIBXML2_VERSION_STRING result variable.

Issue: #27088

Help/release/dev/find-modules.rst

@@ -16,6 +16,9 @@ Find Modules
 * The :module:`FindJasper` module now provides a ``Jasper_VERSION`` result
   variable.  The ``JASPER_VERSION_STRING`` result variable is deprecated.
 
+* The :module:`FindLibXml2` module now provides a ``LibXml2_VERSION`` result
+  variable.  The ``LIBXML2_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/FindLibXml2.cmake

@@ -5,7 +5,11 @@
 FindLibXml2
 -----------
 
-Finds the XML processing library (libxml2).
+Finds the XML processing library (libxml2):
+
+.. code-block:: cmake
+
+  find_package(LibXml2 [<version>] [...])
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
@@ -30,15 +34,22 @@ Result Variables
 This module defines the following variables:
 
 ``LibXml2_FOUND``
-  Boolean indicating whether the libxml2 library is found.
+  Boolean indicating whether (the requested version of) libxml2 library is
+  found.
+
+``LibXml2_VERSION``
+  .. versionadded:: 4.2
+
+  The version of the libxml2 found.
+
 ``LIBXML2_INCLUDE_DIRS``
   Include directories needed to use the libxml2 library.
+
 ``LIBXML2_LIBRARIES``
   Libraries needed to link against to use the libxml2 library.
+
 ``LIBXML2_DEFINITIONS``
   The compiler switches required for using libxml2.
-``LIBXML2_VERSION_STRING``
-  The version of the libxml2 found.
 
 Cache Variables
 ^^^^^^^^^^^^^^^
@@ -47,11 +58,24 @@ The following cache variables may also be set:
 
 ``LIBXML2_INCLUDE_DIR``
   The include directory containing libxml2 headers.
+
 ``LIBXML2_LIBRARY``
   The path to the libxml2 library.
+
 ``LIBXML2_XMLLINT_EXECUTABLE``
   The path to the XML checking tool ``xmllint`` coming with libxml2.
 
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+The following variables are provided for backward compatibility:
+
+``LIBXML2_VERSION_STRING``
+  .. deprecated:: 4.2
+    Superseded by the ``LibXml2_VERSION``.
+
+  The version of the libxml2 found.
+
 Examples
 ^^^^^^^^
 
@@ -102,7 +126,8 @@ if(LIBXML2_INCLUDE_DIR AND EXISTS "${LIBXML2_INCLUDE_DIR}/libxml/xmlversion.h")
          REGEX "^#define[\t ]+LIBXML_DOTTED_VERSION[\t ]+\".*\"")
 
     string(REGEX REPLACE "^#define[\t ]+LIBXML_DOTTED_VERSION[\t ]+\"([^\"]*)\".*" "\\1"
-           LIBXML2_VERSION_STRING "${libxml2_version_str}")
+           LibXml2_VERSION "${libxml2_version_str}")
+    set(LIBXML2_VERSION_STRING "${LibXml2_VERSION}")
     unset(libxml2_version_str)
 endif()
 
@@ -123,7 +148,7 @@ endforeach()
 include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(LibXml2
                                   REQUIRED_VARS LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR
-                                  VERSION_VAR LIBXML2_VERSION_STRING)
+                                  VERSION_VAR LibXml2_VERSION)
 
 mark_as_advanced(LIBXML2_INCLUDE_DIR LIBXML2_LIBRARY LIBXML2_XMLLINT_EXECUTABLE)
 

Tests/CMakeOnly/AllFindModules/CMakeLists.txt

@@ -120,7 +120,7 @@ foreach(
     GIF GTK2
     HDF5
     Jasper JPEG
-    LibArchive LIBLZMA
+    LibArchive LIBLZMA LibXml2
     OPENSCENEGRAPH
     PostgreSQL Protobuf
     Ruby RUBY

Tests/FindLibXml2/Test/CMakeLists.txt

@@ -4,7 +4,7 @@ include(CTest)
 
 find_package(LibXml2 REQUIRED)
 
-add_definitions(-DCMAKE_EXPECTED_LibXml2_VERSION="${LIBXML2_VERSION_STRING}")
+add_definitions(-DCMAKE_EXPECTED_LibXml2_VERSION="${LibXml2_VERSION}")
 
 add_executable(test_tgt main.c)
 target_link_libraries(test_tgt LibXml2::LibXml2)