FindJasper: Add Jasper_VERSION

This deprecates the JASPER_VERSION_STRING result variable.

Issue: #27088

Help/release/dev/find-modules.rst

@@ -13,6 +13,9 @@ Find Modules
 * The :module:`FindFreetype` module now provides a ``Freetype_VERSION`` result
   variable.  The ``FREETYPE_VERSION_STRING`` result variable is deprecated.
 
+* The :module:`FindJasper` module now provides a ``Jasper_VERSION`` result
+  variable.  The ``JASPER_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/FindJasper.cmake

@@ -6,7 +6,11 @@ FindJasper
 ----------
 
 Finds the JasPer Image Coding Toolkit for handling image data in a variety of
-formats, such as the JPEG-2000.
+formats, such as the JPEG-2000:
+
+.. code-block:: cmake
+
+  find_package(Jasper [<version>] [...])
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
@@ -25,8 +29,14 @@ Result Variables
 This module defines the following variables:
 
 ``Jasper_FOUND``
-  Boolean indicating whether the JasPer is found.  For backward compatibility,
-  the ``JASPER_FOUND`` variable is also set to the same value.
+  Boolean indicating whether (the requested version of) JasPer is found.
+  For backward compatibility, the ``JASPER_FOUND`` variable is also set to
+  the same value.
+
+``Jasper_VERSION``
+  .. versionadded:: 4.2
+
+  The version of JasPer found.
 
 ``JASPER_INCLUDE_DIRS``
   .. versionadded:: 3.22
@@ -36,9 +46,6 @@ This module defines the following variables:
 ``JASPER_LIBRARIES``
   The libraries needed to use JasPer.
 
-``JASPER_VERSION_STRING``
-  The version of JasPer found.
-
 Cache Variables
 ^^^^^^^^^^^^^^^
 
@@ -54,6 +61,17 @@ The following cache variables may also be set:
 ``JASPER_LIBRARY_DEBUG``
   The path to the debug variant of the JasPer library.
 
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+The following variables are provided for backward compatibility:
+
+``JASPER_VERSION_STRING``
+  .. deprecated:: 4.2
+    Superseded by the ``Jasper_VERSION``.
+
+  The version of JasPer found.
+
 Examples
 ^^^^^^^^
 
@@ -81,13 +99,14 @@ endif()
 
 if(JASPER_INCLUDE_DIR AND EXISTS "${JASPER_INCLUDE_DIR}/jasper/jas_config.h")
   file(STRINGS "${JASPER_INCLUDE_DIR}/jasper/jas_config.h" jasper_version_str REGEX "^#define[\t ]+JAS_VERSION[\t ]+\".*\".*")
-  string(REGEX REPLACE "^#define[\t ]+JAS_VERSION[\t ]+\"([^\"]+)\".*" "\\1" JASPER_VERSION_STRING "${jasper_version_str}")
+  string(REGEX REPLACE "^#define[\t ]+JAS_VERSION[\t ]+\"([^\"]+)\".*" "\\1" Jasper_VERSION "${jasper_version_str}")
+  set(JASPER_VERSION_STRING "${Jasper_VERSION}")
 endif()
 
 include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(Jasper
                                   REQUIRED_VARS JASPER_LIBRARIES JASPER_INCLUDE_DIR
-                                  VERSION_VAR JASPER_VERSION_STRING)
+                                  VERSION_VAR Jasper_VERSION)
 
 if(Jasper_FOUND)
   set(JASPER_LIBRARIES ${JASPER_LIBRARIES})

Tests/CMakeOnly/AllFindModules/CMakeLists.txt

@@ -119,7 +119,7 @@ foreach(
     FLEX Freetype
     GIF GTK2
     HDF5
-    JPEG
+    Jasper JPEG
     LibArchive LIBLZMA
     OPENSCENEGRAPH
     PostgreSQL Protobuf

Tests/FindJasper/Test/CMakeLists.txt

@@ -4,7 +4,7 @@ include(CTest)
 
 find_package(Jasper)
 
-add_definitions(-DCMAKE_EXPECTED_JASPER_VERSION="${JASPER_VERSION_STRING}")
+add_definitions(-DCMAKE_EXPECTED_JASPER_VERSION="${Jasper_VERSION}")
 
 add_executable(test_jasper_tgt main.c)
 target_link_libraries(test_jasper_tgt Jasper::Jasper)