Merge topic 'build-databases'

e77655555c cmExperimental: gate build database support behind a flag
23cbeb5035 ci: enable `build_database` CXXModules tests
6863c1d823 Tests/CXXModules: add tests for module commands
123107c1a4 Tests/CXXModules: add support for running targets under a given config
438038b5e1 Tests/CXXModules: support building specific targets of example trees
84bc710d84 cmGlobalGenerator: generate build database files for targets
670f753f24 cmDyndepCollation: write build database metadata
dcf9a66ffe cxxmodules: plumb control data for exporting build databases
...

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

Help/dev/experimental.rst

@@ -80,3 +80,24 @@ When activated, this experimental feature provides the following:
 
 .. _CPS: https://cps-org.github.io/cps/
 .. |CPS| replace:: Common Package Specification
+
+Build database support
+======================
+
+In order to activate support for exporting build databases, set
+
+* variable ``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` to
+* value ``4bd552e2-b7fb-429a-ab23-c83ef53f3f13``.
+
+This UUID may change in future versions of CMake.  Be sure to use the value
+documented here by the source tree of the version of CMake with which you are
+experimenting.
+
+When activated, this experimental feature provides the following:
+
+* The :prop_tgt:`EXPORT_BUILD_DATABASE` target property and its initializing
+  variable :variable:`CMAKE_EXPORT_BUILD_DATABASE` and environment variable
+  :envvar:`CMAKE_EXPORT_BUILD_DATABASE`.
+
+* Targets with the property set to a true value will have their C++ build
+  information exported to the build database.

Help/envvar/CMAKE_EXPORT_BUILD_DATABASE.rst

@@ -0,0 +1,17 @@
+CMAKE_EXPORT_BUILD_DATABASE
+---------------------------
+
+.. versionadded:: 3.31
+
+.. include:: ENV_VAR.txt
+
+The default value for :variable:`CMAKE_EXPORT_BUILD_DATABASE` when there is no
+explicit configuration given on the first run while creating a new build tree.
+On later runs in an existing build tree the value persists in the cache as
+:variable:`CMAKE_EXPORT_BUILD_DATABASE`.
+
+.. note ::
+
+   This variable is meaningful only when experimental support for build
+   databases has been enabled by the
+   ``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` gate.

Help/guide/user-interaction/index.rst

@@ -300,6 +300,8 @@ the table below:
                                             commands used without a type
  :variable:`CMAKE_EXPORT_COMPILE_COMMANDS`  Generate a ``compile_commands.json``
                                             file for use with clang-based tools
+ :variable:`CMAKE_EXPORT_BUILD_DATABASE`    Generate a ``build_database.json``
+                                            file for use with clang-based tools
 ========================================== ============================================================
 
 Other project-specific variables may be available

Help/manual/cmake-env-variables.7.rst

@@ -47,6 +47,7 @@ Environment Variables that Control the Build
    /envvar/CMAKE_CONFIG_TYPE
    /envvar/CMAKE_CONFIGURATION_TYPES
    /envvar/CMAKE_CROSSCOMPILING_EMULATOR
+   /envvar/CMAKE_EXPORT_BUILD_DATABASE
    /envvar/CMAKE_EXPORT_COMPILE_COMMANDS
    /envvar/CMAKE_GENERATOR
    /envvar/CMAKE_GENERATOR_INSTANCE

Help/manual/cmake-properties.7.rst

@@ -217,6 +217,7 @@ Properties on Targets
    /prop_tgt/EXCLUDE_FROM_ALL
    /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD
    /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG
+   /prop_tgt/EXPORT_BUILD_DATABASE
    /prop_tgt/EXPORT_COMPILE_COMMANDS
    /prop_tgt/EXPORT_FIND_PACKAGE_NAME
    /prop_tgt/EXPORT_NAME

Help/manual/cmake-variables.7.rst

@@ -195,6 +195,7 @@ Variables that Change Behavior
    /variable/CMAKE_ERROR_DEPRECATED
    /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
    /variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO
