Merge topic 'configure-log'

a78cba5197 message: Add CONFIGURE_LOG mode to record a message in the configure log
645671d36f Help: Document configure log behavior in try_compile and try_run

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !8080

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
 ^^^^^^^^
 

Help/command/try_compile.rst

@@ -42,6 +42,11 @@ below for the meaning of other options.
   Previously this was only done by the
   :ref:`source file <Try Compiling Source Files>` signature.
 
+.. versionadded:: 3.26
+  This command records a
+  :ref:`configure-log try_compile event <try_compile configure-log event>`
+  if the ``NO_LOG`` option is not specified.
+
 This command also supports an alternate signature
 which was present in older versions of CMake:
 

Help/command/try_run.rst

@@ -50,6 +50,11 @@ the test project is constructed to build the source file.
 One or more source files must be provided. Additionally, one of ``SOURCES``
 and/or ``SOURCE_FROM_*`` must precede other keywords.
 
+.. versionadded:: 3.26
+  This command records a
+  :ref:`configure-log try_run event <try_run configure-log event>`
+  if the ``NO_LOG`` option is not specified.
+
 This command also supports an alternate signature
 which was present in older versions of CMake:
 

Help/manual/cmake-configure-log.7.rst

@@ -131,6 +131,40 @@ 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``
 --------------------------
 
@@ -204,6 +238,8 @@ The keys specific to ``try_compile-v1`` mappings are:
     An integer specifying the build tool exit code from trying
     to build the test project.
 
+.. _`try_run configure-log event`:
+
 Event Kind ``try_run``
 ----------------------
 

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