cmake_command: Add command to INVOKE other commands by name

Fixes: #18392

29 files changed, 164 insertions, 0 deletions

diff --git a/Help/command/cmake_command.rst b/Help/command/cmake_command.rst
new file mode 100644
index 0000000..9281647
--- /dev/null
+++ b/Help/command/cmake_command.rst
@@ -0,0 +1,40 @@
+cmake_command
+-------------
+
+Call meta-operations on CMake commands.
+
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  cmake_command(`INVOKE`_ <command> [<args>...])
+
+Introduction
+^^^^^^^^^^^^
+
+This command will call meta-operations on built-in CMake commands or
+those created via the :command:`macro` or :command:`function` commands.
+
+Invoking
+^^^^^^^^
+
+.. _INVOKE:
+
+.. code-block:: cmake
+
+  cmake_command(INVOKE <command> [<args>...])
+
+Invokes the named ``<command>`` with the given arguments (if any).
+For example, the code:
+
+.. code-block:: cmake
+
+  set(message_command "message")
+  cmake_command(INVOKE ${message_command} STATUS "Hello World!")
+
+is equivalent to
+
+.. code-block:: cmake
+
+  message(STATUS "Hello World!")
diff --git a/Help/command/function.rst b/Help/command/function.rst
index 53ba754..30938b3 100644
--- a/Help/command/function.rst
+++ b/Help/command/function.rst
@@ -44,11 +44,15 @@ can be invoked through any of
   foo()
   Foo()
   FOO()
+  cmake_command(INVOKE foo)
 
 and so on. However, it is strongly recommended to stay with the
 case chosen in the function definition. Typically functions use
 all-lowercase names.
 
+The :command:`cmake_command(INVOKE ...)` command can also be used to invoke the
+function.
+
 Arguments
 ^^^^^^^^^
 
diff --git a/Help/command/macro.rst b/Help/command/macro.rst
index 3f6f2f9..ee955cb 100644
--- a/Help/command/macro.rst
+++ b/Help/command/macro.rst
@@ -42,11 +42,15 @@ can be invoked through any of
   foo()
   Foo()
   FOO()
+  cmake_command(INVOKE foo)
 
 and so on. However, it is strongly recommended to stay with the
 case chosen in the macro definition.  Typically macros use
 all-lowercase names.
 
+The :command:`cmake_command(INVOKE ...)` command can also be used to invoke the
+macro.
+
 Arguments
 ^^^^^^^^^
 
diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst
index 59ba897..87743b4 100644
--- a/Help/manual/cmake-commands.7.rst
+++ b/Help/manual/cmake-commands.7.rst
@@ -16,6 +16,7 @@ These commands are always available.
    :maxdepth: 1
 
    /command/break
+   /command/cmake_command
    /command/cmake_host_system_information
    /command/cmake_minimum_required
    /command/cmake_parse_arguments
diff --git a/Help/release/dev/cmake_command-command.rst b/Help/release/dev/cmake_command-command.rst
new file mode 100644
index 0000000..ebe75b1
--- /dev/null
+++ b/Help/release/dev/cmake_command-command.rst
@@ -0,0 +1,6 @@
+cmake_command
+-------------
+
+* The :command:`cmake_command()` command was added for meta-operations on
+  scripted or built-in commands, starting with a mode to ``INVOKE`` other
+  commands.
diff --git a/Source/CMakeLists.txt b/Source/CMakeLists.txt
index c57f713..24370aa 100644
--- a/Source/CMakeLists.txt
+++ b/Source/CMakeLists.txt
@@ -484,6 +484,8 @@ set(SRCS
   cmBuildCommand.h
   cmBuildNameCommand.cxx
   cmBuildNameCommand.h
+  cmCMakeCommand.cxx
+  cmCMakeCommand.h
   cmCMakeHostSystemInformationCommand.cxx
   cmCMakeHostSystemInformationCommand.h
   cmCMakeMinimumRequired.cxx
diff --git a/Source/cmCMakeCommand.cxx b/Source/cmCMakeCommand.cxx
new file mode 100644
index 0000000..5699086
--- /dev/null
+++ b/Source/cmCMakeCommand.cxx
@@ -0,0 +1,47 @@
+/* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+   file Copyright.txt or https://cmake.org/licensing for details.  */
+#include "cmCMakeCommand.h"
+
+#include <cstddef>
+
+#include "cmExecutionStatus.h"
+#include "cmListFileCache.h"
+#include "cmMakefile.h"
+
+bool cmCMakeCommand(std::vector<std::string> const& args,
+                    cmExecutionStatus& status)
+{
+  if (args.empty()) {
+    status.SetError("called with incorrect number of arguments");
+    return false;
+  }
+
+  cmMakefile& makefile = status.GetMakefile();
+  cmListFileContext context = makefile.GetExecutionContext();
+
+  if (args[0] == "INVOKE") {
+    if (args.size() == 1) {
+      status.SetError("called with incorrect number of arguments");
+      return false;
+    }
+
+    // First argument is the name of the function to call
+    cmListFileFunction func;
+    func.Name = args[1];
+    func.Line = context.Line;
+
+    // The rest of the arguments are passed to the function call above
+    func.Arguments.resize(args.size() - 1);
+    for (size_t i = 2; i < args.size(); ++i) {
+      cmListFileArgument lfarg;
+      lfarg.Line = context.Line;
+      lfarg.Value = args[i];
+      func.Arguments.emplace_back(lfarg);
+    }
+
+    return makefile.ExecuteCommand(func, status);
+  }
+
+  status.SetError("called with unknown meta-operation");
+  return false;
+}
diff --git a/Source/cmCMakeCommand.h b/Source/cmCMakeCommand.h
new file mode 100644
index 0000000..cf9f4c3
--- /dev/null
+++ b/Source/cmCMakeCommand.h
@@ -0,0 +1,20 @@
+/* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+   file Copyright.txt or https://cmake.org/licensing for details.  */
+#ifndef cmCMakeCommand_h
+#define cmCMakeCommand_h
+
+#include "cmConfigure.h" // IWYU pragma: keep
+
+#include <string>
+#include <vector>
+
+class cmExecutionStatus;
+
+/**
+ * \brief Calls a scripted or build-in command
+ *
+ */
+bool cmCMakeCommand(std::vector<std::string> const& args,
+                    cmExecutionStatus& status);
+
+#endif
diff --git a/Source/cmCommands.cxx b/Source/cmCommands.cxx
index 896b6a9..28b4267 100644
--- a/Source/cmCommands.cxx
+++ b/Source/cmCommands.cxx
@@ -91,6 +91,7 @@
 #  include "cmAddLinkOptionsCommand.h"
 #  include "cmAuxSourceDirectoryCommand.h"
 #  include "cmBuildNameCommand.h"
+#  include "cmCMakeCommand.h"
 #  include "cmCMakeHostSystemInformationCommand.h"
 #  include "cmExportCommand.h"
 #  include "cmExportLibraryDependenciesCommand.h"
@@ -196,6 +197,7 @@ void GetScriptingCommands(cmState* state)
     "match the opening WHILE command.");
 
 #if !defined(CMAKE_BOOTSTRAP)
