FindRuby: Drop upper-case RUBY_ results in favor of Ruby_ variables

Add policy CMP0185 for compatibility.

Fixes: #26640

Help/manual/cmake-policies.7.rst

@@ -98,6 +98,7 @@ Policies Introduced by CMake 4.0
 .. toctree::
    :maxdepth: 1
 
+   CMP0185: FindRuby no longer provides upper-case RUBY_* variables. </policy/CMP0185>
    CMP0184: MSVC runtime checks flags are selected by an abstraction. </policy/CMP0184>
    CMP0183: add_feature_info() supports full Condition Syntax. </policy/CMP0183>
    CMP0182: Create shared library archives by default on AIX. </policy/CMP0182>

Help/policy/CMP0185.rst

@@ -0,0 +1,25 @@
+CMP0185
+-------
+
+.. versionadded:: 4.0
+
+:module:`FindRuby` no longer provides upper-case ``RUBY_*`` variables.
+
+:module:`FindRuby` in CMake 3.31 and below provided result variables
+named with an upper-case ``RUBY_`` prefix.  CMake 3.18 renamed them
+with a ``Ruby_`` prefix to match the name of the package, but continued
+to provide the upper-case ``RUBY_`` variables for compatibility.
+
+CMake 4.0 and above prefer to provide only ``Ruby_`` variables and no
+longer provide ``RUBY_`` variables.  This policy provides compatibility
+with projects that have not been updated.
+
+The ``OLD`` behavior for this policy is to provide both ``Ruby_`` and
+``RUBY_`` variables.  The ``NEW`` behavior for this policy is to provide
+only ``Ruby_`` variables and not ``RUBY_`` variables.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.0
+.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt

Help/release/dev/FindRuby-compat-vars.rst

@@ -0,0 +1,5 @@
+FindRuby-compat-vars
+--------------------
+
+* The :module:`FindRuby` module no longer provides variables with the
+  upper-case ``RUBY_`` prefix.  See policy :policy:`CMP0185`.

Modules/FindRuby.cmake

@@ -44,21 +44,22 @@ This module will set the following variables in your project:
 
 .. versionchanged:: 3.18
   Previous versions of CMake used the ``RUBY_`` prefix for all variables.
-  The following variables are provided for compatibility reasons,
-  don't use them in new code:
 
-``RUBY_EXECUTABLE``
-  same as Ruby_EXECUTABLE.
-``RUBY_INCLUDE_DIRS``
-  same as Ruby_INCLUDE_DIRS.
-``RUBY_INCLUDE_PATH``
-  same as Ruby_INCLUDE_DIRS.
-``RUBY_LIBRARY``
-  same as Ruby_LIBRARY.
-``RUBY_VERSION``
-  same as Ruby_VERSION.
-``RUBY_FOUND``
-  same as Ruby_FOUND.
+.. deprecated:: 4.0
+  The following variables are deprecated.  See policy :policy:`CMP0185`.
+
+  ``RUBY_EXECUTABLE``
+    same as ``Ruby_EXECUTABLE``.
+  ``RUBY_INCLUDE_DIRS``
+    same as ``Ruby_INCLUDE_DIRS``.
+  ``RUBY_INCLUDE_PATH``
+    same as ``Ruby_INCLUDE_DIRS``.
+  ``RUBY_LIBRARY``
+    same as ``Ruby_LIBRARY``.
+  ``RUBY_VERSION``
+    same as ``Ruby_VERSION``.
+  ``RUBY_FOUND``
+    same as ``Ruby_FOUND``.
 
 Hints
 ^^^^^
@@ -85,20 +86,24 @@ Hints
     or that the ``RBENV_ROOT`` environment variable is defined.
 #]=======================================================================]
 
-# Backwards compatibility
-# Define camel case versions of input variables
-foreach (UPPER
-         RUBY_EXECUTABLE
-         RUBY_LIBRARY
-         RUBY_INCLUDE_DIR
-         RUBY_CONFIG_INCLUDE_DIR)
-  if (DEFINED ${UPPER})
-    string(REPLACE "RUBY_" "Ruby_" Camel ${UPPER})
-    if (NOT DEFINED ${Camel})
-      set(${Camel} ${${UPPER}})
+cmake_policy(GET CMP0185 _Ruby_CMP0185)
+
+if(NOT _Ruby_CMP0185 STREQUAL "NEW")
+  # Backwards compatibility
+  # Define camel case versions of input variables
+  foreach (UPPER
+           RUBY_EXECUTABLE
+           RUBY_LIBRARY
+           RUBY_INCLUDE_DIR
+           RUBY_CONFIG_INCLUDE_DIR)
+    if (DEFINED ${UPPER})
+      string(REPLACE "RUBY_" "Ruby_" Camel ${UPPER})
+      if (NOT DEFINED ${Camel})
+        set(${Camel} ${${UPPER}})
+      endif ()
     endif ()
