This was added in 2.6.0 by commit c1b3484c2d (ENH: store the matches for
paren-delimited subexpression..., 2007-08-21, v2.6.0~1227), not in 3.9.
Only the documentation at this place was added in 3.9, by commit
eb08e1febb (Help: Document CMAKE_MATCH_<n> variables, 2017-04-18,
v3.9.0-rc1~257^2)
Explicitly state that if `<PackageName>_DIR` is set, but the version of
the package found there does not match the requested version, then
`find_package` will ignore that directory and continue searching.
Add a `CUSTOM_CONTENT` argument to `cmake_instrumentation()` for collecting
custom content from configure time.
Snippet files include a reference to a JSON file containing any `CUSTOM_CONTENT`
that was added by this command.
Fixes: #26703
Add the support of CACHE{variable} syntax to enable:
* better consistency with other commands which use this syntax
* more flexibility regarding cache variable options
Revert commit b70ef48b27 (install(DIRECTORY): Add
EXCLUDE_EMPTY_DIRECTORIES option, 2025-04-20, v4.1.0-rc1~212^2).
The implementation had at least two problems:
* It did not exclude the top-level directory if empty.
* It did not exclude non-empty directories whose contents are
all filtered out.
Revert the feature pending a revised implementation.
Issue: #19189Closes: #27092
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.
