cmake_print_variables: Deprecate in favor of cmake_language(PRINT_VARIABLES)

Re-implement it in terms of the replacement command.

Issue: #27513

Help/release/dev/print_variables.rst

@@ -4,3 +4,7 @@ print_variables
 * The :command:`cmake_language(PRINT_VARIABLES)` command was added
   to print variables and their values in human-readable form for
   debugging.
+
+* The :module:`CMakePrintHelpers` module's :command:`cmake_print_variables`
+  command is now deprecated in favor of
+  :command:`cmake_language(PRINT_VARIABLES)`.

Modules/CMakePrintHelpers.cmake

@@ -41,6 +41,10 @@ This module provides the following commands:
 
 .. command:: cmake_print_variables
 
+  .. deprecated:: 4.5
+
+    Use :command:`cmake_language(PRINT_VARIABLES)` instead.
+
   Prints each variable name followed by its value:
 
   .. code-block:: cmake
@@ -86,14 +90,23 @@ Gives::
 #]=======================================================================]
 
 function(cmake_print_variables)
-  set(msg "")
-  foreach(var ${ARGN})
-    if(msg)
-      string(APPEND msg " ; ")
+  message(DEPRECATION
+    "cmake_print_variables() is deprecated. Use cmake_language(PRINT_VARIABLES) instead.")
+
+  set(_cpvmode_reserved_keywords
+    ALL NAMED NAME_REGEX VALUE_REGEX IGNORE_CASE __CMAKE_PRINT_VARIABLES)
+  foreach(_arg IN LISTS ARGV)
+    if(_arg IN_LIST _cpvmode_reserved_keywords)
+      message(FATAL_ERROR
+        "cmake_print_variables() got \"${_arg}\", which is a reserved "
+        "keyword in cmake_language(PRINT_VARIABLES).  If you wish to use "
+        "it as a keyword to the command, use cmake_language(PRINT_VARIABLES) "
+        "directly.")
+      return()
     endif()
-    string(APPEND msg "${var}=\"${${var}}\"")
   endforeach()
-  message(STATUS "${msg}")
+
+  cmake_language(PRINT_VARIABLES NAMED ${ARGN} __CMAKE_PRINT_VARIABLES)
 endfunction()
 
 

Tests/RunCMake/PrintHelpers/RunCMakeTest.cmake

@@ -1,5 +1,10 @@
 include(RunCMake)
 
-run_cmake(Variables)
+block()
+  set(RunCMake_TEST_OPTIONS -Wno-deprecated)
+  run_cmake(VariablesArgForwarding)
+  run_cmake(VariablesReservedKeyword)
+endblock()
+run_cmake(VariablesDeprecation)
 run_cmake(Properties)
 run_cmake(PropertiesSources)

Tests/RunCMake/PrintHelpers/Variables-stdout.txt

@@ -1 +0,0 @@
--- source_dir="src" ; binary_dir="build"

Tests/RunCMake/PrintHelpers/VariablesArgForwarding-stdout.txt

@@ -0,0 +1 @@
+-- source_dir="src" ; binary_dir="build" ; NOT_SET=""

Tests/RunCMake/PrintHelpers/VariablesArgForwarding.cmake

@@ -1,6 +1,6 @@
+include(CMakePrintHelpers)
 
 set(source_dir "src")
 set(binary_dir "build")
 
-include(CMakePrintHelpers)
-cmake_print_variables(source_dir binary_dir)
+cmake_print_variables(source_dir binary_dir NOT_SET)

Tests/RunCMake/PrintHelpers/VariablesDeprecation-stderr.txt

@@ -0,0 +1,5 @@
+CMake Warning \(deprecated\) at .*CMakePrintHelpers\.cmake:[0-9]+ \(message\):
+  cmake_print_variables\(\) is deprecated\.  Use cmake_language\(PRINT_VARIABLES\)
+  instead\.
+Call Stack \(most recent call first\):
+  VariablesDeprecation\.cmake:[0-9]+ \(cmake_print_variables\)

Tests/RunCMake/PrintHelpers/VariablesDeprecation-stdout.txt

@@ -0,0 +1 @@
+-- my_var="value"

Tests/RunCMake/PrintHelpers/VariablesDeprecation.cmake

@@ -0,0 +1,4 @@
+include(CMakePrintHelpers)
+
+set(my_var "value")
+cmake_print_variables(my_var)

Tests/RunCMake/PrintHelpers/VariablesReservedKeyword-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/PrintHelpers/VariablesReservedKeyword-stderr.txt

@@ -0,0 +1,6 @@
+CMake Error at .*CMakePrintHelpers\.cmake:[0-9]+ \(message\):
+  cmake_print_variables\(\) got "ALL", which is a reserved keyword in
+  cmake_language\(PRINT_VARIABLES\)\.  If you wish to use it as a keyword to the
+  command, use cmake_language\(PRINT_VARIABLES\) directly\.
+Call Stack \(most recent call first\):
+  VariablesReservedKeyword\.cmake:[0-9]+ \(cmake_print_variables\)

Tests/RunCMake/PrintHelpers/VariablesReservedKeyword.cmake

@@ -0,0 +1,5 @@
+include(CMakePrintHelpers)
+
+# ALL is a reserved cmake_language(PRINT_VARIABLES) keyword; the wrapper must
+# reject it up front rather than forward it.
+cmake_print_variables(ALL)