Add a handful of helper roles that allow many more command-line option
references to be written without explicit targets. Specifically, what
used to be written ':option:`--foo[=bar] <program --foo>` can now be
written ':program-option:`--foo`'. This allows many such references to
be significantly shortened.
For now, supported programs are 'cmake', 'cpack'. 'ctest',
'cmake--build' and 'cmake--install', which should cover most cases, but
more can be trivially added. Additionally, this does not make a
concerted effort to replace all existing uses, as it is intended mainly
for use in future updates.
Two targets whose names differ only in a `.exe` suffix create a
conflict when adding target- and file-level dependencies for a custom
command. Add CMP0212 to provide compatibility with the old behavior.
Issue: #27612
In commit 51f39a0f32 (Help: Fix install(SBOM) argument typo, 2026-02-27,
v4.3.0-rc2~8^2) the typo was fixed in the wrong signature. Revert that
and fix the correct signature.
Create a stack state for managing diagnostics. This will eventually
replace some of the global state used for diagnostics, as well as
providing a mechanism to add additional diagnostics.
For now, this is only the stack manipulation with a bare minimum of
interface logic (in particular, the `block` and `include` commands).
Nothing actually looks at the diagnostic state yet, and the primary user
interface does not yet exist (although there are some references to it
already).
Try to be a bit more consistent about:
- Placing angle brackets around text which serves as a placeholder
rather than being literal.
- Using curly brackets rather than angle brackets to denote groups where
one of the options is required.
- Describing optional list arguments like `<x>...` rather than
`[<x>...]`. (Instances of lists not associated with keywords are
intentionally left as-is, however.)
Also, teach our CMake lexer to understand curly braces used as above
(prior uses were only in parsed literals without syntax highlighting),
and to highlight them (and remaining uses of angle braces) as the type
Punctuation rather than the type Operator, for consistency with square
braces.
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.
Remove basic CPS import and export from 'experimental' status. Update
documentation and tests accordingly.
Note that mapped exports (CMAKE_EXPERIMENTAL_MAPPED_PACKAGE_INFO) are
still experimental.
Previously, `CMAKE_<LANG>_LINK_FLAGS` was an undocumented variable used
for linking executables only. Re-spell that variable mirroring the
existing spellings for shared and module libraries, and add policy
CMP0210 to preserve compatibility.
Then, repurpose `CMAKE_<LANG>_LINK_FLAGS` to provide a variable to be
used for per-language link flags for all target types, along with a
per-configuration variant. These are added to the `<LINK_FLAGS>` rule
placeholder in the generators.
Fixes: #21934
Relates: #25620
Co-authored-by: Brad King <brad.king@kitware.com>
