FindArmadillo: Add Armadillo_VERSION

This deprecates the following result variables:
* ARMADILLO_VERSION_STRING
* ARMADILLO_VERSION_MAJOR
* ARMADILLO_VERSION_MINOR
* ARMADILLO_VERSION_PATCH
* ARMADILLO_VERSION_NAME (added the Armadillo_VERSION_NAME as an
  alternative).

When Armadillo is found in config mode, the `Armadillo_VERSION` is
already set automatically:

    find_package(Armadillo CONFIG)

Issue: #27088

Help/release/dev/find-modules.rst

@@ -4,6 +4,12 @@ Find Modules
 * The :module:`FindALSA` module now provides a ``ALSA_VERSION`` result
   variable.  The ``ALSA_VERSION_STRING`` result variable is deprecated.
 
+* The :module:`FindArmadillo` module now provides an ``Armadillo_VERSION``,
+  and ``Armadillo_VERSION_NAME`` result variables.  The
+  ``ARMADILLO_VERSION_STRING``, ``ARMADILLO_VERSION_MAJOR``,
+  ``ARMADILLO_VERSION_MINOR``, ``ARMADILLO_VERSION_PATCH``, and
+  ``ARMADILLO_VERSION_NAME`` result variables are deprecated.
+
 * The :module:`FindBZip2` module now provides a ``BZip2_VERSION`` result
   variable.  The ``BZIP2_VERSION`` result variable is deprecated.
 

Modules/FindArmadillo.cmake

@@ -5,8 +5,13 @@
 FindArmadillo
 -------------
 
-Finds the Armadillo C++ library.  Armadillo is a library for linear algebra and
-scientific computing.
+Finds the Armadillo C++ library:
+
+.. code-block:: cmake
+
+  find_package(Armadillo [<version>] [...])
+
+Armadillo is a library for linear algebra and scientific computing.
 
 .. versionadded:: 3.18
   Support for linking wrapped libraries directly (see the
@@ -16,30 +21,68 @@ scientific computing.
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module sets the following variables:
+This module defines the following variables:
 
 ``Armadillo_FOUND``
-  Set to true if the library is found.  For backward compatibility, the
-  ``ARMADILLO_FOUND`` variable is also set to the same value.
+  Boolean indicating whether the (requested version of) Armadillo library is
+  found.  For backward compatibility, the ``ARMADILLO_FOUND`` variable is
+  also set to the same value.
+
+``Armadillo_VERSION``
+  .. versionadded:: 4.2
+
+  The version of Armadillo found (e.g., ``14.90.0``).
+
+``Armadillo_VERSION_NAME``
+  .. versionadded:: 4.2
+
+  The version name of Armadillo found (e.g., ``Antipodean Antileech``).
+
 ``ARMADILLO_INCLUDE_DIRS``
   List of required include directories.
+
 ``ARMADILLO_LIBRARIES``
   List of libraries to be linked.
+
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+The following variables are provided for backward compatibility:
+
 ``ARMADILLO_VERSION_STRING``
-  Version as a string (ex: ``1.0.4``).
+  .. deprecated:: 4.2
+    Superseded by the ``Armadillo_VERSION``.
+
+  The version of Armadillo found.
+
 ``ARMADILLO_VERSION_MAJOR``
+  .. deprecated:: 4.2
+    Superseded by the ``Armadillo_VERSION``.
+
   Major version number.
+
 ``ARMADILLO_VERSION_MINOR``
+  .. deprecated:: 4.2
+    Superseded by the ``Armadillo_VERSION``.
+
   Minor version number.
+
 ``ARMADILLO_VERSION_PATCH``
+  .. deprecated:: 4.2
+    Superseded by the ``Armadillo_VERSION``.
+
   Patch version number.
+
 ``ARMADILLO_VERSION_NAME``
-  Name of the version (ex: ``Antipodean Antileech``).
+  .. deprecated:: 4.2
+    Superseded by the ``Armadillo_VERSION_NAME``.
+
+  The version name of Armadillo found (e.g., ``Antipodean Antileech``).
 
 Examples
 ^^^^^^^^
 
-Using Armadillo:
+Finding Armadillo and creating an imported target:
 
 .. code-block:: cmake
 
@@ -79,10 +122,9 @@ if(ARMADILLO_INCLUDE_DIR)
   set(ARMADILLO_VERSION_MAJOR 0)
   set(ARMADILLO_VERSION_MINOR 0)
   set(ARMADILLO_VERSION_PATCH 0)
-  set(ARMADILLO_VERSION_NAME "EARLY RELEASE")
+  set(Armadillo_VERSION_NAME "EARLY RELEASE")
 
   if(EXISTS "${ARMADILLO_INCLUDE_DIR}/armadillo_bits/arma_version.hpp")
-
     # Read and parse armdillo version header file for version number
     file(STRINGS "${ARMADILLO_INCLUDE_DIR}/armadillo_bits/arma_version.hpp" _ARMA_HEADER_CONTENTS REGEX "#define ARMA_VERSION_[A-Z]+ ")
     string(REGEX REPLACE ".*#define ARMA_VERSION_MAJOR ([0-9]+).*" "\\1" ARMADILLO_VERSION_MAJOR "${_ARMA_HEADER_CONTENTS}")
@@ -90,11 +132,13 @@ if(ARMADILLO_INCLUDE_DIR)
     string(REGEX REPLACE ".*#define ARMA_VERSION_PATCH ([0-9]+).*" "\\1" ARMADILLO_VERSION_PATCH "${_ARMA_HEADER_CONTENTS}")
 
     # WARNING: The number of spaces before the version name is not one.
-    string(REGEX REPLACE ".*#define ARMA_VERSION_NAME\ +\"([0-9a-zA-Z\ _-]+)\".*" "\\1" ARMADILLO_VERSION_NAME "${_ARMA_HEADER_CONTENTS}")
+    string(REGEX REPLACE ".*#define ARMA_VERSION_NAME\ +\"([0-9a-zA-Z\ _-]+)\".*" "\\1" Armadillo_VERSION_NAME "${_ARMA_HEADER_CONTENTS}")
 
+    set(ARMADILLO_VERSION_NAME "${Armadillo_VERSION_NAME}")
   endif()
 
-  set(ARMADILLO_VERSION_STRING "${ARMADILLO_VERSION_MAJOR}.${ARMADILLO_VERSION_MINOR}.${ARMADILLO_VERSION_PATCH}")
+  set(Armadillo_VERSION "${ARMADILLO_VERSION_MAJOR}.${ARMADILLO_VERSION_MINOR}.${ARMADILLO_VERSION_PATCH}")
+  set(ARMADILLO_VERSION_STRING "${Armadillo_VERSION}")
 endif ()
 
 if(EXISTS "${ARMADILLO_INCLUDE_DIR}/armadillo_bits/config.hpp")
@@ -150,7 +194,7 @@ endif()
 
 find_package_handle_standard_args(Armadillo
   REQUIRED_VARS ARMADILLO_INCLUDE_DIR ${_ARMA_REQUIRED_VARS}
-  VERSION_VAR ARMADILLO_VERSION_STRING)
+  VERSION_VAR Armadillo_VERSION)
 
 if (Armadillo_FOUND)
   set(ARMADILLO_INCLUDE_DIRS ${ARMADILLO_INCLUDE_DIR})

Tests/CMakeOnly/AllFindModules/CMakeLists.txt

@@ -112,7 +112,7 @@ endforeach()
 
 foreach(
   VTEST
-    ALSA
+    ALSA Armadillo
     BISON Boost BZip2 BZIP2
     CUDA Cups
     DOXYGEN