From a78cba51978fbc805993604767c1902a249482ff Mon Sep 17 00:00:00 2001
From: Brad King <brad.king@kitware.com>
Date: Mon, 16 Jan 2023 14:32:36 -0500
Subject: 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
---
 Help/command/message.rst                           | 50 ++++++++++++++++++++++
 Help/manual/cmake-configure-log.7.rst              | 32 ++++++++++++++
 Help/release/dev/configure-log.rst                 |  3 ++
 Source/cmFileAPIConfigureLog.cxx                   |  1 +
 Source/cmMessageCommand.cxx                        | 28 ++++++++++++
 Tests/RunCMake/FileAPI/configureLog-v1-check.py    |  2 +-
 Tests/RunCMake/message/ConfigureLog-config.txt     | 30 +++++++++++++
 Tests/RunCMake/message/ConfigureLog-stdout.txt     |  4 ++
 Tests/RunCMake/message/ConfigureLog.cmake          |  7 +++
 .../RunCMake/message/ConfigureLogScript-config.txt |  1 +
 .../RunCMake/message/ConfigureLogScript-stdout.txt |  4 ++
 Tests/RunCMake/message/ConfigureLogScript.cmake    |  1 +
 Tests/RunCMake/message/RunCMakeTest.cmake          |  2 +
 13 files changed, 164 insertions(+), 1 deletion(-)
 create mode 100644 Tests/RunCMake/message/ConfigureLog-config.txt
 create mode 100644 Tests/RunCMake/message/ConfigureLog-stdout.txt
 create mode 100644 Tests/RunCMake/message/ConfigureLog.cmake
 create mode 100644 Tests/RunCMake/message/ConfigureLogScript-config.txt
 create mode 100644 Tests/RunCMake/message/ConfigureLogScript-stdout.txt
 create mode 100644 Tests/RunCMake/message/ConfigureLogScript.cmake

