In commit c9568de52c (install: Add CMAKE_INSTALL_MESSAGE variable
(#13761), 2014-06-24, v3.1.0-rc1~370^2~1) we incorrectly documented
that `CMAKE_INSTALL_MESSAGE` controls the status message for
`file(INSTALL)`. Revert that.
Fixes: #17162
Mention of the fallback of the command options to the CMAKE_...
variables was repeated in places. The wording was also a bit
unclear about whether the fallback only occurred when neither
TLS or neither NETRC option was given to the command. Move
the fallback details directly to each relevant option instead.
Also use cross-referencing to the variables where it was not
linked previously.
An new environment variable 'CMAKE_INSTALL_MODE' is introduced,
which can be used to ask CMake to create symbolic links
instead of copying files during a file(INSTALL ...).
The operation is at the file level only, directory trees are
still created using actual directories, not links.
Signed-off-by: Felix Lelchuk <felix.lelchuk@gmx.de>
The file(COPY_FILE) sub-command is closely related to the
file(COPY) sub-command. Move the former to just before the
latter for improved continuity. The file(RENAME) sub-command is
also somewhat related to file(COPY_FILE), so it was also moved to
keep it just before file(COPY_FILE).
The file(MAKE_DIRECTORY) sub-command was also moved to just
before the file(REMOVE) and file(REMOVE_RECURSE) sub-commands
to keep them together and improve logical flow of operations.
Duplicated textual patterns are factored out to make the text
more readable. The POST_INCLUDE_FILES and POST_EXCLUDE_FILES
were also previously missing from the main syntax block for
install(RUNTIME_DEPENDENCY_SET).
6234afdff4 Help: Document special cases for if(IS_ABSOLUTE)
789307b02f Help: Behavior of file(TO_NATIVE_PATH) depends on the host platform
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6016
769ff05483 Help: Clarify permission-related command options
900184616a Cleanup: Fix misspelt name of local C++ variable
635431a0c9 Tests: Check host platform instead of target for running stat
4ceb0ca59e Tests: Remove redundant files for configure_file() tests
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5945
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.
`.. versionchanged` directive might be more appropriate when
documentation refers to previous CMake version, old behavior
or a policy, and there's no new parameter or a variable involved.
Issue: #19715
This change ony concerns directives that appear in the document body.
The guidelines for inserting version directives:
* Baseline version is CMake 3.0, i.e. directives start at 3.1.
* Always use `.. versionadded::` directive, avoid ad-hoc version
references. Exception: policy pages.
* For new command signatures, put `versionadded` on a separate line
after the signature.
* For a group of new signatures in a new document section,
a single version note at the beginning of the section is sufficient.
* For new options, put `versionadded` on a separate line before
option description.
* If all the option descriptions in the list are short one-liners,
it's fine to put `versionadded` on the same line as the description.
* If multiple option descriptions in close proximity would have
the same ..versionadded directive, consider adding a single
directive after the list, mentioning all added options.
* For compact value lists and sub-option lists, put a single
`versionadded` directive after the list mentioning all additions.
* When a change is described in a single paragraph, put
`versionadded` into that paragraph.
* When only part of the paragraph has changed, separate the changed
part if it doesn't break the flow. Otherwise, write a follow-up
clarification paragraph and apply version directive to that.
* When multiple version directives are close by, order earlier
additions before later additions.
* Indent related lists and code blocks to include them in the scope
of `versionadded` directive.
Issue: #19715
The FILES and DIRECTORY options were renamed in bbcff21f71
(file(ARCHIVE*): Collapse FILES and DIRECTORY options, 2020-06-30),
but the synopsis part of the file() documentation was missed.
The synopsis also typically only shows the mandatory options.
Update the synopsis to reflect the name changes and omit the
DESTINATION option since it is not mandatory.
The two options were concatenated internally for both ARCHIVE_CREATE
and ARCHIVE_EXTRACT. The distinction between files and dirs was not
meaningful. Therefore, replace them with PATHS or PATTERNS
to more accurately describe the way the options are used.
Fixes: #20884
In commit a6fee09484 (file: Add CONFIGURE subcommand, 2020-03-06,
v3.18.0-rc1~584^2) we accidentally treated relative path outputs
with respect to the current working directory. Treat them with
respect to the current binary directory instead.
Fixes: #20885
On machines where the gnu bin utils are prefixed, or suffixed
the file(GET_RUNTIME_DEPENDENCIES ) command would fail without
explicitly setting the location of objdump.
Now we pre-populate the variables used to find objdump based
on the gnu bin utils, so that these use cases are better supported
Extend the `file()` command with a new `CONFIGURE` subcommand that
behaves the same as `string(CONFIGURE)` except that it writes the
resulting output immediately to a file.
Fixes: #20388
Note that ``MODULE`` s was rendering strangely, so the wording
has been tweaked to avoid needing to specify ``MODULE`` as a
plural word. Modules are still libraries, so it is okay to call them as
such where it doesn't cause any ambiguity.
m.klimenko