Previously code like
file(REMOVE_RECURSE "${accidentally_missing_variable}")
treated the empty string as a relative path with respect to the
current directory and removed its contents. Change this behavior
to ignore the empty string with a warning instead.
Normally such behavior changes are done with a policy, but in this case
such code is likely a real bug in project code that can delete data.
Fixes: #19274
Revise docs for all "Scripting Commands", except four find_XXX
that use a macro suite of their own.
* Take full advantage of the improved syntax highlighting.
* Make consequential use of <..> placeholders.
* Clarify things here and there in the text.
Specific improvements to some command docs:
* "math": Correct description of novel hexadecimal capability.
* "if", "foreach", "while": Provide link to "endif" etc
* "foreach", "while": Mention "break" and "continue".
* "foreach": Simplify explanation of ``RANGE`` and ``IN`` signatures;
advise against negative arguments or reverse ranges (compare issue #18461)
* "endif", "endfunction" etc: Explain that the argument is optional and
maintained for compatibility only
Some are user facing.
Found using
codespell -q 3 --skip="./Utilities" -I .cmake-whitelist.txt`
whereby the whitelist contained:
ans
dum
helpfull
emmited
emmitted
buil
iff
isnt
nto
ot
pathes
substract
te
todays
upto
whitespaces
When using `file(WRITE)`, parent directories are also created. Documentation
has been updated to explain this behavior.
Co-Author: Craig Scott <craig.scott@crascit.com>
It has been sorted since commit v3.6.0-rc1~54^2 (file: Sort GLOB results
to make it deterministic, 2016-05-14). That commit left the order
unspecified in the documentation, but has been stable long enough to
document now.
Previously `file(GENERATE)` did not define any behavior for relative
paths given to the `OUTPUT` or `INPUT` arguments. Define behavior
consistent with CMake conventions and add a policy to provide
compatibility for projects that relied on the old accidental behavior.
Fixes: #16786
Spell out the supported algorithms in a definition list in the
`string(<HASH>)` command documentation. Revise the `file(<HASH>)`
command and CPack module documentation to reference it instead of
duplicating the list.
Even though the `file(GLOB)` documentation specifically warns against
using it to collect a list of source files, projects often do it anyway.
Since it uses `readdir()`, the list of files will be unsorted.
This list is often passed directly to add_executable / add_library.
Linking binaries with an unsorted list will make it unreproducible,
which means that the produced binary will differ depending on the
unpredictable `readdir()` order.
To solve those reproducibility issues in a lot of programs (which don't
explicitly `list(SORT)` the list manually), sort the resulting list of
the `file(GLOB)` command.
A more detailed rationale about reproducible builds is available
[here](https://reproducible-builds.org/).
GLOB lists directories by default and GLOB_RECURSE does not.
LIST_DIRECTORIES enables user to control the behavior explicitly for
consistently for both GLOB and GLOB_RECURSE.
In commit v3.1.0-rc1~484^2 (Help: Format and revise file() command
documentation, 2014-05-23) the signature of file(GENERATE) was
accidentally simplified too much and dropped specification of the
required argument ordering. Restore the signature to make the order
clear.
Provide options to fail without blocking or to block up to a timeout.
Provide options to specify the scope containing the lock so it can be
released automatically at the end of a function, file, or process.
Extend the RunCMake.file test with cases covering the file(LOCK) command
usage and error cases.
Create a variable to allow users to control which installation
messages are printed. In particular, provide a "LAZY" setting
that prints "Installing" messages but not "Up-to-date" messages.
This is desirable for incremental re-installations.
Suggested-by: J Decker <d3ck0r@gmail.com>
Organize the documentation by sub-command to keep the signatures and
their descriptions nearby. Use inline and explicit reST markup. Revise
wording as necessary for the updated layout. Clarify behavior of the
file(GENERATE) command w.r.t. conflicting file names.
