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

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``).

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.

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();

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(

Tests/RunCMake/cmake_language/exit_0-result.txt

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

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

Tests/RunCMake/cmake_language/exit_0.cmake

@@ -0,0 +1 @@
+cmake_language(EXIT 0)

Tests/RunCMake/cmake_language/exit_0_script-result.txt

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

Tests/RunCMake/cmake_language/exit_0_script.cmake

@@ -0,0 +1 @@
+cmake_language(EXIT 0)

Tests/RunCMake/cmake_language/exit_0_script_with_command-result.txt

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

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")

Tests/RunCMake/cmake_language/exit_5-result.txt

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

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

Tests/RunCMake/cmake_language/exit_5.cmake

@@ -0,0 +1 @@
+cmake_language(EXIT 5)

Tests/RunCMake/cmake_language/exit_5_script-result.txt

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

Tests/RunCMake/cmake_language/exit_5_script.cmake

@@ -0,0 +1 @@
+cmake_language(EXIT 5)

Tests/RunCMake/cmake_language/exit_5_script_with_command-result.txt

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

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")

Tests/RunCMake/cmake_language/exit_7_script_in_include-result.txt

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

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")

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")

Tests/RunCMake/cmake_language/exit_8_script_in_recursive_cmake_language-result.txt

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

Tests/RunCMake/cmake_language/exit_8_script_in_recursive_cmake_language-stderr.txt

@@ -0,0 +1 @@
+

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")