From 8d1944c675a2240f3b71f813cbf7139429ab766c Mon Sep 17 00:00:00 2001 From: Craig Scott 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 ] [ONLY_IF_DIFFERENT]) +.. versionadded:: 3.21 + Copy a file from ```` to ````. Directories are not supported. Symlinks are ignored and ````'s content is read and written to ```` 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 ```` path already exists, do not replace it if it is the - same as ````. Otherwise, an error is emitted. + If the ```` path already exists, do not replace it if the file's + contents are already the same as ```` (this avoids updating + ````'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 | REGEX ] [EXCLUDE] [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