ExternalProject: Add DOWNLOAD_EXTRACT_TIMESTAMP option and policy

Add the option to keep the current filestamps when extracting an
archive in ExternalProject_Add.

Enabling this option makes the behavior consistent with how
ExternalProject_Add is used when checking out code from revision
control instead of an archive.

Fixes: #22746

1 files changed, 29 insertions, 0 deletions

diff --git a/Help/policy/CMP0135.rst b/Help/policy/CMP0135.rst
new file mode 100644
index 0000000..1c0c134
--- /dev/null
+++ b/Help/policy/CMP0135.rst
@@ -0,0 +1,29 @@
+CMP0135
+-------
+
+.. versionadded:: 3.24
+
+When using the ``URL`` download method with the :command:`ExternalProject_Add`
+command, CMake 3.23 and below sets the timestamps of the extracted contents
+to the same as the timestamps in the archive. When the ``URL`` changes, the
+new archive is downloaded and extracted, but the timestamps of the extracted
+contents might not be newer than the previous contents. Anything that depends
+on the extracted contents might not be rebuilt, even though the contents may
+change.
+
+CMake 3.24 and above prefers to set the timestamps of all extracted contents
+to the time of the extraction. This ensures that anything that depends on the
+extracted contents will be rebuilt whenever the ``URL`` changes.
+
+The ``DOWNLOAD_EXTRACT_TIMESTAMP`` option to the
+:command:`ExternalProject_Add` command can be used to explicitly specify how
+timestamps should be handled. When ``DOWNLOAD_EXTRACT_TIMESTAMP`` is not
+given, this policy controls the default behavior. The ``OLD`` behavior for
+this policy is to restore the timestamps from the archive. The ``NEW``
+behavior sets the timestamps of extracted contents to the time of extraction.
+
+This policy was introduced in CMake version 3.24.  CMake version |release|
+warns when the policy is not set and uses ``OLD`` behavior.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt