Add explicit cross-references for commands which optionally take an
output variable (otherwise modifying their input in-place) for clarity.
Note that `cmake_path` should not be used to modify variables reserved
by CMake.
Improve references to the "CMake-style" semicolon-separated lists, and
apply those corresponding changes to the `file` command page.
Add security flags to libarchive extraction to prevent path traversal
(Zip Slip) and absolute path attacks:
- ARCHIVE_EXTRACT_SECURE_NODOTDOT: Block ".." path components
- ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS: Block absolute paths
- ARCHIVE_EXTRACT_SECURE_SYMLINKS: Block symlinks escaping extract dir
This hardens both `cmake -E tar` and `file(ARCHIVE_EXTRACT)` against
malicious archives that attempt to write files outside the intended
extraction directory.
Using `signature` renders the anchor links for each sub-command, and is
consistent with the other `Help/command` pages which contain multiple
sub-commands.
If the connection fails in a way that might be a certificate error, and
verification was enabled by the new default, mention environment
variable `CMAKE_TLS_VERIFY` in the diagnostic to help users that were
relying on the old behavior turn off server certificate verification in
their environment.
Fixes: #23608
When a library file name is encountered multiple times, reuse the result
from the first time. This more closely matches the behavior of the
dynamic loader on Linux.
Fixes: #24621
Projects may be generating a list of files or directories to pass as arguments
to file(TOUCH), file(TOUCH_NOCREATE), or file(MAKE_DIRECTORY). Those
lists might end up being empty, so rather than requiring at least one item,
allow an empty list.
Fixes: #24897
Moved documentation of file(GET_RUNTIME_DEPENDENCIES ...) from
the 'Reading' section to a separate section at the bottom of
the page. Because it is a very long text, and because this
signature is quite different from all the others in the
'Reading' section.
Previously REAL_PATH would collapse paths before resolving any symlinks
so if `..` crossed a symlink the output from `REAL_PATH` would be wrong.
It looked like REAL_PATH did this by mistake since it was a side-effect
of ensuring we had an absolute path before resolving symlinks.
In commit fa45594407 (file(GET_RUNTIME_DEPENDENCIES): Preserve casing
for Windows PE binaries, 2023-03-06) we neglected to update associated
documentation.
Convert `file` command to use new `signature` directive. Use '<HASH>'
rather than 'HASH' for relevant signature targets, as this is arguably
more correct, results in less need to specify explicit targets, but
still produces '#hash' as the HTML anchor.
Although actual textual changes to `file` are fairly minimal, large
portions of the content have been re-indented and in many cases,
re-flowed. Some tabular content in literal text blocks has also been
converted to actual tables.
Some servers have allow-lists for HTTP UserAgent for example.
CMake project devs would benefit from this hint about setting
authorization tokens and HTTP User Agent.
On Windows, a file may be inaccessible for a short time after it is
created. This occurs for various reasons, including indexing, antivirus
tools, and NTFS's asynchronous semantics. Add an `INPUT_MAY_BE_RECENT`
option to tell CMake that the input file may have been recently created
so that we can retry a few times to read it.
This allows the Zstd compression-level to be set between 0-19. I've
adjusted some of the tests, and error messages to indicates the selected
algorithm, and min/max of its compression-level.
Fixes: #24160
Similar to GNU tar add a --touch option to the tar extract command to
skip extracting the timestamps from the files in the archive
effectively touching them as if they were just created.
Issue: #22746
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.
AJIOB
Tyler Yankee
Brad King
Leslie P. Polzer
hanna.rusakovich
Nikita Nemkin
Peter Kokot
Yuri Witte
Craig Scott
Aliaksandr Averchanka
Asit Dhal
Joachim Wuttke (h)
Ben Boeckel
Cristian Le
Robert Maynard
Matthew Woehlke
scivision
Amir Masoud Abdol
Alex Turbov
Kasper Laudrup
m.klimenko
Arcturus Arcturus