+  state->AddBuiltinCommand("cmake_command", cmCMakeCommand);
   state->AddBuiltinCommand("cmake_host_system_information",
                            cmCMakeHostSystemInformationCommand);
   state->AddBuiltinCommand("load_cache", cmLoadCacheCommand);
diff --git a/Tests/RunCMake/CMakeLists.txt b/Tests/RunCMake/CMakeLists.txt
index e9f8bca..4f6787e 100644
--- a/Tests/RunCMake/CMakeLists.txt
+++ b/Tests/RunCMake/CMakeLists.txt
@@ -651,3 +651,5 @@ add_RunCMake_test("CTestCommandExpandLists")
 
 add_RunCMake_test(PrecompileHeaders)
 add_RunCMake_test("UnityBuild")
+
+add_RunCMake_test(cmake_command)
diff --git a/Tests/RunCMake/cmake_command/CMakeLists.txt b/Tests/RunCMake/cmake_command/CMakeLists.txt
new file mode 100644
index 0000000..2632ffa
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/CMakeLists.txt
@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 3.16)
+project(${RunCMake_TEST} NONE)
+include(${RunCMake_TEST}.cmake)
diff --git a/Tests/RunCMake/cmake_command/RunCMakeTest.cmake b/Tests/RunCMake/cmake_command/RunCMakeTest.cmake
new file mode 100644
index 0000000..d338cd8
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/RunCMakeTest.cmake
@@ -0,0 +1,8 @@
+include(RunCMake)
+
+run_cmake(cmake_command_no_parameters)
+run_cmake(cmake_command_unknown_meta_operation)
+run_cmake(cmake_command_invoke_message)
+run_cmake(cmake_command_invoke_message_fatal_error)
+run_cmake(cmake_command_invoke_no_parameters)
+run_cmake(cmake_command_invoke_unknown_function)
diff --git a/Tests/RunCMake/cmake_command/cmake_command_invoke_message-stderr.txt b/Tests/RunCMake/cmake_command/cmake_command_invoke_message-stderr.txt
new file mode 100644
index 0000000..cfc8694
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_invoke_message-stderr.txt
@@ -0,0 +1 @@
+WORKS!
diff --git a/Tests/RunCMake/cmake_command/cmake_command_invoke_message.cmake b/Tests/RunCMake/cmake_command/cmake_command_invoke_message.cmake
new file mode 100644
index 0000000..336d78a
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_invoke_message.cmake
@@ -0,0 +1 @@
+cmake_command(INVOKE message WORKS!)
diff --git a/Tests/RunCMake/cmake_command/cmake_command_invoke_message_fatal_error-result.txt b/Tests/RunCMake/cmake_command/cmake_command_invoke_message_fatal_error-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_invoke_message_fatal_error-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/cmake_command/cmake_command_invoke_message_fatal_error-stderr.txt b/Tests/RunCMake/cmake_command/cmake_command_invoke_message_fatal_error-stderr.txt
new file mode 100644
index 0000000..2c9dab5
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_invoke_message_fatal_error-stderr.txt
@@ -0,0 +1,5 @@
+CMake Error at cmake_command_invoke_message_fatal_error.cmake:1 \(message\):
+  error!
+Call Stack \(most recent call first\):
+  cmake_command_invoke_message_fatal_error.cmake:1 \(cmake_command\)
+  CMakeLists.txt:3 \(include\)
diff --git a/Tests/RunCMake/cmake_command/cmake_command_invoke_message_fatal_error.cmake b/Tests/RunCMake/cmake_command/cmake_command_invoke_message_fatal_error.cmake
new file mode 100644
index 0000000..6b42764
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_invoke_message_fatal_error.cmake
@@ -0,0 +1 @@
+cmake_command(INVOKE message FATAL_ERROR error!)
diff --git a/Tests/RunCMake/cmake_command/cmake_command_invoke_no_parameters-result.txt b/Tests/RunCMake/cmake_command/cmake_command_invoke_no_parameters-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_invoke_no_parameters-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/cmake_command/cmake_command_invoke_no_parameters-stderr.txt b/Tests/RunCMake/cmake_command/cmake_command_invoke_no_parameters-stderr.txt
new file mode 100644
index 0000000..7741b41
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_invoke_no_parameters-stderr.txt
@@ -0,0 +1,2 @@
+CMake Error at cmake_command_invoke_no_parameters.cmake:1 \(cmake_command\):
+  cmake_command called with incorrect number of arguments
diff --git a/Tests/RunCMake/cmake_command/cmake_command_invoke_no_parameters.cmake b/Tests/RunCMake/cmake_command/cmake_command_invoke_no_parameters.cmake
new file mode 100644
index 0000000..b9c5e14
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_invoke_no_parameters.cmake
@@ -0,0 +1 @@
+cmake_command(INVOKE)
diff --git a/Tests/RunCMake/cmake_command/cmake_command_invoke_unknown_function-result.txt b/Tests/RunCMake/cmake_command/cmake_command_invoke_unknown_function-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_invoke_unknown_function-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/cmake_command/cmake_command_invoke_unknown_function-stderr.txt b/Tests/RunCMake/cmake_command/cmake_command_invoke_unknown_function-stderr.txt
new file mode 100644
index 0000000..50a81a3
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_invoke_unknown_function-stderr.txt
@@ -0,0 +1,2 @@
+CMake Error at cmake_command_invoke_unknown_function.cmake:1 \(unknown\):
+  Unknown CMake command "unknown".
diff --git a/Tests/RunCMake/cmake_command/cmake_command_invoke_unknown_function.cmake b/Tests/RunCMake/cmake_command/cmake_command_invoke_unknown_function.cmake
new file mode 100644
index 0000000..f19a04b
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_invoke_unknown_function.cmake
@@ -0,0 +1 @@
+cmake_command(INVOKE unknown)
diff --git a/Tests/RunCMake/cmake_command/cmake_command_no_parameters-result.txt b/Tests/RunCMake/cmake_command/cmake_command_no_parameters-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_no_parameters-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/cmake_command/cmake_command_no_parameters-stderr.txt b/Tests/RunCMake/cmake_command/cmake_command_no_parameters-stderr.txt
new file mode 100644
index 0000000..772b604
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_no_parameters-stderr.txt
@@ -0,0 +1,2 @@
+CMake Error at cmake_command_no_parameters.cmake:1 \(cmake_command\):
+  cmake_command called with incorrect number of arguments
diff --git a/Tests/RunCMake/cmake_command/cmake_command_no_parameters.cmake b/Tests/RunCMake/cmake_command/cmake_command_no_parameters.cmake
new file mode 100644
index 0000000..b9c5e14
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_no_parameters.cmake
@@ -0,0 +1 @@
+cmake_command(INVOKE)
diff --git a/Tests/RunCMake/cmake_command/cmake_command_unknown_meta_operation-result.txt b/Tests/RunCMake/cmake_command/cmake_command_unknown_meta_operation-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_unknown_meta_operation-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/cmake_command/cmake_command_unknown_meta_operation-stderr.txt b/Tests/RunCMake/cmake_command/cmake_command_unknown_meta_operation-stderr.txt
new file mode 100644
index 0000000..7b9b915
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_unknown_meta_operation-stderr.txt
@@ -0,0 +1,2 @@
+CMake Error at cmake_command_unknown_meta_operation.cmake:1 \(cmake_command\):
+  cmake_command called with unknown meta-operation
diff --git a/Tests/RunCMake/cmake_command/cmake_command_unknown_meta_operation.cmake b/Tests/RunCMake/cmake_command/cmake_command_unknown_meta_operation.cmake
new file mode 100644
index 0000000..f7c77e5
--- /dev/null
+++ b/Tests/RunCMake/cmake_command/cmake_command_unknown_meta_operation.cmake
@@ -0,0 +1 @@
+cmake_command(UNKNOWN)