From 551d4e399a012a07fc90f85f580132a9ae8c6cff Mon Sep 17 00:00:00 2001 From: Matthew Woehlke Date: Tue, 27 May 2025 12:28:05 -0400 Subject: [PATCH] Help: Improve CPS install documentation 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. --- Help/command/find_package.rst | 7 ++++++ Help/command/install.rst | 40 +++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+) diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 5d2e3262ab..9d309beac9 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -659,6 +659,8 @@ the ``EXACT`` option is given, only a version of the package claiming an exact match of the requested version may be found. CMake does not establish any convention for the meaning of version numbers. +.. _`cmake script version selection`: + CMake-script """""""""""" @@ -791,6 +793,8 @@ and the corresponding package configuration file is loaded. As a result, it is not possible to use a version range to extend the range of compatible package versions that will be accepted. +.. _`cps version selection`: + |CPS| """"" @@ -818,6 +822,9 @@ package's actual version is newer. If not specified, the ``compat_version`` is implicitly equal to the package version, i.e. no backwards compatibility is provided. +.. TODO Rework the preceding paragraph when COMPAT_VERSION has broader support + in CMake. + When a package uses a recognized schema, CMake will determine the package's acceptability according to the following rules: diff --git a/Help/command/install.rst b/Help/command/install.rst index 42765ad94b..5040e4497c 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -1019,6 +1019,43 @@ Signatures If ``DESTINATION`` is not specified, a platform-specific default is used. + Several options may be used to specify package metadata: + + ``VERSION `` + Version of the package. The ```` shall conform to the specified + schema. Refer to :ref:`Version Selection (CPS) ` + for more information on how the package version is used when consumers + request a package. + + ``COMPAT_VERSION `` + Oldest version for which the package provides compatibility. + + If not specified, ``COMPAT_VERSION`` is implicitly taken to equal the + package's ``VERSION``, which is to say that no backwards compatibility is + provided. + + ``VERSION_SCHEMA `` + The schema that the package's version number(s) (both ``VERSION`` and + ``COMPAT_VERSION``) follow. While no schema will be written to the + ``.cps`` file if this option is not provided, CPS specifies that the schema + is assumed to be ``simple`` in such cases. Refer to |cps-version_schema|_ + for more details and a list of officially supported schemas, but be aware + that the specification may include schemas that are not supported by CMake. + See :ref:`Version Selection (CPS) ` for the list of + schemas supported by :command:`find_package`. + + ``DEFAULT_TARGETS ...`` + + Targets to be used if a consumer requests linking to the package name, + rather than to specific components. + + ``DEFAULT_CONFIGURATIONS ...`` + + Ordered list of configurations consumers should prefer if no exact match or + mapping of the consumer's configuration to the package's available + configurations exists. If not specified, CMake will fall back to the + package's available configurations in an unspecified order. + If ``APPENDIX`` is specified, rather than generating a top level package specification, the specified targets will be exported as an appendix to the named package. Appendices may be used to separate less commonly used targets @@ -1229,3 +1266,6 @@ and by CPack. You can also invoke this script manually with .. _CPS: https://cps-org.github.io/cps/ .. |CPS| replace:: Common Package Specification + +.. _cps-version_schema: https://cps-org.github.io/cps/schema.html#version-schema +.. |cps-version_schema| replace:: ``version_schema``