Merge topic 'improve-cps-docs'

551d4e399a Help: Improve CPS install documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !10828

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:
 

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>``
+    Version of the package.  The ``<version>`` shall conform to the specified
+    schema.  Refer to :ref:`Version Selection (CPS) <cps version selection>`
+    for more information on how the package version is used when consumers
+    request a package.
+
+  ``COMPAT_VERSION <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 <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) <cps version selection>` for the list of
+    schemas supported by :command:`find_package`.
+
+  ``DEFAULT_TARGETS <target>...``
+
+    Targets to be used if a consumer requests linking to the package name,
+    rather than to specific components.
+
+  ``DEFAULT_CONFIGURATIONS <config>...``
+
+    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``