Merge topic 'configure-log'

48292c8624 try_compile: Record stack of in-progess checks in configure log
d4bf7d80c6 try_compile: Add a NO_LOG option to skip recording in the configure log
9d9e8450a8 try_compile: Add optional LOG_DESCRIPTION to record in configure log
65ed5c2ca8 try_compile: Report underlying error when COPY_FILE fails
0418efb7ad Tests: Add explicit ConfigureLog case to RunCMake.try_compile
189557bd74 cmake: Make entire in-progress check stack available internally
96ce3581ab Help: Clarify backtrace order in cmake-configure-log(7)

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

1 files changed, 22 insertions, 2 deletions

diff --git a/Help/manual/cmake-configure-log.7.rst b/Help/manual/cmake-configure-log.7.rst
index f909717610..262012442b 100644
--- a/Help/manual/cmake-configure-log.7.rst
+++ b/Help/manual/cmake-configure-log.7.rst
@@ -106,6 +106,8 @@ Every event kind is represented by a YAML mapping of the form:
   kind: "<kind>-v<major>"
   backtrace:
     - "<file>:<line> (<function>)"
+  checks:
+    - "Checking for something"
   #...event-specific keys...
 
 The keys common to all events are:
@@ -115,8 +117,16 @@ The keys common to all events are:
 
 ``backtrace``
   A YAML block sequence reporting the call stack of CMake source
-  locations at which the event occurred.  Each node is a string
-  specifying one location formatted as ``<file>:<line> (<function>)``.
+  locations at which the event occurred, from most-recent to
+  least-recent.  Each node is a string specifying one location
+  formatted as ``<file>:<line> (<function>)``.
+
+``checks``
+  An optional key that is present when the event occurred with
+  at least one pending :command:`message(CHECK_START)`.  Its value
+  is a YAML block sequence reporting the stack of pending checks,
+  from most-recent to least-recent.  Each node is a string containing
+  a pending check message.
 
 Additional mapping keys are specific to each (versioned) event kind,
 described below.
@@ -140,6 +150,9 @@ A ``try_compile-v1`` event is a YAML mapping:
   kind: "try_compile-v1"
   backtrace:
     - "CMakeLists.txt:123 (try_compile)"
+  checks:
+    - "Checking for something"
+  description: "Explicit LOG_DESCRIPTION"
   directories:
     source: "/path/to/.../TryCompile-01234"
     binary: "/path/to/.../TryCompile-01234"
@@ -152,6 +165,10 @@ A ``try_compile-v1`` event is a YAML mapping:
 
 The keys specific to ``try_compile-v1`` mappings are:
 
+``description``
+  An optional key that is present when the ``LOG_DESCRIPTION <text>`` option
+  was used.  Its value is a string containing the description ``<text>``.
+
 ``directories``
   A mapping describing the directories associated with the
   compilation attempt.  It has the following keys:
@@ -206,6 +223,9 @@ A ``try_run-v1`` event is a YAML mapping:
   kind: "try_run-v1"
   backtrace:
     - "CMakeLists.txt:456 (try_run)"
+  checks:
+    - "Checking for something"
+  description: "Explicit LOG_DESCRIPTION"
   directories:
     source: "/path/to/.../TryCompile-56789"
     binary: "/path/to/.../TryCompile-56789"