From 8d1944c675a2240f3b71f813cbf7139429ab766c Mon Sep 17 00:00:00 2001 From: Craig Scott <craig.scott@crascit.com> Date: Sun, 18 Jul 2021 19:13:06 +1000 Subject: Help: Expand details for file(COPY_FILE) --- Help/command/file.rst | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/Help/command/file.rst b/Help/command/file.rst index a9cbd40..f038871 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -751,6 +751,8 @@ The options are: [RESULT <result>] [ONLY_IF_DIFFERENT]) +.. versionadded:: 3.21 + Copy a file from ``<oldname>`` to ``<newname>``. Directories are not supported. Symlinks are ignored and ``<oldfile>``'s content is read and written to ``<newname>`` as a new file. @@ -762,8 +764,17 @@ The options are: If ``RESULT`` is not specified and the operation fails, an error is emitted. ``ONLY_IF_DIFFERENT`` - If the ``<newname>`` path already exists, do not replace it if it is the - same as ``<oldname>``. Otherwise, an error is emitted. + If the ``<newname>`` path already exists, do not replace it if the file's + contents are already the same as ``<oldname>`` (this avoids updating + ``<newname>``'s timestamp). + +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. +The ``file(COPY_FILE)`` sub-command does not create such a dependency. + +See also the ``file(COPY)`` sub-command just below which provides +further file-copying capabilities. .. _COPY: .. _INSTALL: @@ -779,6 +790,11 @@ The options are: [[PATTERN <pattern> | REGEX <regex>] [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) +.. note:: + + For a simple file copying operation, the ``file(COPY_FILE)`` sub-command + just above may be easier to use. + The ``COPY`` signature copies files, directories, and symlinks to a destination folder. Relative input paths are evaluated with respect to the current source directory, and a relative destination is -- cgit v0.12