file(COPY_FILE): Add option to retry on Windows if input access fails

On Windows, a file may be inaccessible for a short time after it is
created.  This occurs for various reasons, including indexing, antivirus
tools, and NTFS's asynchronous semantics.  Add an `INPUT_MAY_BE_RECENT`
option to tell CMake that the input file may have been recently created
so that we can retry a few times to read it.

1 files changed, 10 insertions, 1 deletions

diff --git a/Help/command/file.rst b/Help/command/file.rst
index 2348937..df895d0 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -750,7 +750,8 @@ The options are:
 
   file(COPY_FILE <oldname> <newname>
        [RESULT <result>]
-       [ONLY_IF_DIFFERENT])
+       [ONLY_IF_DIFFERENT]
+       [INPUT_MAY_BE_RECENT])
 
 .. versionadded:: 3.21
 
@@ -769,6 +770,14 @@ The options are:
   contents are already the same as ``<oldname>`` (this avoids updating
   ``<newname>``'s timestamp).
 
+``INPUT_MAY_BE_RECENT``
+  .. versionadded:: 3.26
+
+  Tell CMake that the input file may have been recently created.  This is
+  meaningful only on Windows, where files may be inaccessible for a short
+  time after they are created.  With this option, if permission is denied,
+  CMake will retry reading the input a few times.
+
 This sub-command has some similarities to :command:`configure_file` with the
 ``COPYONLY`` option.  An important difference is that :command:`configure_file`
 creates a dependency on the source file, so CMake will be re-run if it changes.