From 21a5ca5fc2692f953ce44f0002d2c7a6c2122abb Mon Sep 17 00:00:00 2001
From: Charlie Savage <cfis@savagexi.com>
Date: Sun, 2 Feb 2025 15:47:22 -0800
Subject: [PATCH] FindRuby: Update comments

---
 Modules/FindRuby.cmake | 36 +++++++++++++++++-------------------
 1 file changed, 17 insertions(+), 19 deletions(-)

diff --git a/Modules/FindRuby.cmake b/Modules/FindRuby.cmake
index f047cbed21..bac96f0015 100644
--- a/Modules/FindRuby.cmake
+++ b/Modules/FindRuby.cmake
@@ -105,30 +105,20 @@ if(NOT _Ruby_CMP0185 STREQUAL "NEW")
   endforeach ()
 endif()
 
-#   Ruby_ARCHDIR=`$RUBY -r rbconfig -e 'printf("%s",Config::CONFIG@<:@"archdir"@:>@)'`
-#   Ruby_SITEARCHDIR=`$RUBY -r rbconfig -e 'printf("%s",Config::CONFIG@<:@"sitearchdir"@:>@)'`
-#   Ruby_SITEDIR=`$RUBY -r rbconfig -e 'printf("%s",Config::CONFIG@<:@"sitelibdir"@:>@)'`
-#   Ruby_LIBDIR=`$RUBY -r rbconfig -e 'printf("%s",Config::CONFIG@<:@"libdir"@:>@)'`
-#   Ruby_LIBRUBYARG=`$RUBY -r rbconfig -e 'printf("%s",Config::CONFIG@<:@"LIBRUBYARG_SHARED"@:>@)'`
-
-# uncomment the following line to get debug output for this file
+# Uncomment the following line to get debug output for this file
 # set(CMAKE_MESSAGE_LOG_LEVEL DEBUG)
 
 # Determine the list of possible names of the ruby executable depending
 # on which version of ruby is required
 set(_Ruby_POSSIBLE_EXECUTABLE_NAMES ruby)
 
-# Set name of possible executables, ignoring the minor
-# Eg:
-# 3.2.6 => from ruby34 to ruby32 included
-# 3.2   => from ruby34 to ruby32 included
-# 3     => from ruby34 to ruby30 included
-# empty => from ruby34 to ruby18 included
+# If the user has not specified a Ruby version, create a list of Ruby versions
+# to check going from 1.8 to 3.4
 if (NOT Ruby_FIND_VERSION_EXACT)
   foreach (_ruby_version RANGE 34 18 -1)
     string(SUBSTRING "${_ruby_version}" 0 1 _ruby_major_version)
     string(SUBSTRING "${_ruby_version}" 1 1 _ruby_minor_version)
-    # Append both rubyX.Y and rubyXY (eg: ruby2.7 ruby27)
+    # Append both rubyX.Y and rubyXY (eg: ruby3.4 ruby34)
     list(APPEND _Ruby_POSSIBLE_EXECUTABLE_NAMES ruby${_ruby_major_version}.${_ruby_minor_version} ruby${_ruby_major_version}${_ruby_minor_version})
   endforeach ()
 endif ()
@@ -142,6 +132,8 @@ elseif (NOT DEFINED Ruby_FIND_VIRTUALENV)
   set(Ruby_FIND_VIRTUALENV "FIRST")
 endif ()
 
+# Validate the found Ruby interpreter to make sure that it is
+# callable and that its version matches the requested version
 function(_RUBY_VALIDATE_INTERPRETER result_var path)
   # Get the interpreter version
   execute_process(COMMAND "${path}" -e "puts RUBY_VERSION"
@@ -172,21 +164,25 @@ function(_RUBY_VALIDATE_INTERPRETER result_var path)
   set(${result_var} TRUE PARENT_SCOPE)
 endfunction()
 
+# Query Ruby RBConfig module for the specified variable (_RUBY_CONFIG_VAR)
 function(_RUBY_CONFIG_VAR RBVAR OUTVAR)
   execute_process(COMMAND ${Ruby_EXECUTABLE} -r rbconfig -e "print RbConfig::CONFIG['${RBVAR}']"
                   RESULT_VARIABLE _Ruby_SUCCESS
                   OUTPUT_VARIABLE _Ruby_OUTPUT
                   ERROR_QUIET)
+
+  # Config was deprecated in Ruby 1.9 and then removed in Ruby 2 - so this is for ancient code
   if (_Ruby_SUCCESS OR _Ruby_OUTPUT STREQUAL "")
     execute_process(COMMAND ${Ruby_EXECUTABLE} -r rbconfig -e "print Config::CONFIG['${RBVAR}']"
                     RESULT_VARIABLE _Ruby_SUCCESS
                     OUTPUT_VARIABLE _Ruby_OUTPUT
                     ERROR_QUIET)
   endif ()
+
   set(${OUTVAR} "${_Ruby_OUTPUT}" PARENT_SCOPE)
 endfunction()
 
-####  Check RVM virtual environment ###
+# Check for RVM virtual environments
 function(_RUBY_CHECK_RVM)
   if (NOT DEFINED ENV{MY_RUBY_HOME})
     return()
@@ -208,7 +204,7 @@ function(_RUBY_CHECK_RVM)
   endif ()
 endfunction()
 
-####  Check RBENV virtual environment ###
+# Check for RBENV virtual environments
 function(_RUBY_CHECK_RBENV)
   find_program(Ruby_RBENV_EXECUTABLE
                NAMES rbenv
@@ -242,7 +238,7 @@ function(_RUBY_CHECK_RBENV)
   endif ()
 endfunction()
 
-####  Check system installed Ruby ###
+# Check system installed Ruby
 function(_RUBY_CHECK_SYSTEM)
   find_program(Ruby_EXECUTABLE
                NAMES ${_Ruby_POSSIBLE_EXECUTABLE_NAMES}
@@ -264,11 +260,13 @@ if (NOT Ruby_EXECUTABLE AND Ruby_FIND_VIRTUALENV MATCHES "^(FIRST|ONLY)$")
   endif ()
 endif ()
 
-# Check for system installed Ruby
+# Fallback to system installed Ruby
 if (NOT Ruby_EXECUTABLE AND NOT Ruby_FIND_VIRTUALENV STREQUAL "ONLY")
   _RUBY_CHECK_SYSTEM()
 endif ()
 
+# We found a new Ruby or a Ruby that is different than the last one we found.
+# So reload a number of variables by querying the Ruby interpreter.
 if (Ruby_EXECUTABLE AND NOT Ruby_EXECUTABLE STREQUAL "${_Ruby_EXECUTABLE_LAST_QUERIED}")
   # query the ruby version
   _RUBY_CONFIG_VAR("MAJOR" Ruby_VERSION_MAJOR)
@@ -387,7 +385,7 @@ if (Ruby_FIND_VERSION VERSION_GREATER_EQUAL "1.9" OR Ruby_VERSION VERSION_GREATE
   set(Ruby_INCLUDE_DIRS ${Ruby_INCLUDE_DIRS} ${Ruby_CONFIG_INCLUDE_DIR})
 endif ()
 
-# Determine the list of possible names for the ruby library
+# Determine the list of possible names for the Ruby shared library
 set(_Ruby_POSSIBLE_LIB_NAMES ruby ruby-static ruby${_Ruby_VERSION_SHORT} ruby${_Ruby_VERSION_SHORT_NODOT} ruby${_Ruby_NODOT_VERSION} ruby-${_Ruby_VERSION_SHORT} ruby-${Ruby_VERSION})
 
 if (WIN32)