Merge topic 'file-api-query-command'

99b2ccf80d cmake_file_api: New project command

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

4 files changed, 91 insertions, 0 deletions

diff --git a/Help/command/cmake_file_api.rst b/Help/command/cmake_file_api.rst
new file mode 100644
index 0000000..e7ee7e7
--- /dev/null
+++ b/Help/command/cmake_file_api.rst
@@ -0,0 +1,78 @@
+cmake_file_api
+--------------
+
+.. versionadded:: 3.27
+
+Enables interacting with the :manual:`CMake file API <cmake-file-api(7)>`.
+
+.. signature::
+  cmake_file_api(QUERY ...)
+
+  The ``QUERY`` subcommand adds a file API query for the current CMake
+  invocation.
+
+  .. code-block:: cmake
+
+    cmake_file_api(
+      QUERY
+      API_VERSION <version>
+      [CODEMODEL <versions>...]
+      [CACHE <versions>...]
+      [CMAKEFILES <versions>...]
+      [TOOLCHAINS <versions>...]
+    )
+
+  The ``API_VERSION`` must always be given.  Currently, the only supported
+  value for ``<version>`` is 1.  See :ref:`file-api v1` for details of the
+  reply content and location.
+
+  Each of the optional keywords ``CODEMODEL``, ``CACHE``, ``CMAKEFILES`` and
+  ``TOOLCHAINS`` correspond to one of the object kinds that can be requested
+  by the project.  The ``configureLog`` object kind cannot be set with this
+  command, since it must be set before CMake starts reading the top level
+  ``CMakeLists.txt`` file.
+
+  For each of the optional keywords, the ``<versions>`` list must contain one
+  or more version values of the form ``major`` or ``major.minor``, where
+  ``major`` and ``minor`` are integers.  Projects should list the versions they
+  accept in their preferred order, as only the first supported value from the
+  list will be selected.  The command will ignore versions with a ``major``
+  version higher than any major version it supports for that object kind.
+  It will raise an error if it encounters an invalid version number, or if none
+  of the requested versions is supported.
+
+  For each type of object kind requested, a query equivalent to a shared,
+  stateless query will be added internally.  No query file will be created in
+  the file system.  The reply *will* be written to the file system at
+  generation time.
+
+  It is not an error to add a query for the same thing more than once, whether
+  from query files or from multiple calls to ``cmake_file_api(QUERY)``.
+  The final set of queries will be a merged combination of all queries
+  specified on disk and queries submitted by the project.
+
+Example
+^^^^^^^
+
+A project may want to use replies from the file API at build time to implement
+some form of verification task.  Instead of relying on something outside of
+CMake to create a query file, the project can use ``cmake_file_api(QUERY)``
+to request the required information for the current run.  It can then create
+a custom command to run at build time, knowing that the requested information
+should always be available.
+
+.. code-block:: cmake
+
+  cmake_file_api(
+    QUERY
+    API_VERSION 1
+    CODEMODEL 2.3
+    TOOLCHAINS 1
+  )
+
+  add_custom_target(verify_project
+    COMMAND ${CMAKE_COMMAND}
+      -D BUILD_DIR=${CMAKE_BINARY_DIR}
+      -D CONFIG=$<CONFIG>
+      -P ${CMAKE_CURRENT_SOURCE_DIR}/verify_project.cmake
+  )
diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst
index 0f35632..bd678b7 100644
--- a/Help/manual/cmake-commands.7.rst
+++ b/Help/manual/cmake-commands.7.rst
@@ -87,6 +87,7 @@ These commands are available only in CMake projects.
    /command/add_test
    /command/aux_source_directory
    /command/build_command
+   /command/cmake_file_api
    /command/create_test_sourcelist
    /command/define_property
    /command/enable_language
diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst
index 0bdb419..5f16a8b 100644
--- a/Help/manual/cmake-file-api.7.rst
+++ b/Help/manual/cmake-file-api.7.rst
@@ -23,6 +23,12 @@ of files within the API directory.  API file layout versioning is
 orthogonal to the versioning of `Object Kinds`_ used in replies.
 This version of CMake supports only one API version, `API v1`_.
 
+.. versionadded:: 3.27
+  Projects may also submit queries for the current run using the
+  :command:`cmake_file_api` command.
+
+.. _`file-api v1`:
+
 API v1
 ======
 
diff --git a/Help/release/dev/file-api-query-command.rst b/Help/release/dev/file-api-query-command.rst
new file mode 100644
index 0000000..66ae7d9
--- /dev/null
+++ b/Help/release/dev/file-api-query-command.rst
@@ -0,0 +1,6 @@
+file-api-query-command
+----------------------
+
+* The :command:`cmake_file_api` command was added, enabling projects to
+  add :manual:`CMake file API <cmake-file-api(7)>` queries for the current
+  CMake run.