Kitware/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-10-15 03:48:02 +08:00
Code Issues Projects Releases Wiki Activity

Help: Clarify permission-related command options

Browse Source 
The previous docs did not make clear that at most only one of the three
permissions-related options can be given for configure_file() or
file(GENERATE) and that USE_SOURCE_PERMISSIONS is already the
default behavior for these commands.

Use consistent wording to refer to the input and output files for
configure_file().

Add missing "versionadded" directives on some of these keywords.

Use the consistent wording and keyword ordering between the
configure_file(), file(GENERATE) and file(COPY) commands.
This commit is contained in:
Craig Scott
2021-03-26 22:02:28 +11:00
parent 900184616a
commit 769ff05483
2 changed files with 40 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
Help/command/configure_file.rst
View File

@@ -6,9 +6,9 @@ Copy a file to another location and modify its contents.
.. code-block:: cmake
configure_file(<input> <output>
[FILE_PERMISSIONS <permissions>...]
[NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
FILE_PERMISSIONS <permissions>...]
[COPYONLY] [ESCAPE_QUOTES] [@ONLY]
[NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Copies an ``<input>`` file to an ``<output>`` file and substitutes
@@ -75,8 +75,27 @@ The arguments are:
If the path names an existing directory the output file is placed
in that directory with the same file name as the input file.
``NO_SOURCE_PERMISSIONS``
.. versionadded:: 3.19
Do not transfer the permissions of the input file to the output file.
The copied file permissions default to the standard 644 value
(-rw-r--r--).
``USE_SOURCE_PERMISSIONS``
.. versionadded:: 3.20
Transfer the permissions of the input file to the output file.
This is already the default behavior if none of the three permissions-related
keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS``
or ``FILE_PERMISSIONS``). The ``USE_SOURCE_PERMISSIONS`` keyword mostly
serves as a way of making the intended behavior clearer at the call site.
``FILE_PERMISSIONS <permissions>...``
Use user provided permissions for the output file.
.. versionadded:: 3.20
Ignore the input file's permissions and use the specified ``<permissions>``
for the output file instead.
``COPYONLY``
Copy the file without replacing any variable references or other
@@ -89,18 +108,6 @@ The arguments are:
Restrict variable replacement to references of the form ``@VAR@``.
This is useful for configuring scripts that use ``${VAR}`` syntax.
``NO_SOURCE_PERMISSIONS``
.. versionadded:: 3.19
Does not transfer the file permissions of the original file to the copy.
The copied file permissions default to the standard 644 value
(-rw-r--r--).
``USE_SOURCE_PERMISSIONS``
.. versionadded:: 3.20
Transfer the file permissions of the original file to the output file.
``NEWLINE_STYLE <style>``
Specify the newline style for the output file. Specify
``UNIX`` or ``LF`` for ``\n`` newlines, or specify

26
Help/command/file.rst
View File

@@ -480,8 +480,8 @@ modified.
file(GENERATE OUTPUT output-file
<INPUT input-file|CONTENT content>
[CONDITION expression] [TARGET target]
[FILE_PERMISSIONS <permissions>...]
[NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
[NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
FILE_PERMISSIONS <permissions>...]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Generate an output file for each build configuration supported by the current
@@ -523,16 +523,26 @@ from the input content to produce the output content. The options are:
require a target for evaluation (e.g. ``$<COMPILE_FEATURES:...>``,
``$<TARGET_PROPERTY:prop>``).
``FILE_PERMISSIONS <permissions>...``
Use user provided permissions for the generated file.
``NO_SOURCE_PERMISSIONS``
.. versionadded:: 3.20
The generated file permissions default to the standard 644 value
(-rw-r--r--).
``USE_SOURCE_PERMISSIONS``
Transfer the file permissions of the original file to the generated file.
This option expects INPUT option.
.. versionadded:: 3.20
Transfer the file permissions of the ``INPUT`` file to the generated file.
This is already the default behavior if none of the three permissions-related
keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS``
or ``FILE_PERMISSIONS``). The ``USE_SOURCE_PERMISSIONS`` keyword mostly
serves as a way of making the intended behavior clearer at the call site.
It is an error to specify this option without ``INPUT``.
``FILE_PERMISSIONS <permissions>...``
.. versionadded:: 3.20
Use the specified permissions for the generated file.
``NEWLINE_STYLE <style>``
.. versionadded:: 3.20
@@ -702,9 +712,9 @@ Create the given directories and their parents as needed.
.. code-block:: cmake
file(<COPY|INSTALL> <files>... DESTINATION <dir>
[NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
[FILE_PERMISSIONS <permissions>...]
[DIRECTORY_PERMISSIONS <permissions>...]
[NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
[FOLLOW_SYMLINK_CHAIN]
[FILES_MATCHING]
[[PATTERN <pattern> | REGEX <regex>]