The meaning of "absolute path" was previously assumed knowledge,
but a number of special cases were left unspecified. The way some of
these are handled differs to the way that cmake_path(IS_ABSOLUTE)
works, so document those special cases so that the differing behavior
between these two commands is clearly defined.
When using `add_library` to create an `IMPORTED` library target, there
are a few target properties that are essential to correctly tell CMake
about the library file. We already cover `IMPORTED_LOCATION` and
`IMPORTED_IMPLIB`. Add `IMPORTED_SONAME` and `IMPORTED_NO_SONAME`,
which are important in certain cases.
Fixes: #22016
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.
Since commit c2dc7e0f53 (Help: Convert genex documentation to sphinx
domain objects, 2021-01-15) we can use `:genex:` cross-references to
link to named generator expressions. Update some places to do this.
This is meant to demonstrate the capability, not as a comprehensive
sweep.
Documentation updates in commit 02f527c66a (Find: Provide global
controls for the `NO_[]_PATH` call options, 2019-06-12,
v3.16.0-rc1~541^2) accidentally switched the `find_library`
documentation to mention `INCLUDE` where it should be `LIB`.
While at it, update `find_file` and `find_path` to mention
`INCLUDE` and `PATH` in the order they are considered.
Update the documentation added by commit c257c25419
(add_custom_{command,target}: Add genex support to OUTPUT and
BYPRODUCTS, 2020-10-19) to use sphinx markup instead of prose to specify
the version in which the feature was added.
Move rejection of `#`, `<`, and `>` characters in outputs and byproducts
to a generate-time check. This removes the front-end check that
disallowed generator expressions. The generators have already been
updated to handle them.
Fixes: #12877
The CMAKE_MINIMUM_REQUIRED_VERSION has long been set by
the cmake_minimum_required() command, but the command docs
never mentioned this. Only the variable's own docs stated this but
the variable isn't very discoverable without it being mentioned in
the command's docs as well.
`.. 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
There was an ambiguity in the wording with the meaning of "or" typically
meaning exclusive-or in prose. Instead, ensure that the easiest parsing
is clear that the directory part is always removed.
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
