Add cmake_language(GET_MESSAGE_LOG_LEVEL) sub command

The new sub-command writes a string representation of the
current log level to the output variable given to the
sub-command.

Given that the log-level might be set either via the --log-level
command line option or via the CMAKE_MESSAGE_LOG_LEVEL
cache / regular variables, the priority for each of the log level
sources is as follows, with the first one being the highest:
1) --log-level
2) CMAKE_MESSAGE_LOG_LEVEL regular variable
3) CMAKE_MESSAGE_LOG_LEVEL cache variable
4) default log level (STATUS)

Fixes: #23572

4 files changed, 42 insertions, 0 deletions

diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst
index cb8d60b..377e42d 100644
--- a/Help/command/cmake_language.rst
+++ b/Help/command/cmake_language.rst
@@ -14,6 +14,7 @@ Synopsis
   cmake_language(`EVAL`_ CODE <code>...)
   cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...])
   cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...)
+  cmake_language(`GET_MESSAGE_LOG_LEVEL`_ <out-var>)
 
 Introduction
 ^^^^^^^^^^^^
@@ -491,3 +492,28 @@ calling the provider command recursively for the same dependency.
     SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
     SUPPORTED_METHODS FIND_PACKAGE
   )
+
+Getting current message log level
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.25
+
+.. _GET_MESSAGE_LOG_LEVEL:
+.. _query_message_log_level:
+
+.. code-block:: cmake
+
+  cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)
+
+Writes the current :command:`message` logging level
+into the given ``<output_variable>``.
+
+See :command:`message` for the possible logging levels.
+
+The current message logging level can be set either using the ``--log-level``
+command line option of the :manual:`cmake(1)` program or using
+the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable.
+
+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.
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 38105dd..2726f13 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -249,6 +249,11 @@ Options
  For backward compatibility reasons, ``--loglevel`` is also accepted as a
  synonym for this option.
 
+ .. versionadded:: 3.25
+   See the :command:`cmake_language`
+   :ref:`cmake_language <query_message_log_level>` command for a way to query
+   the current message logging level.
+
 ``--log-context``
  Enable the :command:`message` command outputting context attached to each
  message.
diff --git a/Help/release/dev/cmake_language_GET_MESSAGE_LOG_LEVEL.rst b/Help/release/dev/cmake_language_GET_MESSAGE_LOG_LEVEL.rst
new file mode 100644
index 0000000..6e99a05
--- /dev/null
+++ b/Help/release/dev/cmake_language_GET_MESSAGE_LOG_LEVEL.rst
@@ -0,0 +1,6 @@
+cmake-language_GET_MESSAGE_LOG_LEVEL
+------------------------------------
+
+* The :command:`cmake_language` command gained a new
+  ``GET_MESSAGE_LOG_LEVEL`` sub-command.  It can be used to
+  query the current message logging level.
diff --git a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst
index 3b45d1d..54ea6a4 100644
--- a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst
+++ b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst
@@ -15,3 +15,8 @@ subsequent CMake runs will continue to use the chosen log level.
 
 Projects should not set this variable, it is intended for users so that
 they may control the log level according to their own needs.
+
+.. versionadded:: 3.25
+  See the :command:`cmake_language`
+  :ref:`cmake_language <query_message_log_level>` command for a way to query
+  the current message logging level.