Merge topic 'fc-cmp0168-fresh'

9299cbbdb4 FetchContent: Force cmake --fresh to re-execute direct population steps
e82e2c38c1 Tests: RunCMake.FetchContent should not always force _deps removal
f97b25ec4b Tests: Fix -direct variants of FetchContent tests using wrong files
11b684c449 FetchContent: Fix typos in stamp/step file names
a02eec4a9f FetchContent,ExternalProject: Fix extra semicolons in step commands

Acked-by: Kitware Robot <[email protected]>
Tested-by: buildbot <[email protected]>
Merge-request: !9589

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/ExternalProject/shared_internal_commands.cmake

@@ -777,7 +777,7 @@ function(_ep_add_script_commands script_var work_dir cmd)
 
   # There can be multiple COMMANDs, but we have to split those up to
   # one command per call to execute_process()
-  set(execute_process_cmd
+  string(CONCAT execute_process_cmd
     "execute_process(\n"
     "  WORKING_DIRECTORY \"${work_dir}\"\n"
     "  COMMAND_ERROR_IS_FATAL LAST\n"

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
@@ -1674,7 +1685,7 @@ function(__FetchContent_populateDirect)
   # using a sub-build and is not appropriate for us here.
 
   set(download_script ${_EP_TMP_DIR}/download.cmake)
-  set(update_script   ${_EP_TMP_DIR}/upload.cmake)
+  set(update_script   ${_EP_TMP_DIR}/update.cmake)
   set(patch_script    ${_EP_TMP_DIR}/patch.cmake)
   _ep_add_download_command(${contentName}
     SCRIPT_FILE ${download_script}
@@ -1690,7 +1701,7 @@ function(__FetchContent_populateDirect)
   )
 
   set(download_stamp ${_EP_STAMP_DIR}/download.stamp)
-  set(update_stamp   ${_EP_STAMP_DIR}/upload.stamp)
+  set(update_stamp   ${_EP_STAMP_DIR}/update.stamp)
   set(patch_stamp    ${_EP_STAMP_DIR}/patch.stamp)
   __FetchContent_doStepDirect(
     SCRIPT_FILE ${download_script}

Tests/RunCMake/FetchContent/CMakeLists.txt

@@ -1,12 +1,8 @@
 cmake_minimum_required(VERSION 3.9)
 project(${RunCMake_TEST} NONE)
 
-# Tests assume no previous downloads in the output directory
-file(REMOVE_RECURSE ${CMAKE_CURRENT_BINARY_DIR}/_deps)
-
 if(CMP0168 STREQUAL "NEW")
   cmake_policy(SET CMP0168 NEW)
-  string(REGEX REPLACE "-direct$" "" RunCMake_TEST "${RunCMake_TEST}")
 else()
   cmake_policy(SET CMP0168 OLD)
 endif()

Tests/RunCMake/FetchContent/RunCMakeTest.cmake

@@ -4,7 +4,8 @@ unset(RunCMake_TEST_NO_CLEAN)
 
 function(run_cmake_with_cmp0168 name)
   run_cmake_with_options("${name}" -D CMP0168=OLD ${ARGN})
-  run_cmake_with_options("${name}-direct" -D CMP0168=NEW ${ARGN})
+  set(RunCMake_TEST_VARIANT_DESCRIPTION "-direct")
+  run_cmake_with_options("${name}" -D CMP0168=NEW ${ARGN})
 endfunction()
 
 # Won't get to the part where CMP0168 matters
@@ -16,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)
@@ -46,18 +55,16 @@ run_cmake_with_cmp0168(ManualSourceDirectoryRelative
 
 function(run_FetchContent_DirOverrides cmp0168)
   if(cmp0168 STREQUAL "NEW")
-    set(suffix "-direct")
-  else()
-    set(suffix "")
+    set(RunCMake_TEST_VARIANT_DESCRIPTION "-direct")
   endif()
-  set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/DirOverrides${suffix}-build)
+  set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/DirOverrides${RunCMake_TEST_VARIANT_DESCRIPTION}-build)
   file(REMOVE_RECURSE "${RunCMake_TEST_BINARY_DIR}")
   file(MAKE_DIRECTORY "${RunCMake_TEST_BINARY_DIR}")
 
-  run_cmake_with_options(DirOverrides${suffix} -D CMP0168=${cmp0168})
+  run_cmake_with_options(DirOverrides -D CMP0168=${cmp0168})
 
   set(RunCMake_TEST_NO_CLEAN 1)
-  run_cmake_with_options(DirOverridesDisconnected${suffix}
+  run_cmake_with_options(DirOverridesDisconnected
     -D CMP0168=${cmp0168}
     -D FETCHCONTENT_FULLY_DISCONNECTED=YES
   )