Re-organize the section to explicitly describe target-specific
commands, build properties, and usage requirement properties.
Add builtin transitive properties that have been created since
the document was first written.
This requires knowing when a generated header is public, which we can
model using file sets. Add policy CMP0154 to treat generated sources
as private by default in targets with file sets. Generated public
headers can be specified in public file sets.
Fixes: #24959
Issue: #15555
C++ modules have two variants which are of importance to CMake:
- `CXX_MODULES`: interface modules (those using `export module M;`,
`export module M:part;`, or `module M:internal_part;`)
- `CXX_MODULE_HEADER_UNITS`: importable header units
Creating C++ modules or partitions are *not* supported in any other
source listing. This is because the source files must be installed (so
their scope matters), but not part of usage requirements (what it means
for a module source to be injected into a consumer is not clear at this
moment). Due to the way `FILE_SET` works with scopes, they are a perfect
fit as long as `INTERFACE` is not allowed (which it is not).
The feature needs a specialized implementation to place headers
in the right place inside frameworks. To avoid silently doing
the wrong thing, make this case an error for the 3.23 series.
Issue: #23386
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.
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>
`.. 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
Previously the command considered non-absolute source file paths relative to
the associated target on the LHS. This causes problems in incremental builds
where files are added from subdirectories and forces users to workaround by
manually converting to absolute paths. Change this to enable more intuitive
usage by projects.
Fixes#17981
Now, several `INTERFACE_*` properties can be set on `IMPORTED` targets,
not only via `set_property` and `set_target_properties` but also via
`target_compile_definitions`, `target_compile_features`,
`target_compile_options`, `target_include_directories`, `target_sources`
and `target_link_libraries`.
Fixes: #15689
Issue: #17197
