project(): Add new CMAKE_PROJECT_TOP_LEVEL_INCLUDES file injection point

Fixes: #22685

1 files changed, 27 insertions, 0 deletions

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.