message: Add CONFIGURE_LOG mode to record a message in the configure log

Provide a replacement for `file(APPEND .../CMake{Output,Error}.log)`
that records messages in the configure log.

Issue: #23200

3 files changed, 85 insertions, 0 deletions

diff --git a/Help/command/message.rst b/Help/command/message.rst
index 9ac4277392..e8a4ea000c 100644
--- a/Help/command/message.rst
+++ b/Help/command/message.rst
@@ -14,6 +14,8 @@ Synopsis
   `Reporting checks`_
     message(<checkState> "message text" ...)
 
+  `Configure Log`_
+    message(CONFIGURE_LOG <text>...)
 
 General messages
 ^^^^^^^^^^^^^^^^
@@ -194,6 +196,54 @@ Output from the above would appear something like the following::
   --   Finding partB - not found
   -- Finding my things - missing components: B
 
+Configure Log
+^^^^^^^^^^^^^
+
+.. versionadded:: 3.26
+
+.. code-block:: cmake
+
+  message(CONFIGURE_LOG <text>...)
+
+Record a :ref:`configure-log message event <message configure-log event>`
+with the specified ``<text>``.  By convention, if the text contains more
+than one line, the first line should be a summary of the event.
+
+This mode is intended to record the details of a system inspection check
+or other one-time operation guarded by a cache entry, but that is not
+performed using :command:`try_compile` or :command:`try_run`, which
+automatically log their details.  Projects should avoid calling it every
+time CMake runs.  For example:
+
+.. code-block:: cmake
+
+  if (NOT DEFINED MY_CHECK_RESULT)
+    # Print check summary in configure output.
+    message(CHECK_START "My Check")
+
+    # ... perform system inspection, e.g., with execute_process ...
+
+    # Cache the result so we do not run the check again.
+    set(MY_CHECK_RESULT "${MY_CHECK_RESULT}" CACHE INTERNAL "My Check")
+
+    # Record the check details in the cmake-configure-log.
+    message(CONFIGURE_LOG
+      "My Check Result: ${MY_CHECK_RESULT}\n"
+      "${details}"
+    )
+
+    # Print check result in configure output.
+    if(MY_CHECK_RESULT)
+      message(CHECK_PASS "passed")
+    else()
+      message(CHECK_FAIL "failed")
+    endif()
+  endif()
+
+If no project is currently being configured, such as in
+:ref:`cmake -P <Script Processing Mode>` script mode,
+this command does nothing.
+
 See Also
 ^^^^^^^^
 
diff --git a/Help/manual/cmake-configure-log.7.rst b/Help/manual/cmake-configure-log.7.rst
index 768ef7ed1f..a9c185dd3b 100644
--- a/Help/manual/cmake-configure-log.7.rst
+++ b/Help/manual/cmake-configure-log.7.rst
@@ -131,6 +131,38 @@ The keys common to all events are:
 Additional mapping keys are specific to each (versioned) event kind,
 described below.
 
+.. _`message configure-log event`:
+
+Event Kind ``message``
+----------------------
+
+The :command:`message(CONFIGURE_LOG)` command logs ``message`` events.
+
+There is only one ``message`` event major version, version 1.
+
+.. _`message-v1 event`:
+
+``message-v1`` Event
+^^^^^^^^^^^^^^^^^^^^
+
+A ``message-v1`` event is a YAML mapping:
+
+.. code-block:: yaml
+
+  kind: "message-v1"
+  backtrace:
+    - "CMakeLists.txt:123 (message)"
+  checks:
+    - "Checking for something"
+  message: |
+    # ...
+
+The keys specific to ``message-v1`` mappings are:
+
+``message``
+  A YAML literal block scalar containing the message text,
+  represented using our `Text Block Encoding`_.
+
 .. _`try_compile configure-log event`:
 
 Event Kind ``try_compile``
diff --git a/Help/release/dev/configure-log.rst b/Help/release/dev/configure-log.rst
index f802a8c132..588a54cb28 100644
--- a/Help/release/dev/configure-log.rst
+++ b/Help/release/dev/configure-log.rst
@@ -7,6 +7,9 @@ Configure Log
 * The :manual:`cmake-file-api(7)` gained a new "configureLog" object kind
   that enables stable access to the :manual:`cmake-configure-log(7)`.
 
+* The :command:`message` command gained a ``CONFIGURE_LOG`` mode to
+  record an entry in the :manual:`cmake-configure-log(7)`.
+
 * The :command:`try_compile` and :command:`try_run` commands gained
   a ``LOG_DESCRIPTION`` option specifying text to be recorded in the
   :manual:`cmake-configure-log(7)`.