+   /variable/CMAKE_EXPORT_BUILD_DATABASE
    /variable/CMAKE_EXPORT_COMPILE_COMMANDS
    /variable/CMAKE_EXPORT_PACKAGE_REGISTRY
    /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY

Help/prop_tgt/EXPORT_BUILD_DATABASE.rst

@@ -0,0 +1,15 @@
+EXPORT_BUILD_DATABASE
+---------------------
+
+.. versionadded:: 3.31
+
+Enable/Disable output of a build database for a target.
+
+This property is initialized by the value of the variable
+:variable:`CMAKE_EXPORT_BUILD_DATABASE` if it is set when a target is created.
+
+.. note ::
+
+   This property is meaningful only when experimental support for build
+   databases has been enabled by the
+   ``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` gate.

Help/release/dev/module-cdb.rst

@@ -0,0 +1,8 @@
+module-cdb
+==========
+
+* Targets with C++ modules may now export their module compile commands using
+  the :prop_tgt:`EXPORT_BUILD_DATABASE` target property. This is initialized
+  with the :variable:`CMAKE_EXPORT_BUILD_DATABASE` variable which is itself
+  initialized using the :envvar:`CMAKE_EXPORT_BUILD_DATABASE` environment
+  variable. Only supported with the :ref:`Ninja Generators`.

Help/variable/CMAKE_EXPORT_BUILD_DATABASE.rst

@@ -0,0 +1,86 @@
+CMAKE_EXPORT_BUILD_DATABASE
+---------------------------
+
+.. versionadded:: 3.31
+
+.. note ::
+
+   This variable is meaningful only when experimental support for build
+   databases has been enabled by the
+   ``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` gate.
+
+Enable/Disable output of module compile commands during the build.
+
+If enabled, generates a ``build_database.json`` file containing the
+information necessary to compile a target's C++ module sources with any
+tooling. The format of the JSON file looks like:
+
+.. code-block:: javascript
+
+  {
+    "version": 1,
+    "revision": 0,
+    "sets": [
+      {
+        "family-name" : "export_build_database",
+        "name" : "export_build_database@Debug",
+        "translation-units" : [
+          {
+            "arguments": [
+              "/path/to/compiler",
+              "...",
+            ],
+            "baseline-arguments" :
+            [
+              "...",
+            ],
+            "local-arguments" :
+            [
+              "...",
+            ],
+            "object": "CMakeFiles/target.dir/source.cxx.o",
+            "private": true,
+            "provides": {
+              "importable": "path/to/bmi"
+            },
+            "requires" : [],
+            "source": "path/to/source.cxx",
+            "work-directory": "/path/to/working/directory"
+          }
+        ],
+        "visible-sets" : []
+      }
+    ]
+  }
+
+This is initialized by the :envvar:`CMAKE_EXPORT_BUILD_DATABASE` environment
+variable, and initializes the :prop_tgt:`EXPORT_BUILD_DATABASE` target
+property for all targets.
+
+.. note::
+  This option is implemented only by the :ref:`Ninja Generators`.  It is
+  ignored on other generators.
+
+When supported and enabled, numerous targets are created in order to make it
+possible to build a file containing just the commands that are needed for the
+tool in question.
+
+``cmake_build_database-<CONFIG>``
+  Writes ``build_database_<CONFIG>.json``. Writes a build database for the
+  entire build for the given configuration and all languages. Not available if
+  the configuration name is the empty string.
+
+``cmake_build_database-<LANG>-<CONFIG>``
+  Writes ``build_database_<LANG>_<CONFIG>.json``. Writes build database for
+  the entire build for the given configuration and language. Not available if
+  the configuration name is the empty string.
+
+``cmake_build_database-<LANG>``
+  Writes ``build_database_<LANG>.json``. Writes build database for the entire
+  build for the given language and all configurations. In a multi-config
+  generator, other build configuration database may be assumed to exist.
+
+``cmake_build_database``
+  Writes to ``build_database.json``. Writes build database for all languages
+  and configurations. In a multi-config generator, other build configuration
+  database may be assumed to exist.