FindLua*: Add Lua_VERSION

New result variables in FindLua:

* Lua_VERSION
* Lua_VERSION_MAJOR
* Lua_VERSION_MINOR
* Lua_VERSION_PATCH

Deprecated variables in FindLua:

* LUA_VERSION_STRING
* LUA_VERSION_MAJOR
* LUA_VERSION_MINOR
* LUA_VERSION_PATCH

Deprecated variables in FindLua51:

* LUA_VERSION_STRING

Issue: #27088

Help/release/dev/find-modules.rst

@@ -46,6 +46,14 @@ Find Modules
 * The :module:`FindLTTngUST` module now provides a ``LTTngUST_VERSION`` result
   variable.  The ``LTTNGUST_VERSION_STRING`` result variable is deprecated.
 
+* The :module:`FindLua` module now provides ``Lua_VERSION``,
+  ``Lua_VERSION_MAJOR``, ``Lua_VERSION_MINOR``, and ``Lua_VERSION_PATCH``
+  result variables.  The ``LUA_VERSION_STRING``, ``LUA_VERSION_MAJOR``,
+  ``LUA_VERSION_MINOR``, and ``LUA_VERSION_PATCH`` result variables are
+  deprecated.  The :module:`FindLua51` module now similarly provides a
+  ``Lua_VERSION`` instead of the now deprecated ``LUA_VERSION_STRING`` result
+  variable.
+
 * The :module:`FindOpenSceneGraph` module now provides an
   ``OpenSceneGraph_VERSION`` result variable.  The ``OPENSCENEGRAPH_VERSION``
   result variable is deprecated.

Modules/FindLua.cmake

@@ -5,7 +5,13 @@
 FindLua
 -------
 
-Finds the Lua library.  Lua is a embeddable scripting language.
+Finds the Lua library:
+
+.. code-block:: cmake
+
+  find_package(Lua [<version>] [...])
+
+Lua is a embeddable scripting language.
 
 .. versionadded:: 3.18
   Support for Lua 5.4.
@@ -35,14 +41,27 @@ This module defines the following variables:
   Boolean indicating whether (the requested version of) Lua is found.  For
   backward compatibility, the ``LUA_FOUND`` variable is also set to the same
   value.
-``LUA_VERSION_STRING``
+
+``Lua_VERSION``
+  .. versionadded:: 4.2
+
   The version of Lua found.
-``LUA_VERSION_MAJOR``
+
+``Lua_VERSION_MAJOR``
+  .. versionadded:: 4.2
+
   The major version of Lua found.
-``LUA_VERSION_MINOR``
+
+``Lua_VERSION_MINOR``
+  .. versionadded:: 4.2
+
   The minor version of Lua found.
-``LUA_VERSION_PATCH``
+
+``Lua_VERSION_PATCH``
+  .. versionadded:: 4.2
+
   The patch version of Lua found.
+
 ``LUA_LIBRARIES``
   Libraries needed to link against to use Lua.  This list includes both ``lua``
   and ``lualib`` libraries.
@@ -56,6 +75,35 @@ The following cache variables may also be set:
   The directory containing the Lua header files, such as ``lua.h``,
   ``lualib.h``, and ``lauxlib.h``, needed to use Lua.
 
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+The following variables are provided for backward compatibility:
+
+``LUA_VERSION_STRING``
+  .. deprecated:: 4.2
+    Superseded by the ``Lua_VERSION``.
+
+  The version of Lua found.
+
+``LUA_VERSION_MAJOR``
+  .. deprecated:: 4.2
+    Superseded by the ``Lua_VERSION_MAJOR``.
+
+  The major version of Lua found.
+
+``LUA_VERSION_MINOR``
+  .. deprecated:: 4.2
+    Superseded by the ``Lua_VERSION_MINOR``.
+
+  The minor version of Lua found.
+
+``LUA_VERSION_PATCH``
+  .. deprecated:: 4.2
+    Superseded by the ``Lua_VERSION_PATCH``.
+
+  The patch version of Lua found.
+
 Examples
 ^^^^^^^^
 
@@ -81,6 +129,7 @@ project target:
 #]=======================================================================]
 
 cmake_policy(PUSH)  # Policies apply to functions at definition-time
