cmake_file_api: New project command

Projects can use the new command to request file API replies for the current
run. No query files are generated, the query is tracked internally. Replies are
created in the file system at generation time in the usual way.

Fixes: #24951

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.