ConfigureLog: Add documentation

Issue: #23200

Help/index.rst

@@ -57,6 +57,7 @@ Reference Manuals
    /manual/cmake-buildsystem.7
    /manual/cmake-commands.7
    /manual/cmake-compile-features.7
+   /manual/cmake-configure-log.7
    /manual/cmake-developer.7
    /manual/cmake-env-variables.7
    /manual/cmake-file-api.7

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

+.. cmake-manual-description: CMake Configure Log
+
+cmake-configure-log(7)
+**********************
+
+.. only:: html
+
+   .. contents::
+
+Introduction
+============
+
+CMake provides a running log, known as the configure log,
+of certain key events which occur during each execution.
+The log file is located at
+``${CMAKE_BINARY_DIR}/CMakeFiles/CMakeConfigureLog.yaml``.
+
+Log Structure
+=============
+
+The log uses YAML for structure.
+Each run of CMake appends a new YAML document to the log.
+Each such document is a single YAML object.
+
+The root object has the following members:
+
+``version``
+  An object which describes the schema version of the log object.
+  It has the integer members ``major`` and ``minor``.
+
+``events``
+  A list of events which occurred during the CMake run.
+
+Event Structure
+---------------
+
+Each event is a YAML object. Most of the object's members will vary
+depending on the event kind. The following are common to most or all events:
+
+``kind``
+  A string which identifies the event kind.
+  Always present.
+
+``backtrace``
+  A list of strings which identifies the source of the event.
+  The list gives the call stack of source locations which produced the event,
+  formatted as in CMake's message reporting (``<file>:<line> (<function>)``).
+  Present for most event kinds.
+
+Members for additional event types are described below.
+
+``try_compile`` Event
+---------------------
+
+Corresponds to a :command:`try_compile` command.
+This event has the following additional members:
+
+``directories``
+
+  An object describing the directories associated with the compilation attempt,
+  which has the following members:
+
+  ``source``
+    String specifying the source directory
+    of the :command:`try_compile` project.
+
+  ``binary``
+    String specifying the binary directory
+    of the :command:`try_compile` project.
+    For non-project invocations,
+    this is often the same as the source directory.
+
+``buildResult``
+  An object describing the result of compiling the test code,
+  which has the following members:
+
+  ``variable``
+    Name of the CMake variable (string) which received the result
+    of trying to compile the test project.
+
+  ``cached``
+    Boolean indicating whether the above result ``variable``
+    is stored in the CMake cache.
+
+  ``stdout``
+    Output (string) from compiling the test project, represented
+    using our `Text Block Encoding`_.
+    Despite the name, this contains both stdout and stderr.
+
+  ``exitCode``
+    Exit code (integer) from compiling the test project.
+
+``try_run`` Event
+-----------------
+
+Corresponds to a :command:`try_run` command.
+This event has the same members as ``try_compile``, plus:
+
+``runResult``
+  An object describing the result of compiling the test code.
+  This member is only present if compilation succeeded.
+  It has the following members:
+
+  ``variable``
+    Name of the CMake variable (string) which received the result
+    of trying to run the test executable.
+
+  ``cached``
+    Boolean indicating whether the above result ``variable``
+    is stored in the CMake cache.
+
+  ``stdout``
+    Output (string) from running the test executable, represented
+    using our `Text Block Encoding`_.
+
+    If ``RUN_OUTPUT_VARIABLE`` was used, stdout and stderr are captured
+    together, so this will contain both.  Otherwise, this will contain
+    only the stdout output.
+
+  ``stderr``
+    Output (string) from running the test executable, represented
+    using our `Text Block Encoding`_.
+
+    If ``RUN_OUTPUT_VARIABLE`` was used, stdout and stderr are captured
+    together in the ``stdout`` member, and this will be ``null``.
+    Otherwise, this will contain only the stderr output.
+
+  ``exitCode``
+    Exit code from running the test executable.
+    Usually an integer, but may be a string
+    in some instances when cross-compiling.
+
+If the test test executable could not be executed
+(e.g. because it could not be compiled),
+``stdout``, ``stderr`` and ``exitCode`` will all be ``null``.
+
+Text Block Encoding
+-------------------
+
+In order to make the log human-readable, text blocks are always represented
+using YAML literal style (``|``).  Since YAML literal text blocks do not
+support escaping, backslashes and non-printable characters are encoded at
+the application layer:
+
+* ``\\`` encodes a backslash.
+* ``\xXX`` encodes a byte using two hexadecimal digits, ``XX``.

Help/release/dev/configure-log.rst

+Configure Log
+-------------
+
+* CMake now writes a YAML log of configure-time checks.
+  See the :manual:`cmake-configure-log(7)` manual.