This implements a limited exception mechanism for find_package() via
the UNWIND_INCLUDE keyword.
When package discovery via find_package(UNWIND_INCLUDE) fails the
StateSnapshot is updated to an UNWINDING state. In this state further
calls to find_package() and include() are forbidden. While in the
UNWINDING state, the include() command immediately calls
SetReturnInvoked() whenever it is reached.
The UNWINDING state is reset when a parent call to find_package() is
reached.
Fixes: #26897
Add `LICENSE` and `DEFAULT_LICENSE` arguments to the `PACKAGE_INFO`
modes of the `install` and `export` commands. If not otherwise
specified, the `LICENSE` will be taken from the project's
`SPDX_LICENSE`, if available.
Add an argument to the `project` command to allow specifying a license
for a project as a whole. This is in addition to specifying licenses on
individual targets, and will be used to set the license(s) on exported
packages.
Also, move listing of `COMPAT_VERSION` variables to follow
lexicographical order.
Replace the 'project-description-string' descriptor in the `project`,
`export` and `install` commands with 'description-string'. This is more
consistent, as none of the other descriptors include 'project-', and
it's arguably wrong in the context of `export`/`install`, as the
description applies to a package.
The `project` command mentions that it sets variables "intended for use
as default values in package metadata". Add a sentence that the
`install` and `export` commands actually do so for CPS. Also add
`COMPAT_VERSION` to the list of relevant options.
Historically, find_package() does not guarantee the order in which directories
matching a search path containing a glob expression are processed in - the
"first valid package" will be selected if there are multiple candidates. In such
cases, which package is chosen is completely random and can change, potentially
leading to build failures and reproducibility issues. This is rather unexpected
and confusing for developers.
Now that CMake has bumped its major version, it's a good time to change default
sort order and direction could be changed to natural sorting with a descending
order. That will result in the newest version of a library being picked in case
there are multiple ones available.
Add support for specifying CPS's supplemental `description` and
`website` attributes. Add ability to inherit these from the `project()`,
similar to how version information can be inherited.
Modify {export,install}(PACKAGE_INFO) commands to inherit version
information from the current project in situations where it seems
reasonable to do so. Add an option to explicitly request inheritance
from a specific project.
This leverages the recently added project(COMPAT_VERSION).
This updates the module documentation and deprecates some result
variables in favor of using imported targets.
Changes:
- Synced module documentation with other similar find modules.
- Reworded and updated descriptions.
- Renamed "Cache Variables" to "Hints".
- Added info about config mode.
- Added separate section "Deprecated Items".
- Mention of Threads::Threads imported target removed.
- Added intro code blocks showing how to include these modules.
- Used word "command" instead of "macro".
- Added examples sections.
- Updated and synced descriptions of commands and arguments.
- Added a rubric title for variables that affect the checks.
- Listed CMAKE_TRY_COMPILE_TARGET_TYPE variable in the rubric together
with CMAKE_REQUIRED_* variables.
- Added link to CheckCompilerFlag module in the target_compile_options()
docs.
- Used lowercase style for check_fortran_compiler_flag() command.
- Added a link to `$<COMPILE_LANGUAGE:languages>` generator expression
so it can be linked from other pages (See commit
2e37a20f02 for more info on the initial
style used).
- Fixed the GENEX_NOTE inclusion (starting with line after the 2nd line)
where part of the sentence was rendered in the output.
Add documentation for several options related to CPS export/install that
were not previously documented. Add note to update documentation when
(if) COMPAT_VERSION support is not specific to CPS.
- Added intro code block showing how to include this module.
- Added a list of variables that can affect the check. The
CMAKE_REQUIRED_LINK_OPTIONS is skipped as it is currently internally
overridden by the module's check command.
- Added examples section.
- Described command arguments as a list.
- Added included section describing the `LINKER:` (and `SHELL:`) prefix.
- Added link to the module in target_link_options() docs.
- Added intro code block with include() showing how to load this module.
- Used "command" instead of "macro".
- Removed duplicate mention of CMakeDependentOption module in the
option() documentation.
- Synced captions in examples.
EXCLUDE_EMPTY_DIRECTORIES option excludes empty directories under the
directory to install. A directory is considered not empty if and only if
the directory contains at least one file or one symbolic link or one
none-empty sub-directory.
Closes: #19189
This makes it easier to find documentation for each option.
Previously they were sprinkled throughout prose. It also
provides a good place for ``versionadded`` directives.
This hopefully helps a bit when upgrading CMake code that uses
`exec_program()` command.
Changes:
- Used third-person phrasing for the command description.
- The `exec_program()` command arguments in signature updated a bit.
- Mention of CMakeLists.txt file removed as this command also worked in
CMake scripts and other modes.
- Added examples section.
This updates the module documentation to be more synced with other
modules. Also, this module on the first glance doesn't do what most
people might think. Because when condition evaluates to false, internal
cache remains with the same value, and a local variable is created with
the value provided in the last argument.
- Command arguments described separately and their placeholders renamed
to more intuitive names.
- More examples added, starting with a very basic syntax usage to more
complex ones, each described in more details.
- Each example has include() added to be more clear that this is a
module command.
This adds a short example demonstrating how to set this property.
Additionally, a paragraph is added to the target_link_libraries() and
its debug/optimized keywords to mention that imported targets with
IMPORTED_CONFIGURATIONS property may provide better alternative for
linking.
The recent addition of component handling for CPS neglected to update
the documentation of how find_package handles component requests when
importing from CPS. Make those changes now.
