FetchContent: Populate directly without a sub-build

Fixes: #21703

3 files changed, 74 insertions, 0 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 43d54dc..72aedba 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.30
 .. toctree::
    :maxdepth: 1
 
+   CMP0168: FetchContent implements steps directly instead of through a sub-build. </policy/CMP0168>
    CMP0167: The FindBoost module is removed. </policy/CMP0167>
    CMP0166: TARGET_PROPERTY evaluates link properties transitively over private dependencies of static libraries. </policy/CMP0166>
    CMP0165: enable_language() must not be called before project(). </policy/CMP0165>
diff --git a/Help/policy/CMP0168.rst b/Help/policy/CMP0168.rst
new file mode 100644
index 0000000..8317351
--- /dev/null
+++ b/Help/policy/CMP0168.rst
@@ -0,0 +1,64 @@
+CMP0168
+-------
+
+.. versionadded:: 3.30
+
+The :module:`FetchContent` module implements steps directly instead of through
+a sub-build.
+
+CMake 3.29 and below implement FetchContent as a separate sub-build.
+This required configuring that separate project and using a build tool.
+This approach can be very slow with some generators and operating systems.
+CMake 3.30 and above prefer to implement the download, update, and patch
+steps directly as part of the main project.
+
+The ``NEW`` behavior has the following characteristics:
+
+* No sub-build is used. All operations are implemented directly from the
+  main project's CMake configure step. When running in CMake script mode,
+  no build tool needs to be available.
+* Generator expressions and GNU Make variables of the form ``$(SOMEVAR)`` are
+  not supported. They should not be used in any argument to
+  :command:`FetchContent_Declare` or :command:`FetchContent_Populate`.
+* All ``LOG_...`` and ``USES_TERMINAL_...`` options, the ``QUIET`` option, and
+  the :variable:`FETCHCONTENT_QUIET` variable are ignored.
+  :module:`FetchContent` output is always part of the main project's configure
+  output. This also means it now respects the message logging level (see
+  :variable:`CMAKE_MESSAGE_LOG_LEVEL` and
+  :option:`--log-level <cmake --log-level>`). The default message log level
+  should be comparable to using ``QUIET`` with the ``OLD`` policy setting,
+  except that warnings will now be shown.
+* The ``PREFIX``, ``TMP_DIR``, ``STAMP_DIR``, ``LOG_DIR``, and ``DOWNLOAD_DIR``
+  options and their associated directory properties are ignored. The
+  :module:`FetchContent` module controls those locations internally.
+
+The ``OLD`` behavior has the following characteristics:
+
+* A sub-build is always used to implement the download, update, and patch
+  steps. A build tool must be available, even when using
+  :command:`FetchContent_Populate` in CMake script mode.
+* Generator expressions and GNU Make variables of the form ``$(SOMEVAR)`` can
+  be used, although such use is almost always inappropriate. They are evaluated
+  in the sub-build, so they do not see any information from the main build.
+* All logging, terminal control, and directory options related to the download,
+  update, or patch steps are supported.
+* If the ``QUIET`` option is used, or the :variable:`FETCHCONTENT_QUIET`
+  variable is set to true, warnings will not be shown in the output.
+
+There's a reasonably good chance that users can set the
+:variable:`CMAKE_POLICY_DEFAULT_CMP0168 <CMAKE_POLICY_DEFAULT_CMP<NNNN>>`
+variable to ``NEW`` to globally switch to the ``NEW`` behavior while waiting
+for the project and its dependencies to be updated use the ``NEW`` policy
+setting by default. Projects don't typically make use of the features that the
+``NEW`` behavior no longer supports, and even those projects that do will often
+still work fine when those options are ignored. Before setting this behavior
+globally, check whether any :command:`FetchContent_Declare` or
+:command:`FetchContent_Populate` calls use the ignored options in a way that
+would change observable behavior, other than putting temporary or
+internally-generated files in different locations.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30
+.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/fetchcontent-direct.rst b/Help/release/dev/fetchcontent-direct.rst
new file mode 100644
index 0000000..7cb33ab
--- /dev/null
+++ b/Help/release/dev/fetchcontent-direct.rst
@@ -0,0 +1,9 @@
+fetchcontent-direct
+-------------------
+
+* :module:`FetchContent` now prefers to populate content directly rather
+  than using a separate sub-build. This may significantly improve configure
+  times on some systems (Windows especially, but also on macOS when using
+  the Xcode generator). Policy :policy:`CMP0168` provides backward
+  compatibility for those projects that still rely on using a sub-build for
+  content population.