cmExperimental: gate build database support behind a flag

Given that the feature currently only supports C++ sources and is not
formally accepted by ISO yet, gate it behind a flag.

13 files changed, 74 insertions, 0 deletions

diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst
index fb33112..f5b9114 100644
--- a/Help/dev/experimental.rst
+++ b/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.
diff --git a/Help/envvar/CMAKE_EXPORT_BUILD_DATABASE.rst b/Help/envvar/CMAKE_EXPORT_BUILD_DATABASE.rst
index ff0fec4..b6d004d 100644
--- a/Help/envvar/CMAKE_EXPORT_BUILD_DATABASE.rst
+++ b/Help/envvar/CMAKE_EXPORT_BUILD_DATABASE.rst
@@ -9,3 +9,9 @@ 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.
diff --git a/Help/prop_tgt/EXPORT_BUILD_DATABASE.rst b/Help/prop_tgt/EXPORT_BUILD_DATABASE.rst
index 6b2ad1b..6f68b47 100644
--- a/Help/prop_tgt/EXPORT_BUILD_DATABASE.rst
+++ b/Help/prop_tgt/EXPORT_BUILD_DATABASE.rst
@@ -7,3 +7,9 @@ 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.
diff --git a/Help/variable/CMAKE_EXPORT_BUILD_DATABASE.rst b/Help/variable/CMAKE_EXPORT_BUILD_DATABASE.rst
index 6b606a0..94d9842 100644
--- a/Help/variable/CMAKE_EXPORT_BUILD_DATABASE.rst
+++ b/Help/variable/CMAKE_EXPORT_BUILD_DATABASE.rst
@@ -3,6 +3,12 @@ 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
diff --git a/Source/cmExperimental.cxx b/Source/cmExperimental.cxx
index 4504c07..1bfd9b9 100644
--- a/Source/cmExperimental.cxx
+++ b/Source/cmExperimental.cxx
@@ -56,6 +56,15 @@ cmExperimental::FeatureData LookupTable[] = {
     {},
     cmExperimental::TryCompileCondition::Always,
     false },
+  // ExportBuildDatabase
+  { "ExportBuildDatabase",
+    "4bd552e2-b7fb-429a-ab23-c83ef53f3f13",
+    "CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE",
+    "CMake's support for exporting build databases is experimental. It is "
+    "meant only for experimentation and feedback to CMake developers.",
+    {},
+    cmExperimental::TryCompileCondition::Never,
+    false },
 };
 static_assert(sizeof(LookupTable) / sizeof(LookupTable[0]) ==
                 static_cast<size_t>(cmExperimental::Feature::Sentinel),
diff --git a/Source/cmExperimental.h b/Source/cmExperimental.h
index 46a9bc4..875491c 100644
--- a/Source/cmExperimental.h
+++ b/Source/cmExperimental.h
@@ -21,6 +21,7 @@ public:
     WindowsKernelModeDriver,
     CxxImportStd,
     ExportPackageInfo,
+    ExportBuildDatabase,
 
     Sentinel,
   };
