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.
`.. 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
Replace our hard-coded defaults for `/MD` and `/MDd` with a first-class
abstraction to select the runtime library from an enumeration of logical
names. We've long hesitated to do this because the idea of "runtime
library selection" touches on related concepts on several platforms.
Avoid that scope creep by simply defining an abstraction that applies
only when targeting the MSVC ABI on Windows.
Removing the old default flags requires a policy because existing
projects may rely on string processing to edit them and choose a runtime
library under the old behavior. Add policy CMP0091 to provide
compatibility.
Fixes: #19108
All uppercase is typically used for command keywords. Non-keyword
arguments should generally be shown as `<something>` according
to the CMake documentation guide.
-- Forward GHS platform variables to try_compile()
CMAKE_TRY_COMPILE_PLATFORM_VARIABLES only worked for source signature try_compile()
-- Update tests to no longer add GHS platform variables to try_compile()
-- Avoid linker error in GhsMulti/GhsMultiCompilerOptions/CMakeLists.txt by building library
Projects use `try_compile` to check if they will be able to compile some
particular source code. When a language standard variable like
`CMAKE_CXX_STANDARD` is set, then the project intends to compile source
code using a compiler mode for that standard. Therefore it makes sense
for `try_compile` to use that standard in the test project too.
Unfortunately this was not done when support for the
`CMAKE_CXX_STANDARD` variable was first implemented. Add a policy to
introduce the improved behavior in a compatible way.
Closes: #16456
Give `try_compile` callers a way to control the `CXX_STANDARD`,
`CXX_STANDARD_REQUIRED`, and `CXX_EXTENSIONS` properties of the
generated test target (or the `C` equivalents) in order to compile a
test source for a particular language standard.
Issue: #16456
Add a `CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify a list
of custom variables to be forwarded to a `try_compile` test project.
This will be useful for platform information modules or toolchain files
to forward some platform-specific set of variables from the host project
(perhaps set in its cache) to the test project so that it can build the
same way.
Create a `CMAKE_TRY_COMPILE_TARGET_TYPE` option to specify use
of `add_library(... STATIC ...)` for the generated test project.
This will be useful for cross-compiling toolchains that cannot
link a binary without custom flags or scripts.
Set policy CMP0065 to the value used in the calling project.
Set the the value of CMAKE_ENABLE_EXPORTS if set in the calling
project to initialize the target property appropriately.
Explain that try_compile calls need to be protected with conditions to
avoid running more than once so that it is easy to isolate a single
try_compile to perform with --debug-trycompile.
