Merge branch 'file_symlink_docs' into release-3.14
Merge-request: !2974
diff --git a/Help/command/file.rst b/Help/command/file.rst
index db4d6fc..465e567 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -26,8 +26,8 @@
file(`MAKE_DIRECTORY`_ [<dir>...])
file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
file(`SIZE`_ <filename> <out-var>)
- file(`READ_SYMLINK`_ <filename> <out-var>)
- file(`CREATE_LINK`_ <file> <new-file> [...])
+ file(`READ_SYMLINK`_ <linkname> <out-var>)
+ file(`CREATE_LINK`_ <original> <linkname> [...])
`Path Conversion`_
file(`RELATIVE_PATH`_ <out-var> <directory> <file>)
@@ -350,22 +350,22 @@
.. code-block:: cmake
- file(READ_SYMLINK <filename> <variable>)
+ file(READ_SYMLINK <linkname> <variable>)
-Read the symlink at ``<filename>`` and put the result in ``<variable>``.
-Requires that ``<filename>`` is a valid path pointing to a symlink. If
-``<filename>`` does not exist, or is not a symlink, an error is thrown.
+This subcommand queries the symlink ``<linkname>`` and stores the path it
+points to in the result ``<variable>``. If ``<linkname>`` does not exist or
+is not a symlink, CMake issues a fatal error.
Note that this command returns the raw symlink path and does not resolve
-relative symlinks. If you want to resolve the relative symlink yourself, you
-could do something like this:
+a relative path. The following is an example of how to ensure that an
+absolute path is obtained:
.. code-block:: cmake
- set(filename "/path/to/foo.sym")
- file(READ_SYMLINK "${filename}" result)
+ set(linkname "/path/to/foo.sym")
+ file(READ_SYMLINK "${linkname}" result)
if(NOT IS_ABSOLUTE "${result}")
- get_filename_component(dir "${filename}" DIRECTORY)
+ get_filename_component(dir "${linkname}" DIRECTORY)
set(result "${dir}/${result}")
endif()
@@ -373,23 +373,23 @@
.. code-block:: cmake
- file(CREATE_LINK <file> <new-file>
+ file(CREATE_LINK <original> <linkname>
[RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
-Create a link to ``<file>`` at ``<new-file>``.
+Create a link ``<linkname>`` that points to ``<original>``.
+It will be a hard link by default, but providing the ``SYMBOLIC`` option
+results in a symbolic link instead. Hard links require that ``original``
+exists and is a file, not a directory. If ``<linkname>`` already exists,
+it will be overwritten.
-It is a hard link by default. This can be changed to symbolic links by
-using ``SYMBOLIC``. The original file needs to exist for hard links.
-
-The ``<result>`` variable, if specified, gets the status of the operation.
-It is set to ``0`` in case of success. Otherwise, it contains the error
-generated. In case of failures, if ``RESULT`` is not specified, a fatal error
-is emitted.
+The ``<result>`` variable, if specified, receives the status of the operation.
+It is set to ``0`` upon success or an error message otherwise. If ``RESULT``
+is not specified and the operation fails, a fatal error is emitted.
Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if
-creating the link fails.
-
-Overwrites the ``<new-file>`` if it exists.
+creating the link fails. It can be useful for handling situations such as
+``<original>`` and ``<linkname>`` being on different drives or mount points,
+which would make them unable to support a hard link.
Path Conversion
^^^^^^^^^^^^^^^