diff --git a/Source/cmGeneratorTarget.cxx b/Source/cmGeneratorTarget.cxx
index fcf790f..4b7e243 100644
--- a/Source/cmGeneratorTarget.cxx
+++ b/Source/cmGeneratorTarget.cxx
@@ -5942,6 +5942,10 @@ std::string cmGeneratorTarget::BuildDatabasePath(
   if (!this->GetPropertyAsBool("EXPORT_BUILD_DATABASE")) {
     return {};
   }
+  if (!cmExperimental::HasSupportEnabled(
+        *this->Makefile, cmExperimental::Feature::ExportBuildDatabase)) {
+    return {};
+  }
   // Check to see if the generator supports it.
   if (!this->GetGlobalGenerator()->SupportsBuildDatabase()) {
     return {};
diff --git a/Source/cmGlobalGenerator.cxx b/Source/cmGlobalGenerator.cxx
index a38208c..d6d4653 100644
--- a/Source/cmGlobalGenerator.cxx
+++ b/Source/cmGlobalGenerator.cxx
@@ -34,6 +34,7 @@
 #include "cmCustomCommandLines.h"
 #include "cmCustomCommandTypes.h"
 #include "cmDuration.h"
+#include "cmExperimental.h"
 #include "cmExportBuildFileGenerator.h"
 #include "cmExternalMakefileProjectGenerator.h"
 #include "cmGeneratedFileStream.h"
@@ -3303,6 +3304,10 @@ bool cmGlobalGenerator::AddBuildDatabaseTargets()
   if (!mf->IsOn("CMAKE_EXPORT_BUILD_DATABASE")) {
     return true;
   }
+  if (!cmExperimental::HasSupportEnabled(
+        *mf.get(), cmExperimental::Feature::ExportBuildDatabase)) {
+    return {};
+  }
 
   static const auto reservedTargets = { "cmake_build_database" };
   for (auto const& target : reservedTargets) {
diff --git a/Tests/RunCMake/CXXModules/NinjaDependInfoCompileDatabase-stderr.txt b/Tests/RunCMake/CXXModules/NinjaDependInfoCompileDatabase-stderr.txt
new file mode 100644
index 0000000..b9886ad
--- /dev/null
+++ b/Tests/RunCMake/CXXModules/NinjaDependInfoCompileDatabase-stderr.txt
@@ -0,0 +1,4 @@
+CMake Warning \(dev\) in CMakeLists.txt:
+  CMake's support for exporting build databases is experimental.  It is meant
+  only for experimentation and feedback to CMake developers.
+This warning is for project developers.  Use -Wno-dev to suppress it.
diff --git a/Tests/RunCMake/CXXModules/NinjaDependInfoCompileDatabase.cmake b/Tests/RunCMake/CXXModules/NinjaDependInfoCompileDatabase.cmake
index 1208279..91a6884 100644
--- a/Tests/RunCMake/CXXModules/NinjaDependInfoCompileDatabase.cmake
+++ b/Tests/RunCMake/CXXModules/NinjaDependInfoCompileDatabase.cmake
@@ -2,6 +2,8 @@
 # here.
 set(CMAKE_CXX_SCANDEP_SOURCE "")
 
+set(CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE "4bd552e2-b7fb-429a-ab23-c83ef53f3f13")
+
 enable_language(CXX)
 
 if (NOT CMAKE_GENERATOR MATCHES "Ninja")
diff --git a/Tests/RunCMake/CXXModules/examples/export-build-database-setup.cmake b/Tests/RunCMake/CXXModules/examples/export-build-database-setup.cmake
index 6a699c1..20a9e90 100644
--- a/Tests/RunCMake/CXXModules/examples/export-build-database-setup.cmake
+++ b/Tests/RunCMake/CXXModules/examples/export-build-database-setup.cmake
@@ -1,3 +1,5 @@
+set(CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE "4bd552e2-b7fb-429a-ab23-c83ef53f3f13")
+
 get_property(is_multiconfig GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
 if (is_multiconfig)
   set(CMAKE_CONFIGURATION_TYPES "Debug" "Release")
diff --git a/Tests/RunCMake/CXXModules/examples/export-build-database-stderr.txt b/Tests/RunCMake/CXXModules/examples/export-build-database-stderr.txt
new file mode 100644
index 0000000..b9886ad
--- /dev/null
+++ b/Tests/RunCMake/CXXModules/examples/export-build-database-stderr.txt
@@ -0,0 +1,4 @@
+CMake Warning \(dev\) in CMakeLists.txt:
+  CMake's support for exporting build databases is experimental.  It is meant
+  only for experimentation and feedback to CMake developers.
+This warning is for project developers.  Use -Wno-dev to suppress it.
diff --git a/Tests/RunCMake/CXXModules/examples/import-modules-export-build-database-stderr.txt b/Tests/RunCMake/CXXModules/examples/import-modules-export-build-database-stderr.txt
new file mode 100644
index 0000000..b9886ad
--- /dev/null
+++ b/Tests/RunCMake/CXXModules/examples/import-modules-export-build-database-stderr.txt
@@ -0,0 +1,4 @@
+CMake Warning \(dev\) in CMakeLists.txt:
+  CMake's support for exporting build databases is experimental.  It is meant
+  only for experimentation and feedback to CMake developers.
+This warning is for project developers.  Use -Wno-dev to suppress it.