try_compile: Propagating top level includes into whole-project calls

Fixes: #24151

6 files changed, 52 insertions, 4 deletions

diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst
index 38d06bb..a9c7653 100644
--- a/Help/command/cmake_language.rst
+++ b/Help/command/cmake_language.rst
@@ -271,6 +271,11 @@ Dependency Providers
   :command:`project`.  Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)``
   outside of that context will result in an error.
 
+  .. versionadded:: 3.30
+    The :prop_gbl:`PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE` global
+    property can be set if the dependency provider also wants to be enabled
+    in whole-project calls to :command:`try_compile`.
+
   .. note::
     The choice of dependency provider should always be under the user's control.
     As a convenience, a project may choose to provide a file that users can
diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst
index 9ee1d01..30ab41a 100644
--- a/Help/command/try_compile.rst
+++ b/Help/command/try_compile.rst
@@ -47,6 +47,11 @@ below for the meaning of other options.
   :ref:`configure-log try_compile event <try_compile configure-log event>`
   if the ``NO_LOG`` option is not specified.
 
+.. versionadded:: 3.30
+  If the :prop_gbl:`PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE` global
+  property is set to true, :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` is
+  propagated into the project's build configuration.
+
 This command supports an alternate signature for CMake older than 3.25.
 The signature above is recommended for clarity.
 
@@ -388,6 +393,12 @@ configuration:
   :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` to specify the MSVC debug
   information format.
 
+.. versionadded:: 3.30
+  If the :prop_gbl:`PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE` global
+  property is set to true, :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` is
+  propagated into the test project's build configuration when using the
+  :ref:`whole-project signature <Try Compiling Whole Projects>`.
+
 See Also
 ^^^^^^^^
 
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 7e640df..c72f490 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -44,6 +44,7 @@ Properties of Global Scope
    /prop_gbl/PACKAGES_FOUND
    /prop_gbl/PACKAGES_NOT_FOUND
    /prop_gbl/PREDEFINED_TARGETS_FOLDER
+   /prop_gbl/PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE
    /prop_gbl/REPORT_UNDEFINED_PROPERTIES
    /prop_gbl/RULE_LAUNCH_COMPILE
    /prop_gbl/RULE_LAUNCH_CUSTOM
diff --git a/Help/prop_gbl/PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE.rst b/Help/prop_gbl/PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE.rst
new file mode 100644
index 0000000..edfee17
--- /dev/null
+++ b/Help/prop_gbl/PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE.rst
@@ -0,0 +1,19 @@
+PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE
+-------------------------------------------
+
+.. versionadded:: 3.30
+
+When this global property is set to true, the
+:variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable is propagated into
+:command:`try_compile` calls that use the
+:ref:`whole-project signature <Try Compiling Whole Projects>`.
+Calls to the :ref:`source file signature <Try Compiling Source Files>` are not
+affected by this property.
+``PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE`` is unset by default.
+
+For :ref:`dependency providers <dependency_providers_overview>` that want to
+be enabled in whole-project :command:`try_compile` calls, set this global
+property to true just before or after registering the provider.
+Note that all files listed in :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES`
+will need to be able to handle being included in such :command:`try_compile`
+calls, and it is the user's responsibility to ensure this.
diff --git a/Help/release/dev/dep-provider-try_compile.rst b/Help/release/dev/dep-provider-try_compile.rst
new file mode 100644
index 0000000..666c9b1
--- /dev/null
+++ b/Help/release/dev/dep-provider-try_compile.rst
@@ -0,0 +1,9 @@
+dep-provider-try_compile
+------------------------
+
+* The :prop_gbl:`PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE` global property
+  can be used to propagate :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` into
+  :command:`try_compile` calls that use the
+  :ref:`whole-project signature <Try Compiling Whole Projects>`.
+  This is primarily intended as a way for dependency providers to be enabled
+  in such :command:`try_compile` calls.
diff --git a/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst b/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst
index 54f530e..805b7ea 100644
--- a/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst
+++ b/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst
@@ -25,7 +25,10 @@ details (use :variable:`CMAKE_TOOLCHAIN_FILE` for that).
 
 By default, this variable is empty.  It is intended to be set by the user.
 
-See also the :variable:`CMAKE_PROJECT_INCLUDE`,
-:variable:`CMAKE_PROJECT_INCLUDE_BEFORE`,
-:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, and
-:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables.
+See also:
+
+* :variable:`CMAKE_PROJECT_INCLUDE`
+* :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`
+* :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`
+* :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`
+* :prop_gbl:`PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE`