FetchContent: Force cmake --fresh to re-execute direct population steps

Issue: #25468

Help/manual/cmake.1.rst

@@ -213,6 +213,13 @@ Options
  This removes any existing ``CMakeCache.txt`` file and associated
  ``CMakeFiles/`` directory, and recreates them from scratch.
 
+ .. versionchanged:: 3.30
+
+   For dependencies previously populated by :module:`FetchContent` with the
+   ``NEW`` setting for policy :policy:`CMP0168`, their stamp and script files
+   from any previous run will be removed. The download, update, and patch
+   steps will therefore be forced to re-execute.
+
 .. option:: -L[A][H]
 
  List non-advanced cached variables.
@@ -1381,9 +1388,8 @@ The options are:
 
 .. option:: --fresh
 
-  Perform a fresh configuration of the build tree.
-  This removes any existing ``CMakeCache.txt`` file and associated
-  ``CMakeFiles/`` directory, and recreates them from scratch.
+  Perform a fresh configuration of the build tree, which has the same effect
+  as :option:`cmake --fresh`.
 
 View Help
 =========

Help/policy/CMP0168.rst

@@ -31,6 +31,11 @@ The ``NEW`` behavior has the following characteristics:
 * 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.
+* :option:`cmake --fresh` will remove the stamp and script files used for
+  tracking and populating the dependency. This will force the dependency's
+  download, update, and patch steps to be re-executed. The directory used for
+  downloads is not affected by :option:`cmake --fresh`, so any previously
+  downloaded files for the ``URL`` download method can still be re-used.
 
 The ``OLD`` behavior has the following characteristics:
 
@@ -44,6 +49,9 @@ The ``OLD`` behavior has the following characteristics:
   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.
+* :option:`cmake --fresh` has no effect on the dependency's stamp or script
+  files. Previously executed steps will only re-run if details about the
+  dependency have changed.
 
 There's a reasonably good chance that users can set the
 :variable:`CMAKE_POLICY_DEFAULT_CMP0168 <CMAKE_POLICY_DEFAULT_CMP<NNNN>>`

Help/release/3.30.rst

@@ -224,9 +224,10 @@ Other Changes
 * :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.
+  the Xcode generator). :option:`cmake --fresh` also forces the download,
+  update, and patch steps of directly populated dependencies to be re-executed.
+  Policy :policy:`CMP0168` provides backward compatibility for those projects
+  that still rely on using a sub-build for content population.
 
 * When :variable:`FETCHCONTENT_FULLY_DISCONNECTED` is set to true,
   :command:`FetchContent_MakeAvailable` and the single-argument form of

Modules/FetchContent.cmake

@@ -1653,9 +1653,19 @@ function(__FetchContent_populateDirect)
   # extensive customization options it supports either. Note that
   # _EP_SOURCE_DIR and _EP_BINARY_DIR are always included in the saved args,
   # so we must not set them here.
-  set(_EP_STAMP_DIR "${FETCHCONTENT_BASE_DIR}/${contentNameLower}-stamp")
-  set(_EP_TMP_DIR   "${FETCHCONTENT_BASE_DIR}/${contentNameLower}-tmp")
-  set(_EP_DOWNLOAD_DIR "${_EP_TMP_DIR}")
+  if(cmake_role STREQUAL "PROJECT")
+    # Put these under CMakeFiles so that they are removed by "cmake --fresh",
+    # which will cause the steps to re-run.
+    set(_EP_STAMP_DIR "${CMAKE_BINARY_DIR}/CMakeFiles/fc-stamp/${contentNameLower}")
+    set(_EP_TMP_DIR   "${CMAKE_BINARY_DIR}/CMakeFiles/fc-tmp/${contentNameLower}")
+  else()
+    # We have no CMakeFiles in script mode, so keep everything together.
+    set(_EP_STAMP_DIR "${FETCHCONTENT_BASE_DIR}/${contentNameLower}-stamp")
+    set(_EP_TMP_DIR   "${FETCHCONTENT_BASE_DIR}/${contentNameLower}-tmp")
+  endif()
+  # Always put downloaded things under FETCHCONTENT_BASE_DIR so that we can
+  # reuse previously downloaded content, even after a "cmake --fresh".
+  set(_EP_DOWNLOAD_DIR "${FETCHCONTENT_BASE_DIR}/${contentNameLower}-tmp")
 
   # If CMAKE_DISABLE_SOURCE_CHANGES is set to true and _EP_SOURCE_DIR is an
   # existing directory in our source tree, calling file(MAKE_DIRECTORY) on it
@@ -1667,6 +1677,7 @@ function(__FetchContent_populateDirect)
     "${_EP_BINARY_DIR}"
     "${_EP_STAMP_DIR}"
     "${_EP_TMP_DIR}"
+    "${_EP_DOWNLOAD_DIR}"
   )
 
   # We take over the stamp files and use our own for detecting whether each

Tests/RunCMake/FetchContent/RunCMakeTest.cmake

@@ -17,6 +17,14 @@ run_cmake_with_options(VarPassthroughs -D CMP0168=OLD)
 
 run_cmake_with_cmp0168(DirectIgnoresDetails)
 run_cmake_with_cmp0168(FirstDetailsWin)
+block(SCOPE_FOR VARIABLES)
+  # Reuse this test to also verify that "cmake --fresh" re-executes the steps
+  # when using the direct mode
+  set(RunCMake_TEST_NO_CLEAN 1)
+  set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/FirstDetailsWin-direct-build)
+  set(RunCMake_TEST_VARIANT_DESCRIPTION "-direct-fresh")
+  run_cmake_with_options(FirstDetailsWin -D CMP0168=NEW --fresh)
+endblock()
 run_cmake_with_cmp0168(DownloadTwice)
 run_cmake_with_cmp0168(DownloadFile)
 run_cmake_with_cmp0168(IgnoreToolchainFile)