From 5f2fdb7cbf03713eb09d539fdcce2adbe750ea09 Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Thu, 31 Jul 2025 21:02:05 +0200
Subject: [PATCH] FindPNG: Add PNG_VERSION

This deprecates the PNG_VERSION_STRING result variable.

Additionally, the documentation has been adjusted and synced with other
similar find modules:
- Added "Deprecated Variables" section and deprecated versions.
- Added intro code block how to use this module.

Issue: #27088
---
 Help/release/dev/find-modules.rst             |  3 ++
 Modules/FindPNG.cmake                         | 46 ++++++++++++++-----
 Tests/CMakeOnly/AllFindModules/CMakeLists.txt |  4 +-
 Tests/FindPNG/Test/CMakeLists.txt             |  2 +-
 4 files changed, 41 insertions(+), 14 deletions(-)

diff --git a/Help/release/dev/find-modules.rst b/Help/release/dev/find-modules.rst
index b8c69e08f0..10034c97cd 100644
--- a/Help/release/dev/find-modules.rst
+++ b/Help/release/dev/find-modules.rst
@@ -22,6 +22,9 @@ Find Modules
 * The :module:`FindLibXslt` module now provides a ``LibXslt_VERSION`` result
   variable.  The ``LIBXSLT_VERSION_STRING`` result variable is deprecated.
 
+* The :module:`FindPNG` module now provides a ``PNG_VERSION`` result
+  variable.  The ``PNG_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.
diff --git a/Modules/FindPNG.cmake b/Modules/FindPNG.cmake
index 1a72f7d788..0d5886aafc 100644
--- a/Modules/FindPNG.cmake
+++ b/Modules/FindPNG.cmake
@@ -5,7 +5,11 @@
 FindPNG
 -------
 
-Finds libpng, the official reference library for the PNG image format.
+Finds libpng, the official reference library for the PNG image format:
+
+.. code-block:: cmake
+
+  find_package(PNG [<version>] [...])
 
 .. note::
 
@@ -15,11 +19,11 @@ Finds libpng, the official reference library for the PNG image format.
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-.. versionadded:: 3.5
-
 This module defines the following :ref:`Imported Targets`:
 
 ``PNG::PNG``
+  .. versionadded:: 3.5
+
   The libpng library, if found.
 
 Result Variables
@@ -27,29 +31,48 @@ Result Variables
 
 This module sets the following variables:
 
+``PNG_FOUND``
+  Boolean indicating whether (the requested version of) PNG library is found.
+
+``PNG_VERSION``
+  .. versionadded:: 4.2
+
+  The version of the PNG library found.
+
 ``PNG_INCLUDE_DIRS``
   Directory containing the PNG headers (e.g., ``png.h``).
+
 ``PNG_LIBRARIES``
   PNG libraries required for linking.
+
 ``PNG_DEFINITIONS``
   Compile definitions for using PNG, if any.  They can be added with
   :command:`target_compile_definitions` command when not using the ``PNG::PNG``
   imported target.
-``PNG_FOUND``
-  True if PNG library is found.
-``PNG_VERSION_STRING``
-  The version of the PNG library found.
 
-Obsolete Variables
-^^^^^^^^^^^^^^^^^^
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
 
 The following variables may also be set for backward compatibility:
 
 ``PNG_LIBRARY``
+  .. deprecated:: 3.0
+    Use the ``PNG::PNG`` imported target.
+
   Path to the PNG library.
+
 ``PNG_INCLUDE_DIR``
+  .. deprecated:: 3.0
+    Use the ``PNG::PNG`` imported target.
+
   Directory containing the PNG headers (same as ``PNG_INCLUDE_DIRS``).
 
+``PNG_VERSION_STRING``
+  .. deprecated:: 4.2
+    Superseded by the ``PNG_VERSION``.
+
+  The version of the PNG library found.
+
 Examples
 ^^^^^^^^
 
@@ -184,7 +207,8 @@ if(ZLIB_FOUND)
   if (PNG_PNG_INCLUDE_DIR AND EXISTS "${PNG_PNG_INCLUDE_DIR}/png.h")
       file(STRINGS "${PNG_PNG_INCLUDE_DIR}/png.h" png_version_str REGEX "^#define[ \t]+PNG_LIBPNG_VER_STRING[ \t]+\".+\"")
 
-      string(REGEX REPLACE "^#define[ \t]+PNG_LIBPNG_VER_STRING[ \t]+\"([^\"]+)\".*" "\\1" PNG_VERSION_STRING "${png_version_str}")
+      string(REGEX REPLACE "^#define[ \t]+PNG_LIBPNG_VER_STRING[ \t]+\"([^\"]+)\".*" "\\1" PNG_VERSION "${png_version_str}")
+      set(PNG_VERSION_STRING "${PNG_VERSION}")
       unset(png_version_str)
   endif ()
 endif()
@@ -192,6 +216,6 @@ endif()
 include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(PNG
                                   REQUIRED_VARS PNG_LIBRARY PNG_PNG_INCLUDE_DIR
-                                  VERSION_VAR PNG_VERSION_STRING)
+                                  VERSION_VAR PNG_VERSION)
 
 cmake_policy(POP)
diff --git a/Tests/CMakeOnly/AllFindModules/CMakeLists.txt b/Tests/CMakeOnly/AllFindModules/CMakeLists.txt
index 7eb381a1ac..dcb7335f20 100644
--- a/Tests/CMakeOnly/AllFindModules/CMakeLists.txt
+++ b/Tests/CMakeOnly/AllFindModules/CMakeLists.txt
@@ -102,7 +102,7 @@ foreach(
     ICOTOOL
     JASPER
     LIBLZMA LIBXML2 LIBXSLT LTTNGUST
-    PERL PKG_CONFIG PostgreSQL
+    PERL PKG_CONFIG PNG PostgreSQL
     TIFF
     ZLIB
 )
@@ -122,7 +122,7 @@ foreach(
     Jasper JPEG
     LibArchive LIBLZMA LibXml2 LibXslt
     OPENSCENEGRAPH
-    PostgreSQL Protobuf
+    PNG PostgreSQL Protobuf
     Ruby RUBY
     SWIG
     ZLIB
diff --git a/Tests/FindPNG/Test/CMakeLists.txt b/Tests/FindPNG/Test/CMakeLists.txt
index 6cc9ca2d1d..5ac2b39896 100644
--- a/Tests/FindPNG/Test/CMakeLists.txt
+++ b/Tests/FindPNG/Test/CMakeLists.txt
@@ -4,7 +4,7 @@ include(CTest)
 
 find_package(PNG REQUIRED)
 
-add_definitions(-DCMAKE_EXPECTED_PNG_VERSION="${PNG_VERSION_STRING}")
+add_definitions(-DCMAKE_EXPECTED_PNG_VERSION="${PNG_VERSION}")
 
 add_executable(test_tgt main.c)
 target_link_libraries(test_tgt PNG::PNG)