project(): Add new CMAKE_PROJECT_TOP_LEVEL_INCLUDES file injection point

Fixes: #22685

6 files changed, 50 insertions, 12 deletions

diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE.rst
index 41d9e5d..76b9d92 100644
--- a/Help/variable/CMAKE_PROJECT_INCLUDE.rst
+++ b/Help/variable/CMAKE_PROJECT_INCLUDE.rst
@@ -5,8 +5,11 @@ CMAKE_PROJECT_INCLUDE
 
 A CMake language file or module to be included as the last step of all
 :command:`project` command calls.  This is intended for injecting custom code
-into project builds without modifying their source.
+into project builds without modifying their source.  See :ref:`Code Injection`
+for a more detailed discussion of files potentially included during a
+:command:`project` call.
 
 See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`,
-:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and
-:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables.
+:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`,
+:variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, and
+:variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables.
diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst
index c2fd0f8..9a8c4b5 100644
--- a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst
+++ b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst
@@ -5,8 +5,11 @@ CMAKE_PROJECT_INCLUDE_BEFORE
 
 A CMake language file or module to be included as the first step of all
 :command:`project` command calls.  This is intended for injecting custom code
-into project builds without modifying their source.
+into project builds without modifying their source.  See :ref:`Code Injection`
+for a more detailed discussion of files potentially included during a
+:command:`project` call.
 
 See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`,
-:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and
-:variable:`CMAKE_PROJECT_INCLUDE` variables.
+:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`,
+:variable:`CMAKE_PROJECT_INCLUDE`, and
+:variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables.
diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst
index 74247f1..3bb5cd8 100644
--- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst
+++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst
@@ -4,8 +4,9 @@ CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
 A CMake language file or module to be included as the last step of any
 :command:`project` command calls that specify ``<PROJECT-NAME>`` as the project
 name.  This is intended for injecting custom code into project builds without
-modifying their source.
+modifying their source.  See :ref:`Code Injection` for a more detailed
+discussion of files potentially included during a :command:`project` call.
 
 See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`,
-:variable:`CMAKE_PROJECT_INCLUDE` and
-:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables.
+:variable:`CMAKE_PROJECT_INCLUDE`, :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`,
+and :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables.
diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst
index 39abb12..ca584c1 100644
--- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst
+++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst
@@ -6,8 +6,9 @@ CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE
 A CMake language file or module to be included as the first step of any
 :command:`project` command calls that specify ``<PROJECT-NAME>`` as the project
 name.  This is intended for injecting custom code into project builds without
-modifying their source.
+modifying their source.  See :ref:`Code Injection` for a more detailed
+discussion of files potentially included during a :command:`project` call.
 
 See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`,
-:variable:`CMAKE_PROJECT_INCLUDE` and
-:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables.
+:variable:`CMAKE_PROJECT_INCLUDE`, :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`,
+and :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables.
diff --git a/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst b/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst
new file mode 100644
index 0000000..2010b08
--- /dev/null
+++ b/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst
@@ -0,0 +1,27 @@
+CMAKE_PROJECT_TOP_LEVEL_INCLUDES
+--------------------------------
+
+.. versionadded:: 3.24
+
+:ref:`Semicolon-separated list <CMake Language Lists>` of CMake language
+files to include as part of the very first :command:`project` call.
+The files will be included immediately after the toolchain file has been read
+(if one is specified) and platform variables have been set, but before any
+languages have been enabled. Therefore, language-specific variables,
+including things like :variable:`CMAKE_<LANG>_COMPILER`, might not be set.
+See :ref:`Code Injection` for a more detailed discussion of files potentially
+included during a :command:`project` call.
+
+This variable is intended for specifying files that perform one-time setup
+for the build. It provides an injection point for things like configuring
+package managers, adding logic the user shares between projects (e.g. defining
+their own custom build types), and so on. It is primarily for users to add
+things specific to their environment, but not for specifying the toolchain
+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.
diff --git a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst
index ff8d59a..1117c1f 100644
--- a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst
+++ b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst
@@ -13,3 +13,6 @@ build directory, and if not found, relative to the source directory.
 
 This is initialized by the :envvar:`CMAKE_TOOLCHAIN_FILE` environment
 variable if it is set when a new build tree is first created.
+
+See the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable for setting
+other things not directly related to the toolchain.