-  endif ()
-endforeach ()
+  endforeach ()
+endif()
 
 #   Ruby_ARCHDIR=`$RUBY -r rbconfig -e 'printf("%s",Config::CONFIG@<:@"archdir"@:>@)'`
 #   Ruby_SITEARCHDIR=`$RUBY -r rbconfig -e 'printf("%s",Config::CONFIG@<:@"sitearchdir"@:>@)'`
@@ -451,32 +456,34 @@ mark_as_advanced(
     Ruby_CONFIG_INCLUDE_DIR
 )
 
-# Set some variables for compatibility with previous version of this file (no need to provide a CamelCase version of that...)
-set(RUBY_POSSIBLE_LIB_PATH ${_Ruby_POSSIBLE_LIB_DIR})
-set(RUBY_RUBY_LIB_PATH ${Ruby_RUBY_LIB_DIR})
-set(RUBY_INCLUDE_PATH ${Ruby_INCLUDE_DIRS})
+if(NOT _Ruby_CMP0185 STREQUAL "NEW")
+  # Set some variables for compatibility with previous version of this file (no need to provide a CamelCase version of that...)
+  set(RUBY_POSSIBLE_LIB_PATH ${_Ruby_POSSIBLE_LIB_DIR})
+  set(RUBY_RUBY_LIB_PATH ${Ruby_RUBY_LIB_DIR})
+  set(RUBY_INCLUDE_PATH ${Ruby_INCLUDE_DIRS})
 
-# Backwards compatibility
-# Define upper case versions of output variables
-foreach (Camel
-         Ruby_EXECUTABLE
-         Ruby_INCLUDE_DIRS
-         Ruby_LIBRARY
-         Ruby_VERSION
-         Ruby_VERSION_MAJOR
-         Ruby_VERSION_MINOR
-         Ruby_VERSION_PATCH
+  # Backwards compatibility
+  # Define upper case versions of output variables
+  foreach (Camel
+           Ruby_EXECUTABLE
+           Ruby_INCLUDE_DIRS
+           Ruby_LIBRARY
+           Ruby_VERSION
+           Ruby_VERSION_MAJOR
+           Ruby_VERSION_MINOR
+           Ruby_VERSION_PATCH
 
-         Ruby_ARCH_DIR
-         Ruby_ARCH
-         Ruby_HDR_DIR
-         Ruby_ARCHHDR_DIR
-         Ruby_RUBY_LIB_DIR
-         Ruby_SITEARCH_DIR
-         Ruby_SITELIB_DIR
-         Ruby_HAS_VENDOR_RUBY
-         Ruby_VENDORARCH_DIR
-         Ruby_VENDORLIB_DIR)
-  string(TOUPPER ${Camel} UPPER)
-  set(${UPPER} ${${Camel}})
-endforeach ()
+           Ruby_ARCH_DIR
+           Ruby_ARCH
+           Ruby_HDR_DIR
+           Ruby_ARCHHDR_DIR
+           Ruby_RUBY_LIB_DIR
+           Ruby_SITEARCH_DIR
+           Ruby_SITELIB_DIR
+           Ruby_HAS_VENDOR_RUBY
+           Ruby_VENDORARCH_DIR
+           Ruby_VENDORLIB_DIR)
+    string(TOUPPER ${Camel} UPPER)
+    set(${UPPER} ${${Camel}})
+  endforeach ()
+endif()

Source/cmPolicies.h

@@ -552,6 +552,9 @@ class cmMakefile;
          "add_feature_info() supports full Condition Syntax.", 4, 0, 0, WARN) \
   SELECT(POLICY, CMP0184,                                                     \
          "MSVC runtime check flags are selected by an abstraction.", 4, 0, 0, \
+         WARN)                                                                \
+  SELECT(POLICY, CMP0185,                                                     \
+         "FindRuby no longer provides upper-case RUBY_* variables.", 4, 0, 0, \
          WARN)
 
 #define CM_SELECT_ID(F, A1, A2, A3, A4, A5, A6) F(A1)

Tests/FindRuby/Test/CMakeLists.txt

@@ -2,11 +2,24 @@ cmake_minimum_required(VERSION 3.17)
 project(TestRuby LANGUAGES C)
 include(CTest)
 
+cmake_policy(SET CMP0185 NEW)
+
 find_package(Ruby 1.9.9 REQUIRED)
 if (NOT Ruby_FOUND)
   message (FATAL_ERROR "Failed to find Ruby >=1.9.9")
 endif()
 
+foreach(var_CMP0185
+    RUBY_EXECUTABLE
+    RUBY_INCLUDE_DIRS
+    RUBY_LIBRARY
+    RUBY_VERSION
+    )
+  if(DEFINED ${var_CMP0185})
+    message(FATAL_ERROR "Pre-CMP0185 result variable is set: ${var_CMP0185}")
+  endif()
+endforeach()
+
 add_executable(ruby_version ruby_version.c)
 target_include_directories(ruby_version PRIVATE ${Ruby_INCLUDE_DIRS})
 target_link_libraries(ruby_version PRIVATE ${Ruby_LIBRARIES})