Not all the behaviors of CMake variables for ignoring search
locations by find_...() commands were fully documented.
Add the missing effects, clarify the wording and restructure the
way the details are assembled to reduce duplication.
Also improve the cross-referencing to ensure all the related
variables are more discoverable.
Issue: #20878
Allow find package to promote scope of imported targets by specifying
an argument to `find_package` or by specifying a CMake variable.
* Add support for CMAKE_GLOBAL_IMPORT_SCOPE variable
* Add support for GLOBAL argument to find_package
Additionally add testing for above features.
Add `--test-output-truncation` to `ctest`. This option can be used to
customize which part of the test output is being truncated. Currently
supported values are `tail`, `middle` and `head`.
Also add equivalent `CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable.
Fixes: #23206
Previously, headers would typically be installed as bare files or
as whole directories. File sets offer a better abstraction and
associate headers with a target, installing them as part of the
target. Add notes and update examples to draw the reader's
attention to the advantages of file sets for headers.
Reduce duplication and make the docs for target_sources() focus
on the functionality rather than the properties it modifies.
The properties are a lower level quantity, so put the relevant
details for them in the property documentation. The target_sources()
command only needs to reference the properties, not reproduce
the property documentation.
Improve the cross-referencing between the HEADER_... property
docs. This helps build the mental picture of how they relate to
each other.
Add section headers for each signature, and a synopsis linking to them.
Re-order sections to introduce the main `export(TARGETS)` functionality
before mentioning the `export(EXPORT)` shorthand, which may be confused
with `install(EXPORT)`.
Fixes: #23221
The wording update in commit b74819e4fe (Help: Format 'if' command
documentation, 2013-12-18, v3.0.0-rc1~227^2~1) incorrectly implied that
`AND` has higher precedence than `OR`. Although this is common in many
languages, it has never been true in CMake's implementation. Revise
the wording to clarify the precedence.
Add a test case demonstrating the order.
Fixes: #23207
Mention that system include directories are searched after normal
include directories.
Document that `IMPORTED_NO_SYSTEM` and `NO_SYSTEM_FROM_IMPORTED`
do not affect `INTERFACE_SYSTEM_INCLUDE_DIRECTORIES`.
In commit c705279bae (Help: Add `.. versionadded` directives to commands
documentation, 2020-11-08, v3.20.0-rc1~508^2) we accidentally added
``versionadded`` markup suggesting that the first argument to
`try_compile` was fixed as `RESULT_VAR` prior to CMake 3.14. This was
probably due to misinterpreting the change from commit 7975edeac5 (Help:
User-provided variable names for try_* commands, 2019-02-24,
v3.14.0-rc3~16^2~3).
The result variable has never been fixed. Drop the incorrect markup.
The %f specified extends the string(TIMESTAMP) and file(TIMESTAMP)
commands to output the timestamp with a microsecond resolution.
This convention is offered by python's datetime module.
Before, the precision was limited to seconds.
The implementation is done by extending existing cmTimestamp methods
with a `microseconds` parameter. This parameter is optional in order to
be backwards compatible. The timestamps are now received in a
cross-platform manner using libuv, since the standard C functions like
time() don't allow for sub-second precision.
This requires libuv 1.28 or higher. We already require higher than
that on Windows, so update the required version for other platforms.
Implements: #19335
294581a443 Help: Be more explicit about the behavior of if(<string>)
3a9695557d Help: Explicitly state that if(ENV{some_var}) is always false
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6768
250acbb099 Help: Improve cross-referencing of test LABELS and related features
a77bdefa3e Help: Add missing version details for Additional Test Measurements
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6726
With some of the content expanded, reorder a few paragraphs
and tweak some of the wording to improve the flow.
Co-Authored-By: Craig Scott <craig.scott@crascit.com>
This generator expression does not report the locations of `.dll`
files on imported targets with the `UNKNWON` type, since their
`IMPORTED_LOCATION` refers to the import library and not the DLL.
Fixes: #22845
