Merge topic 'fileapi-configureLog'

d811d86fd7 FileAPI: Add "configureLog" object kind

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

3 files changed, 52 insertions, 0 deletions

diff --git a/Help/manual/cmake-configure-log.7.rst b/Help/manual/cmake-configure-log.7.rst
index 7f395f5113..f909717610 100644
--- a/Help/manual/cmake-configure-log.7.rst
+++ b/Help/manual/cmake-configure-log.7.rst
@@ -73,6 +73,16 @@ they do not understand:
 * If an existing build tree is re-configured with a different version of
   CMake, the log may contain different versions of the same event kind.
 
+* If :manual:`cmake-file-api(7)` queries request one or more
+  :ref:`configureLog <file-api configureLog>` object versions,
+  the log may contain multiple entries for the same event, each
+  with a different version of its event kind.
+
+IDEs should write a :manual:`cmake-file-api(7)` query requesting a
+specific :ref:`configureLog <file-api configureLog>` object version,
+before running CMake, and then read the configure log only as described
+by the file-api reply.
+
 Text Block Encoding
 -------------------
 
diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst
index cdc86ecc7d..7ff9728a5f 100644
--- a/Help/manual/cmake-file-api.7.rst
+++ b/Help/manual/cmake-file-api.7.rst
@@ -1298,6 +1298,45 @@ elsewhere in the containing object.  The backtrace graph object members are:
   directory then the path is specified relative to that directory.
   Otherwise the path is absolute.
 
+.. _`file-api configureLog`:
+
+Object Kind "configureLog"
+--------------------------
+
+The ``configureLog`` object kind describes the location and contents of
+a :manual:`cmake-configure-log(7)` file.
+
+There is only one ``configureLog`` object major version, version 1.
+
+"configureLog" version 1
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``configureLog`` object version 1 is a JSON object:
+
+.. code-block:: json
+
+  {
+    "kind": "configureLog",
+    "version": { "major": 1, "minor": 0 },
+    "path": "/path/to/top-level-build-dir/CMakeFiles/CMakeConfigureLog.yaml",
+    "eventKindNames": [ "try_compile-v1", "try_run-v1" ]
+  }
+
+The members specific to ``configureLog`` objects are:
+
+``path``
+  A string specifying the path to the configure log file.
+  Clients must read the log file from this path, which may be
+  different than the path documented by :manual:`cmake-configure-log(7)`.
+  The log file may not exist if no events are logged.
+
+``eventKindNames``
+  A JSON array whose entries are each a JSON string naming one
+  of the :manual:`cmake-configure-log(7)` versioned event kinds.
+  At most one version of each configure log event kind will be listed.
+  Although the configure log may contain other (versioned) event kinds,
+  clients must ignore those that are not listed in this field.
+
 Object Kind "cache"
 -------------------
 
diff --git a/Help/release/dev/configure-log.rst b/Help/release/dev/configure-log.rst
index 8518b21567..34b8fb3fc5 100644
--- a/Help/release/dev/configure-log.rst
+++ b/Help/release/dev/configure-log.rst
@@ -3,3 +3,6 @@ Configure Log
 
 * CMake now writes a YAML log of configure-time checks.
   See the :manual:`cmake-configure-log(7)` manual.
+
+* The :manual:`cmake-file-api(7)` gained a new "configureLog" object kind
+  that enables stable access to the :manual:`cmake-configure-log(7)`.