diff --git a/Help/command/message.rst b/Help/command/message.rst
index 9ac4277..e8a4ea0 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 768ef7e..a9c185d 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 f802a8c..588a54c 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)`.
diff --git a/Source/cmFileAPIConfigureLog.cxx b/Source/cmFileAPIConfigureLog.cxx
index 50189cb..ad0997c 100644
--- a/Source/cmFileAPIConfigureLog.cxx
+++ b/Source/cmFileAPIConfigureLog.cxx
@@ -52,6 +52,7 @@ Json::Value ConfigureLog::DumpEventKindNames()
   // major version of the configureLog object kind is needed.
   Json::Value eventKindNames = Json::arrayValue;
   if (this->Version == 1) {
+    eventKindNames.append("message-v1");     // WriteMessageEvent
     eventKindNames.append("try_compile-v1"); // WriteTryCompileEvent
     eventKindNames.append("try_run-v1");     // WriteTryRunEvent
   }
diff --git a/Source/cmMessageCommand.cxx b/Source/cmMessageCommand.cxx
index fa29ec9..205f01f 100644
--- a/Source/cmMessageCommand.cxx
+++ b/Source/cmMessageCommand.cxx
@@ -8,6 +8,7 @@
 #include <cm/string_view>
 #include <cmext/string_view>
 
+#include "cmConfigureLog.h"
 #include "cmExecutionStatus.h"
 #include "cmMakefile.h"
 #include "cmMessageType.h"
@@ -64,6 +65,25 @@ void ReportCheckResult(cm::string_view what, std::string result,
   }
 }
 
+namespace {
+#ifndef CMAKE_BOOTSTRAP
+void WriteMessageEvent(cmConfigureLog& log, cmMakefile const& mf,
+                       std::string const& message)
+{
+  // Keep in sync with cmFileAPIConfigureLog's DumpEventKindNames.
+  static const std::vector<unsigned long> LogVersionsWithMessageV1{ 1 };
+
+  if (log.IsAnyLogVersionEnabled(LogVersionsWithMessageV1)) {
+    log.BeginEvent("message-v1");
+    log.WriteBacktrace(mf);
+    log.WriteChecks(mf);
+    log.WriteLiteralTextBlock("message"_s, message);
+    log.EndEvent();
+  }
+}
+#endif
+}
+
 } // anonymous namespace
 
 // cmLibraryCommand
@@ -121,6 +141,14 @@ bool cmMessageCommand(std::vector<std::string> const& args,
     level = Message::LogLevel::LOG_STATUS;
     checkingType = CheckingType::CHECK_FAIL;
     ++i;
+  } else if (*i == "CONFIGURE_LOG") {
+#ifndef CMAKE_BOOTSTRAP
+    if (cmConfigureLog* log = mf.GetCMakeInstance()->GetConfigureLog()) {
+      ++i;
+      WriteMessageEvent(*log, mf, cmJoin(cmMakeRange(i, args.cend()), ""_s));
+    }
+#endif
+    return true;
   } else if (*i == "STATUS") {
     level = Message::LogLevel::LOG_STATUS;
     ++i;
diff --git a/Tests/RunCMake/FileAPI/configureLog-v1-check.py b/Tests/RunCMake/FileAPI/configureLog-v1-check.py
index ea5beb4..05c7893 100644
--- a/Tests/RunCMake/FileAPI/configureLog-v1-check.py
+++ b/Tests/RunCMake/FileAPI/configureLog-v1-check.py
@@ -14,7 +14,7 @@ def check_object_configureLog(o):
     assert os.path.exists(path)
     eventKindNames = o["eventKindNames"]
     assert is_list(eventKindNames)
-    assert sorted(eventKindNames) == ["try_compile-v1", "try_run-v1"]
+    assert sorted(eventKindNames) == ["message-v1", "try_compile-v1", "try_run-v1"]
 
 assert is_dict(index)
 assert sorted(index.keys()) == ["cmake", "objects", "reply"]
diff --git a/Tests/RunCMake/message/ConfigureLog-config.txt b/Tests/RunCMake/message/ConfigureLog-config.txt
new file mode 100644
index 0000000..49c12de
--- /dev/null
+++ b/Tests/RunCMake/message/ConfigureLog-config.txt
@@ -0,0 +1,30 @@
+^
+---
+events:
+  -
+    kind: "message-v1"
+    backtrace:
+      - "ConfigureLog.cmake:[0-9]+ \(message\)"
+      - "CMakeLists.txt:[0-9]+ \(include\)"
+    message: |
+      Message 0
+  -
+    kind: "message-v1"
+    backtrace:
+      - "ConfigureLog.cmake:[0-9]+ \(message\)"
+      - "CMakeLists.txt:[0-9]+ \(include\)"
+    checks:
+      - "Check 1"
+    message: |
+      Message 1
+  -
+    kind: "message-v1"
+    backtrace:
+      - "ConfigureLog.cmake:[0-9]+ \(message\)"
+      - "CMakeLists.txt:[0-9]+ \(include\)"
+    checks:
+      - "Check 2"
+      - "Check 1"
+    message: |
+      Message 2
+\.\.\.$
diff --git a/Tests/RunCMake/message/ConfigureLog-stdout.txt b/Tests/RunCMake/message/ConfigureLog-stdout.txt
new file mode 100644
index 0000000..ba32642
--- /dev/null
+++ b/Tests/RunCMake/message/ConfigureLog-stdout.txt
@@ -0,0 +1,4 @@
+-- Check 1
+-- Check 2
+-- Check 2 - passed
+-- Check 1 - passed
diff --git a/Tests/RunCMake/message/ConfigureLog.cmake b/Tests/RunCMake/message/ConfigureLog.cmake
new file mode 100644
index 0000000..6f2c1b0
--- /dev/null
+++ b/Tests/RunCMake/message/ConfigureLog.cmake
@@ -0,0 +1,7 @@
+message(CONFIGURE_LOG "Message 0")
+message(CHECK_START "Check 1")
+message(CONFIGURE_LOG "Message 1")
+message(CHECK_START "Check 2")
+message(CONFIGURE_LOG "Message 2")
+message(CHECK_PASS "passed")
+message(CHECK_PASS "passed")
diff --git a/Tests/RunCMake/message/ConfigureLogScript-config.txt b/Tests/RunCMake/message/ConfigureLogScript-config.txt
new file mode 100644
index 0000000..10f3293
--- /dev/null
+++ b/Tests/RunCMake/message/ConfigureLogScript-config.txt
@@ -0,0 +1 @@
+^$
diff --git a/Tests/RunCMake/message/ConfigureLogScript-stdout.txt b/Tests/RunCMake/message/ConfigureLogScript-stdout.txt
new file mode 100644
index 0000000..ba32642
--- /dev/null
+++ b/Tests/RunCMake/message/ConfigureLogScript-stdout.txt
@@ -0,0 +1,4 @@
+-- Check 1
+-- Check 2
+-- Check 2 - passed
+-- Check 1 - passed
diff --git a/Tests/RunCMake/message/ConfigureLogScript.cmake b/Tests/RunCMake/message/ConfigureLogScript.cmake
new file mode 100644
index 0000000..e1cd21b
--- /dev/null
+++ b/Tests/RunCMake/message/ConfigureLogScript.cmake
@@ -0,0 +1 @@
+include("${CMAKE_CURRENT_LIST_DIR}/ConfigureLog.cmake")
diff --git a/Tests/RunCMake/message/RunCMakeTest.cmake b/Tests/RunCMake/message/RunCMakeTest.cmake
index 1233838..c54e8f2 100644
--- a/Tests/RunCMake/message/RunCMakeTest.cmake
+++ b/Tests/RunCMake/message/RunCMakeTest.cmake
@@ -1,7 +1,9 @@
 include(RunCMake)
 
+run_cmake_script(ConfigureLogScript)
 run_cmake_script(newline)
 
+run_cmake(ConfigureLog)
 run_cmake(defaultmessage)
 run_cmake(nomessage)
 run_cmake(message-internal-warning)
-- 
cgit v0.12