cmake_language: Add EXIT subcommand

Add tests to cover these cases:

* run as regular CMake module, in NORMAL_MODE (expected to fail);
* run as CMake script in SCRIPT_MODE (expected to exit with given code);
* run as CMake script that `include()`-s another script with EXIT subcommand;
* run as CMake script which EVAL-uates EXIT subcommand via
  `cmake_language(EVAL CODE "<cmake code>")`.

Fixes: #23162

29 files changed, 93 insertions, 0 deletions

diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst
index 4b64eb6..45ac569 100644
--- a/Help/command/cmake_language.rst
+++ b/Help/command/cmake_language.rst
@@ -15,6 +15,7 @@ Synopsis
   cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...])
   cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...)
   cmake_language(`GET_MESSAGE_LOG_LEVEL`_ <out-var>)
+  cmake_language(`EXIT`_ <exit-code>)
 
 Introduction
 ^^^^^^^^^^^^
@@ -506,3 +507,25 @@ Getting current message log level
   If both the command line option and the variable are set, the command line
   option takes precedence. If neither are set, the default logging level
   is returned.
+
+Terminating Scripts
+^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.29
+
+.. _EXIT:
+.. _exit-code:
+
+.. code-block:: cmake
+
+.. signature::
+  cmake_language(EXIT <exit-code>)
+
+  Terminate the current :option:`cmake -P` script and exit with ``<exit-code>``.
+
+  This command works only in :ref:`script mode <Script Processing Mode>`.
+
+  The ``<exit-code>`` should be non-negative.
+  If ``<exit-code>`` is negative then the behavior
+  is unspecified (e.g., on Windows the error code -1
+  becomes ``0xffffffff``, and on Linux it becomes ``255``).
diff --git a/Help/release/dev/cmake-language-exit.rst b/Help/release/dev/cmake-language-exit.rst
new file mode 100644
index 0000000..42e8ae2
--- /dev/null
+++ b/Help/release/dev/cmake-language-exit.rst
@@ -0,0 +1,5 @@
+cmake-language-exit
+-------------------
+
+* The :command:`cmake_language()` command gained a new ``EXIT``
+  sub-command to exit scripts with a specified exit code.
diff --git a/Source/cmCMakeLanguageCommand.cxx b/Source/cmCMakeLanguageCommand.cxx
index 329427c..9ffc363 100644
--- a/Source/cmCMakeLanguageCommand.cxx
+++ b/Source/cmCMakeLanguageCommand.cxx
@@ -398,6 +398,32 @@ bool cmCMakeLanguageCommand(std::vector<cmListFileArgument> const& args,
   if (!moreArgs()) {
     return FatalError(status, "called with incorrect number of arguments");
   }
+  if (expArgs[expArg] == "EXIT"_s) {
+    ++expArg; // consume "EXIT".
+
+    if (!moreArgs()) {
+      return FatalError(status, "EXIT requires one argument");
+    }
+
+    auto workingMode =
+      status.GetMakefile().GetCMakeInstance()->GetWorkingMode();
+    if (workingMode != cmake::SCRIPT_MODE) {
+      return FatalError(status, "EXIT can be used only in SCRIPT mode");
+    }
+
+    long retCode = 0;
+
+    if (!cmStrToLong(expArgs[expArg], &retCode)) {
+      return FatalError(status,
+                        cmStrCat("EXIT requires one integral argument, got \"",
+                                 expArgs[expArg], '\"'));
+    }
+
+    if (workingMode == cmake::SCRIPT_MODE) {
+      status.SetExitCode(static_cast<int>(retCode));
+    }
+    return true;
+  }
 
   if (expArgs[expArg] == "SET_DEPENDENCY_PROVIDER"_s) {
     finishArgs();
diff --git a/Tests/RunCMake/cmake_language/RunCMakeTest.cmake b/Tests/RunCMake/cmake_language/RunCMakeTest.cmake
index 38ce10b..ac4aec8 100644
--- a/Tests/RunCMake/cmake_language/RunCMakeTest.cmake
+++ b/Tests/RunCMake/cmake_language/RunCMakeTest.cmake
@@ -84,6 +84,13 @@ run_cmake(defer_get_call_id_var)
 run_cmake(defer_missing_arg)
 run_cmake(defer_missing_call)
 run_cmake(defer_unknown_option)
+run_cmake(exit_0)
+run_cmake(exit_5)
+run_cmake_script(exit_0_script)
+run_cmake_script(exit_5_script)
+run_cmake_script(exit_0_script_with_command)
+run_cmake_script(exit_7_script_in_include)
+run_cmake_script(exit_8_script_in_recursive_cmake_language)
 
 # Default log level
 run_cmake_command(
diff --git a/Tests/RunCMake/cmake_language/exit_0-result.txt b/Tests/RunCMake/cmake_language/exit_0-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_0-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/cmake_language/exit_0-stderr.txt b/Tests/RunCMake/cmake_language/exit_0-stderr.txt
new file mode 100644
index 0000000..04a586e
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_0-stderr.txt
@@ -0,0 +1,2 @@
+CMake Error at exit_0.cmake:1 \(cmake_language\):
+  cmake_language EXIT can be used only in SCRIPT mode
diff --git a/Tests/RunCMake/cmake_language/exit_0.cmake b/Tests/RunCMake/cmake_language/exit_0.cmake
new file mode 100644
index 0000000..53a150e
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_0.cmake
@@ -0,0 +1 @@
+cmake_language(EXIT 0)
diff --git a/Tests/RunCMake/cmake_language/exit_0_script-result.txt b/Tests/RunCMake/cmake_language/exit_0_script-result.txt
new file mode 100644
index 0000000..573541a
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_0_script-result.txt
@@ -0,0 +1 @@
+0
diff --git a/Tests/RunCMake/cmake_language/exit_0_script-stderr.txt b/Tests/RunCMake/cmake_language/exit_0_script-stderr.txt
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_0_script-stderr.txt
diff --git a/Tests/RunCMake/cmake_language/exit_0_script.cmake b/Tests/RunCMake/cmake_language/exit_0_script.cmake
new file mode 100644
index 0000000..53a150e
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_0_script.cmake
@@ -0,0 +1 @@
+cmake_language(EXIT 0)
diff --git a/Tests/RunCMake/cmake_language/exit_0_script_with_command-result.txt b/Tests/RunCMake/cmake_language/exit_0_script_with_command-result.txt
new file mode 100644
index 0000000..573541a
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_0_script_with_command-result.txt
@@ -0,0 +1 @@
+0
diff --git a/Tests/RunCMake/cmake_language/exit_0_script_with_command-stderr.txt b/Tests/RunCMake/cmake_language/exit_0_script_with_command-stderr.txt
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_0_script_with_command-stderr.txt
diff --git a/Tests/RunCMake/cmake_language/exit_0_script_with_command.cmake b/Tests/RunCMake/cmake_language/exit_0_script_with_command.cmake
new file mode 100644
index 0000000..ebc4ca7
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_0_script_with_command.cmake
@@ -0,0 +1,3 @@
+cmake_language(EXIT 0)
+
+message(FATAL_ERROR "cmake_language(EXIT 0) doesn't work")
diff --git a/Tests/RunCMake/cmake_language/exit_5-result.txt b/Tests/RunCMake/cmake_language/exit_5-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_5-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/cmake_language/exit_5-stderr.txt b/Tests/RunCMake/cmake_language/exit_5-stderr.txt
new file mode 100644
index 0000000..ad232f8
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_5-stderr.txt
@@ -0,0 +1,2 @@
+CMake Error at exit_5.cmake:1 \(cmake_language\):
+  cmake_language EXIT can be used only in SCRIPT mode
diff --git a/Tests/RunCMake/cmake_language/exit_5.cmake b/Tests/RunCMake/cmake_language/exit_5.cmake
new file mode 100644
index 0000000..5e5c147
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_5.cmake
@@ -0,0 +1 @@
+cmake_language(EXIT 5)
diff --git a/Tests/RunCMake/cmake_language/exit_5_script-result.txt b/Tests/RunCMake/cmake_language/exit_5_script-result.txt
new file mode 100644
index 0000000..7ed6ff8
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_5_script-result.txt
@@ -0,0 +1 @@
+5
diff --git a/Tests/RunCMake/cmake_language/exit_5_script-stderr.txt b/Tests/RunCMake/cmake_language/exit_5_script-stderr.txt
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_5_script-stderr.txt
diff --git a/Tests/RunCMake/cmake_language/exit_5_script.cmake b/Tests/RunCMake/cmake_language/exit_5_script.cmake
new file mode 100644
index 0000000..5e5c147
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_5_script.cmake
@@ -0,0 +1 @@
+cmake_language(EXIT 5)
diff --git a/Tests/RunCMake/cmake_language/exit_5_script_with_command-result.txt b/Tests/RunCMake/cmake_language/exit_5_script_with_command-result.txt
new file mode 100644
index 0000000..7ed6ff8
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_5_script_with_command-result.txt
@@ -0,0 +1 @@
+5
diff --git a/Tests/RunCMake/cmake_language/exit_5_script_with_command-stderr.txt b/Tests/RunCMake/cmake_language/exit_5_script_with_command-stderr.txt
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_5_script_with_command-stderr.txt
diff --git a/Tests/RunCMake/cmake_language/exit_5_script_with_command.cmake b/Tests/RunCMake/cmake_language/exit_5_script_with_command.cmake
new file mode 100644
index 0000000..4400307
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_5_script_with_command.cmake
@@ -0,0 +1,3 @@
+cmake_language(EXIT 5)
+
+message(FATAL_ERROR "cmake_language(EXIT 5) doesn't work")
diff --git a/Tests/RunCMake/cmake_language/exit_7_script_in_include-result.txt b/Tests/RunCMake/cmake_language/exit_7_script_in_include-result.txt
new file mode 100644
index 0000000..7f8f011
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_7_script_in_include-result.txt
@@ -0,0 +1 @@
+7
diff --git a/Tests/RunCMake/cmake_language/exit_7_script_in_include-stderr.txt b/Tests/RunCMake/cmake_language/exit_7_script_in_include-stderr.txt
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_7_script_in_include-stderr.txt
diff --git a/Tests/RunCMake/cmake_language/exit_7_script_in_include.cmake b/Tests/RunCMake/cmake_language/exit_7_script_in_include.cmake
new file mode 100644
index 0000000..e65fa5c
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_7_script_in_include.cmake
@@ -0,0 +1,3 @@
+include(${CMAKE_CURRENT_LIST_DIR}/exit_7_script_included_with_exit.cmake)
+
+message(FATAL_ERROR "The cmake_language(EXIT 7) from include()-d script doesn't work")
diff --git a/Tests/RunCMake/cmake_language/exit_7_script_included_with_exit.cmake b/Tests/RunCMake/cmake_language/exit_7_script_included_with_exit.cmake
new file mode 100644
index 0000000..ee36ca0
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_7_script_included_with_exit.cmake
@@ -0,0 +1,3 @@
+cmake_language(EXIT 7)
+
+message(FATAL_ERROR "The include()-d script with EXIT 7 doesn't work")
diff --git a/Tests/RunCMake/cmake_language/exit_8_script_in_recursive_cmake_language-result.txt b/Tests/RunCMake/cmake_language/exit_8_script_in_recursive_cmake_language-result.txt
new file mode 100644
index 0000000..45a4fb7
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_8_script_in_recursive_cmake_language-result.txt
@@ -0,0 +1 @@
+8
diff --git a/Tests/RunCMake/cmake_language/exit_8_script_in_recursive_cmake_language-stderr.txt b/Tests/RunCMake/cmake_language/exit_8_script_in_recursive_cmake_language-stderr.txt
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_8_script_in_recursive_cmake_language-stderr.txt
@@ -0,0 +1 @@
+
diff --git a/Tests/RunCMake/cmake_language/exit_8_script_in_recursive_cmake_language.cmake b/Tests/RunCMake/cmake_language/exit_8_script_in_recursive_cmake_language.cmake
new file mode 100644
index 0000000..96daf86
--- /dev/null
+++ b/Tests/RunCMake/cmake_language/exit_8_script_in_recursive_cmake_language.cmake
@@ -0,0 +1,3 @@
+cmake_language(EVAL CODE "cmake_language(EXIT 8)")
+
+message(FATAL_ERROR "The cmake_language EVAL of EXIT 8 test doesn't work")