cxxmodules: plumb control data for exporting build databases

This includes the target property, its initializing variable, its
initializing environment variable, and updating related docs to mention
the new bits.

Help/envvar/CMAKE_EXPORT_BUILD_DATABASE.rst

@@ -0,0 +1,11 @@
+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`.

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,9 @@
+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.

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,80 @@
+CMAKE_EXPORT_BUILD_DATABASE
+---------------------------
+
+.. versionadded:: 3.31
+
+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.

Modules/CMakeGenericSystem.cmake

@@ -78,6 +78,13 @@ if(NOT DEFINED CMAKE_EXPORT_COMPILE_COMMANDS AND CMAKE_GENERATOR MATCHES "Ninja|
   mark_as_advanced(CMAKE_EXPORT_COMPILE_COMMANDS)
 endif()
 
+if(NOT DEFINED CMAKE_EXPORT_BUILD_DATABASE AND CMAKE_GENERATOR MATCHES "Ninja")
+  set(CMAKE_EXPORT_BUILD_DATABASE "$ENV{CMAKE_EXPORT_BUILD_DATABASE}"
+    CACHE BOOL "Enable/Disable output of build database during the build."
+    )
+  mark_as_advanced(CMAKE_EXPORT_BUILD_DATABASE)
+endif()
+
 # GetDefaultWindowsPrefixBase
 #
 # Compute the base directory for CMAKE_INSTALL_PREFIX based on:

Source/cmTarget.cxx

@@ -598,6 +598,7 @@ TargetProperty const StaticTargetProperties[] = {
 
   // Metadata
   { "CROSSCOMPILING_EMULATOR"_s, IC::ExecutableTarget },
+  { "EXPORT_BUILD_DATABASE"_s, IC::CanCompileSources },
   { "EXPORT_COMPILE_COMMANDS"_s, IC::CanCompileSources },
   { "FOLDER"_s },
   { "TEST_LAUNCHER"_s, IC::ExecutableTarget },
@@ -1895,6 +1896,10 @@ void cmTarget::CopyImportedCxxModulesProperties(cmTarget const* tgt)
     // Metadata
     "EchoString",
     "EXPORT_COMPILE_COMMANDS",
+    // Do *not* copy this property; it should be re-initialized at synthesis
+    // time from the `CMAKE_EXPORT_BUILD_DATABASE` variable as `IMPORTED`
+    // targets ignore the property initialization.
+    // "EXPORT_BUILD_DATABASE",
     "FOLDER",
     "LABELS",
     "PROJECT_LABEL",

Tests/RunCMake/property_init/CompileSources.cmake

@@ -177,6 +177,7 @@ set(properties
 
   # Metadata
   "EXPORT_COMPILE_COMMANDS"                 "OFF"               "<SAME>"
+  "EXPORT_BUILD_DATABASE"                   "OFF"               "<SAME>"
   )
 
 if (CMAKE_HOST_APPLE) # compile-guarded in CMake