Kitware/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-10-15 20:46:37 +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 .. code-block:: cmake
configure_file(<input> <output> configure_file(<input> <output>
[FILE_PERMISSIONS <permissions>...] [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
FILE_PERMISSIONS <permissions>...]
[COPYONLY] [ESCAPE_QUOTES] [@ONLY] [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
[NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Copies an ``<input>`` file to an ``<output>`` file and substitutes 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 If the path names an existing directory the output file is placed
in that directory with the same file name as the input file. 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>...`` ``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`` ``COPYONLY``
Copy the file without replacing any variable references or other 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@``. Restrict variable replacement to references of the form ``@VAR@``.
This is useful for configuring scripts that use ``${VAR}`` syntax. 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>`` ``NEWLINE_STYLE <style>``
Specify the newline style for the output file. Specify Specify the newline style for the output file. Specify
``UNIX`` or ``LF`` for ``\n`` newlines, or 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 file(GENERATE OUTPUT output-file
<INPUT input-file|CONTENT content> <INPUT input-file|CONTENT content>
[CONDITION expression] [TARGET target] [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] ]) [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Generate an output file for each build configuration supported by the current 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:...>``, require a target for evaluation (e.g. ``$<COMPILE_FEATURES:...>``,
``$<TARGET_PROPERTY:prop>``). ``$<TARGET_PROPERTY:prop>``).
``FILE_PERMISSIONS <permissions>...``
Use user provided permissions for the generated file.
``NO_SOURCE_PERMISSIONS`` ``NO_SOURCE_PERMISSIONS``
.. versionadded:: 3.20
The generated file permissions default to the standard 644 value The generated file permissions default to the standard 644 value
(-rw-r--r--). (-rw-r--r--).
``USE_SOURCE_PERMISSIONS`` ``USE_SOURCE_PERMISSIONS``
Transfer the file permissions of the original file to the generated file. .. versionadded:: 3.20
This option expects INPUT option.
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>`` ``NEWLINE_STYLE <style>``
.. versionadded:: 3.20 .. versionadded:: 3.20
@@ -702,9 +712,9 @@ Create the given directories and their parents as needed.
.. code-block:: cmake .. code-block:: cmake
file(<COPY|INSTALL> <files>... DESTINATION <dir> file(<COPY|INSTALL> <files>... DESTINATION <dir>
[NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
[FILE_PERMISSIONS <permissions>...] [FILE_PERMISSIONS <permissions>...]
[DIRECTORY_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...]
[NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
[FOLLOW_SYMLINK_CHAIN] [FOLLOW_SYMLINK_CHAIN]
[FILES_MATCHING] [FILES_MATCHING]
[[PATTERN <pattern> | REGEX <regex>] [[PATTERN <pattern> | REGEX <regex>]