From 4786a6f34a10696e82cfcbbd46895268d0d4dc1b Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Wed, 6 Aug 2025 23:51:23 +0200
Subject: [PATCH] FindGnuplot: Add Gnuplot_VERSION

This deprecates the GNUPLOT_VERSION_STRING result variable.

Issue: #27088
---
 Help/release/dev/find-modules.rst |  3 +++
 Modules/FindGnuplot.cmake         | 40 ++++++++++++++++++++++++-------
 2 files changed, 34 insertions(+), 9 deletions(-)

diff --git a/Help/release/dev/find-modules.rst b/Help/release/dev/find-modules.rst
index 122db56d3a..4e254d78c9 100644
--- a/Help/release/dev/find-modules.rst
+++ b/Help/release/dev/find-modules.rst
@@ -28,6 +28,9 @@ Find Modules
 * The :module:`FindGettext` module now provides a ``Gettext_VERSION`` result
   variable.  The ``GETTEXT_VERSION_STRING`` result variable is deprecated.
 
+* The :module:`FindGnuplot` module now provides a ``Gnuplot_VERSION`` result
+  variable.  The ``GNUPLOT_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.
 
diff --git a/Modules/FindGnuplot.cmake b/Modules/FindGnuplot.cmake
index abbb681551..c8e788602d 100644
--- a/Modules/FindGnuplot.cmake
+++ b/Modules/FindGnuplot.cmake
@@ -6,18 +6,25 @@ FindGnuplot
 -----------
 
 Finds the Gnuplot command-line graphing utility for generating two- and
-three-dimensional plots (``gnuplot``).
+three-dimensional plots (``gnuplot``):
+
+.. code-block:: cmake
+
+  find_package(Gnuplot [<version>] [...])
 
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module sets the following variables:
+This module defines the following variables:
 
 ``Gnuplot_FOUND``
-  Boolean indicating whether Gnuplot has been found.  For backward
-  compatibility, the ``GNUPLOT_FOUND`` variable is also set to the same value.
+  Boolean indicating whether (the requested version of) Gnuplot has been
+  found.  For backward compatibility, the ``GNUPLOT_FOUND`` variable is also
+  set to the same value.
+
+``Gnuplot_VERSION``
+  .. versionadded:: 4.2
 
-``GNUPLOT_VERSION_STRING``
   The version of Gnuplot found.
 
   .. note::
@@ -33,14 +40,28 @@ The following cache variables may also be set:
 ``GNUPLOT_EXECUTABLE``
   Absolute path to the ``gnuplot`` executable.
 
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+The following variables are provided for backward compatibility:
+
+``GNUPLOT_VERSION_STRING``
+  .. deprecated:: 4.2
+    Superseded by the ``Gnuplot_VERSION``.
+
+  The version of Gnuplot found.
+
 Examples
 ^^^^^^^^
 
-Finding Gnuplot:
+Finding Gnuplot and executing it in a process:
 
 .. code-block:: cmake
 
   find_package(Gnuplot)
+  if(Gnuplot_FOUND)
+    execute_process(COMMAND ${GNUPLOT_EXECUTABLE} --help)
+  endif()
 #]=======================================================================]
 
 include(${CMAKE_CURRENT_LIST_DIR}/FindCygwin.cmake)
@@ -62,8 +83,9 @@ if (GNUPLOT_EXECUTABLE)
                   ERROR_QUIET
                   OUTPUT_STRIP_TRAILING_WHITESPACE)
 
-    string(REGEX REPLACE "^gnuplot ([0-9\\.]+)( patchlevel )?" "\\1." GNUPLOT_VERSION_STRING "${GNUPLOT_OUTPUT_VARIABLE}")
-    string(REGEX REPLACE "\\.$" "" GNUPLOT_VERSION_STRING "${GNUPLOT_VERSION_STRING}")
+    string(REGEX REPLACE "^gnuplot ([0-9\\.]+)( patchlevel )?" "\\1." Gnuplot_VERSION "${GNUPLOT_OUTPUT_VARIABLE}")
+    string(REGEX REPLACE "\\.$" "" Gnuplot_VERSION "${Gnuplot_VERSION}")
+    set(GNUPLOT_VERSION_STRING "${Gnuplot_VERSION}")
     unset(GNUPLOT_OUTPUT_VARIABLE)
 endif()
 
@@ -73,6 +95,6 @@ set(GNUPLOT ${GNUPLOT_EXECUTABLE})
 include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(Gnuplot
                                   REQUIRED_VARS GNUPLOT_EXECUTABLE
-                                  VERSION_VAR GNUPLOT_VERSION_STRING)
+                                  VERSION_VAR Gnuplot_VERSION)
 
 mark_as_advanced( GNUPLOT_EXECUTABLE )