+cmake_policy(SET CMP0140 NEW)
 cmake_policy(SET CMP0159 NEW)  # file(STRINGS) with REGEX updates CMAKE_MATCH_<n>
 
 unset(_lua_include_subdirs)
@@ -146,7 +195,7 @@ function(_lua_set_version_vars)
 endfunction()
 
 function(_lua_get_header_version)
-  unset(LUA_VERSION_STRING PARENT_SCOPE)
+  unset(Lua_VERSION PARENT_SCOPE)
   set(_hdr_file "${LUA_INCLUDE_DIR}/lua.h")
 
   if (NOT EXISTS "${_hdr_file}")
@@ -159,27 +208,39 @@ function(_lua_get_header_version)
   file(STRINGS "${_hdr_file}" lua_version_strings
        REGEX "^#define[ \t]+LUA_(RELEASE[ \t]+\"Lua [0-9]|VERSION([ \t]+\"Lua [0-9]|_[MR])).*")
 
-  string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_MAJOR[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" LUA_VERSION_MAJOR ";${lua_version_strings};")
+  string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_MAJOR[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" Lua_VERSION_MAJOR ";${lua_version_strings};")
-  if (LUA_VERSION_MAJOR MATCHES "^[0-9]+$")
+
-    string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_MINOR[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" LUA_VERSION_MINOR ";${lua_version_strings};")
+  if (Lua_VERSION_MAJOR MATCHES "^[0-9]+$")
-    string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_RELEASE[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" LUA_VERSION_PATCH ";${lua_version_strings};")
+    string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_MINOR[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" Lua_VERSION_MINOR ";${lua_version_strings};")
-    set(LUA_VERSION_STRING "${LUA_VERSION_MAJOR}.${LUA_VERSION_MINOR}.${LUA_VERSION_PATCH}")
+    string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_RELEASE[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" Lua_VERSION_PATCH ";${lua_version_strings};")
+    set(Lua_VERSION "${Lua_VERSION_MAJOR}.${Lua_VERSION_MINOR}.${Lua_VERSION_PATCH}")
   else ()
-    string(REGEX REPLACE ".*;#define[ \t]+LUA_RELEASE[ \t]+\"Lua ([0-9.]+)\"[ \t]*;.*" "\\1" LUA_VERSION_STRING ";${lua_version_strings};")
+    string(REGEX REPLACE ".*;#define[ \t]+LUA_RELEASE[ \t]+\"Lua ([0-9.]+)\"[ \t]*;.*" "\\1" Lua_VERSION ";${lua_version_strings};")
-    if (NOT LUA_VERSION_STRING MATCHES "^[0-9.]+$")
+    if (NOT Lua_VERSION MATCHES "^[0-9.]+$")
-      string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION[ \t]+\"Lua ([0-9.]+)\"[ \t]*;.*" "\\1" LUA_VERSION_STRING ";${lua_version_strings};")
+      string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION[ \t]+\"Lua ([0-9.]+)\"[ \t]*;.*" "\\1" Lua_VERSION ";${lua_version_strings};")
     endif ()
-    string(REGEX REPLACE "^([0-9]+)\\.[0-9.]*$" "\\1" LUA_VERSION_MAJOR "${LUA_VERSION_STRING}")
+    string(REGEX REPLACE "^([0-9]+)\\.[0-9.]*$" "\\1" Lua_VERSION_MAJOR "${Lua_VERSION}")
-    string(REGEX REPLACE "^[0-9]+\\.([0-9]+)[0-9.]*$" "\\1" LUA_VERSION_MINOR "${LUA_VERSION_STRING}")
+    string(REGEX REPLACE "^[0-9]+\\.([0-9]+)[0-9.]*$" "\\1" Lua_VERSION_MINOR "${Lua_VERSION}")
-    string(REGEX REPLACE "^[0-9]+\\.[0-9]+\\.([0-9]).*" "\\1" LUA_VERSION_PATCH "${LUA_VERSION_STRING}")
+    string(REGEX REPLACE "^[0-9]+\\.[0-9]+\\.([0-9]).*" "\\1" Lua_VERSION_PATCH "${Lua_VERSION}")
   endif ()
   foreach (ver IN LISTS _lua_append_versions)
-    if (ver STREQUAL "${LUA_VERSION_MAJOR}.${LUA_VERSION_MINOR}")
+    if (ver STREQUAL "${Lua_VERSION_MAJOR}.${Lua_VERSION_MINOR}")
-      set(LUA_VERSION_MAJOR ${LUA_VERSION_MAJOR} PARENT_SCOPE)
+      set(LUA_VERSION_STRING "${Lua_VERSION}")
-      set(LUA_VERSION_MINOR ${LUA_VERSION_MINOR} PARENT_SCOPE)
+      set(LUA_VERSION_MAJOR "${Lua_VERSION_MAJOR}")
-      set(LUA_VERSION_PATCH ${LUA_VERSION_PATCH} PARENT_SCOPE)
+      set(LUA_VERSION_MINOR "${Lua_VERSION_MINOR}")
-      set(LUA_VERSION_STRING ${LUA_VERSION_STRING} PARENT_SCOPE)
+      set(LUA_VERSION_PATCH "${Lua_VERSION_PATCH}")
-      return()
+
+      return(
+        PROPAGATE
+          Lua_VERSION
+          Lua_VERSION_MAJOR
+          Lua_VERSION_MINOR
+          Lua_VERSION_PATCH
+          LUA_VERSION_STRING
+          LUA_VERSION_MAJOR
+          LUA_VERSION_MINOR
+          LUA_VERSION_PATCH
+      )
     endif ()
   endforeach ()
 endfunction()
@@ -208,9 +269,9 @@ function(_lua_find_header)
     endif()
     _lua_get_header_version()
     # Found accepted version -> Ok
-    if (LUA_VERSION_STRING)
+    if (Lua_VERSION)
       if (LUA_Debug)
-        message(STATUS "Found suitable version ${LUA_VERSION_STRING} in ${LUA_INCLUDE_DIR}/lua.h")
+        message(STATUS "Found suitable version ${Lua_VERSION} in ${LUA_INCLUDE_DIR}/lua.h")
       endif()
       return()
     endif()
@@ -230,12 +291,12 @@ _lua_find_header()
 _lua_get_header_version()
 unset(_lua_append_versions)
 
-if (LUA_VERSION_STRING)
+if (Lua_VERSION)
   set(_lua_library_names
-    lua${LUA_VERSION_MAJOR}${LUA_VERSION_MINOR}
+    lua${Lua_VERSION_MAJOR}${Lua_VERSION_MINOR}
-    lua${LUA_VERSION_MAJOR}.${LUA_VERSION_MINOR}
+    lua${Lua_VERSION_MAJOR}.${Lua_VERSION_MINOR}
-    lua-${LUA_VERSION_MAJOR}.${LUA_VERSION_MINOR}
+    lua-${Lua_VERSION_MAJOR}.${Lua_VERSION_MINOR}
-    lua.${LUA_VERSION_MAJOR}.${LUA_VERSION_MINOR}
+    lua.${Lua_VERSION_MAJOR}.${Lua_VERSION_MINOR}
     )
 endif ()
 
@@ -270,7 +331,7 @@ endif ()
 include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(Lua
                                   REQUIRED_VARS LUA_LIBRARIES LUA_INCLUDE_DIR
-                                  VERSION_VAR LUA_VERSION_STRING)
+                                  VERSION_VAR Lua_VERSION)
 
 mark_as_advanced(LUA_INCLUDE_DIR LUA_LIBRARY)
 

Modules/FindLua50.cmake

@@ -11,7 +11,13 @@ FindLua50
   not maintained anymore.  In new code use the latest supported Lua version and
   the version-agnostic module :module:`FindLua` instead.
 
-Finds the Lua library.  Lua is a embeddable scripting language.
+Finds the Lua library:
+
+.. code-block:: cmake
+
+  find_package(Lua50 [...])
+
+Lua is a embeddable scripting language.
 
 When working with Lua, its library headers are intended to be included in
 project source code as:

Modules/FindLua51.cmake

@@ -11,7 +11,13 @@ FindLua51
   not maintained anymore.  In new code use the latest supported Lua version and
   the version-agnostic module :module:`FindLua` instead.
 
-Finds the Lua library.  Lua is a embeddable scripting language.
+Finds the Lua library:
+
+.. code-block:: cmake
+
+  find_package(Lua51 [<version>] [...])
+
+Lua is a embeddable scripting language.
 
 When working with Lua, its library headers are intended to be included in
 project source code as:
@@ -35,9 +41,13 @@ Result Variables
 This module defines the following variables:
 
 ``Lua51_FOUND``
-  Boolean indicating whether Lua is found.  For backward compatibility, the
+  Boolean indicating whether (the requested version of) Lua is found.  For
-  ``LUA51_FOUND`` variable is also set to the same value.
+  backward compatibility, the ``LUA51_FOUND`` variable is also set to the
-``LUA_VERSION_STRING``
+  same value.
+
+``Lua_VERSION``
+  .. versionadded:: 4.2
+
   The version of Lua found.
 
 Cache Variables
@@ -48,9 +58,21 @@ The following cache variables may also be set:
 ``LUA_INCLUDE_DIR``
   The directory containing the Lua header files, such as ``lua.h``,
   ``lualib.h``, and ``lauxlib.h``, needed to use Lua.
+
 ``LUA_LIBRARIES``
   Libraries needed to link against to use Lua.
 
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+The following variables are provided for backward compatibility:
+
+``LUA_VERSION_STRING``
+  .. deprecated:: 4.2
+    Superseded by the ``Lua_VERSION``.
+
+  The version of Lua found.
+
 Examples
 ^^^^^^^^
 
@@ -118,14 +140,15 @@ endif()
 if(LUA_INCLUDE_DIR AND EXISTS "${LUA_INCLUDE_DIR}/lua.h")
   file(STRINGS "${LUA_INCLUDE_DIR}/lua.h" lua_version_str REGEX "^#define[ \t]+LUA_RELEASE[ \t]+\"Lua .+\"")
 
-  string(REGEX REPLACE "^#define[ \t]+LUA_RELEASE[ \t]+\"Lua ([^\"]+)\".*" "\\1" LUA_VERSION_STRING "${lua_version_str}")
+  string(REGEX REPLACE "^#define[ \t]+LUA_RELEASE[ \t]+\"Lua ([^\"]+)\".*" "\\1" Lua_VERSION "${lua_version_str}")
+  set(LUA_VERSION_STRING "${Lua_VERSION}")
   unset(lua_version_str)
 endif()
 
 include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(Lua51
                                   REQUIRED_VARS LUA_LIBRARIES LUA_INCLUDE_DIR
-                                  VERSION_VAR LUA_VERSION_STRING)
+                                  VERSION_VAR Lua_VERSION)
 
 mark_as_advanced(LUA_INCLUDE_DIR LUA_LIBRARIES LUA_LIBRARY LUA_MATH_LIBRARY)
 

Tests/RunCMake/FindLua/FindLuaTest.cmake

@@ -21,8 +21,11 @@ function(require_found path version)
     if(NOT "${LUA_INCLUDE_DIR}" STREQUAL "${path}")
         message(FATAL_ERROR "LUA_INCLUDE_PATH != path: '${LUA_INCLUDE_DIR}' != '${path}'")
     endif()
-    if(NOT LUA_VERSION_STRING MATCHES "^${version}\.[0-9]$")
+    if(NOT Lua_VERSION MATCHES "^${version}\.[0-9]$")
-        message(FATAL_ERROR "Wrong versionfound in '${LUA_INCLUDE_DIR}': ${LUA_VERSION_STRING} != ${version}")
+        message(FATAL_ERROR "Wrong version found in '${LUA_INCLUDE_DIR}': ${Lua_VERSION} != ${version}")
+    endif()
+    if(NOT LUA_VERSION_STRING STREQUAL Lua_VERSION)
+        message(FATAL_ERROR "LUA_VERSION_STRING != Lua_VERSION in '${LUA_INCLUDE_DIR}': ${LUA_VERSION_STRING} != ${Lua_VERSION}")
     endif()
 endfunction()