mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-05-01 03:29:18 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'package-info-from-install-export'

Browse Source 
34343922a5 install: Add ability to generate CPS from install(EXPORT)

Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Merge-request: !11315
This commit is contained in:
Brad King
2025-11-12 16:52:42 +00:00
committed by Kitware Robot
parent 64ffd3b323 34343922a5
commit 515bb02443
29 changed files with 517 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Help/command/install.rst
+15 -1
View File
@@ -979,7 +979,7 @@ Signatures
Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO``.
Installs a |CPS|_ file exporting targets for dependent projects:
Installs a |CPS|_ ("CPS") file exporting targets for dependent projects:
.. code-block:: cmake
@@ -1105,6 +1105,20 @@ Signatures
use of ``LOWER_CASE_FILE`` should be consistent between the main package and
any appendices.
.. note::
Because it is intended to be portable across multiple build tools, CPS
may not support all features that are allowed in CMake-script exports. In
particular, support for generator expressions in interface properties is
limited at this time to configuration-dependent expressions.
.. note::
This is the recommended way to generate |CPS| package information for a
project. For distributors whose users may require CPS package information
when making changes to the project's build files is not practical, the
:variable:`CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO` variable may be used to
generate ``.cps`` files from :command:`install(EXPORT)` calls. Refer to
the variable's documentation for usage and caveats.
.. signature::
install(RUNTIME_DEPENDENCY_SET <set-name> [...])
Help/manual/cmake-variables.7.rst
+1
View File
@@ -263,6 +263,7 @@ Variables that Change Behavior
/variable/CMAKE_INCLUDE_PATH
/variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
/variable/CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO
/variable/CMAKE_INSTALL_MESSAGE
/variable/CMAKE_INSTALL_PREFIX
/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
Help/variable/CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO.rst
+122
View File
@@ -0,0 +1,122 @@
CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO
-------------------------------------
.. versionadded:: 4.3
.. note::
This variable is meaningful only when experimental support has been enabled
by the ``CMAKE_EXPERIMENTAL_FIXME`` gate.
A list of directives instructing CMake to install |CPS| package information
when exported target information is installed via :command:`install(EXPORT)`.
The value is treated as a list, with each directive having the form
``<export-name>:<package-name>[/[l][a<appendix-name>][/<destination>]]``.
Slashes are used to separate different components of the directive.
Note that this feature is intended for package distributors, and should
**only** be used when editing a project's CMake script is not feasible.
Developers should use :command:`install(PACKAGE_INFO)` directly.
Additionally, because ``CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO`` functions by
emulating a call to :command:`install(PACKAGE_INFO)`, using it with a project
that is already calling :command:`install(PACKAGE_INFO)` directly may result
in conflicting installation directives, which will usually cause the project's
configure step to fail.
The meaning of the values is as follows:
``<export-name>``
Name of the export for which package information should be installed.
``<package-name>``
Name of the package for which to generate package information. This is also
the name that users would use in a :command:`find_package` call.
``l``
Optional. Specifies that the name of the package information file on disk
should be lower case. See the ``LOWER_CASE_FILE`` option of
:command:`install(PACKAGE_INFO)`.
``a<appendix-name>``
Optional. Specifies that an appendix ``<appendix-name>`` should be created
rather than a root package description. See the ``APPENDIX`` option of
:command:`install(PACKAGE_INFO)`. Note that additional information
(see below) cannot be added to appendices.
``<destination>``
Optional. Specifies the destination to which the package information file
should be installed. See the ``DESTINATION`` option of
:command:`install(PACKAGE_INFO)`. Note that the default is a
platform-specific location that is appropriate for |CPS| files in most
instances, *not* the ``DESTINATION`` of the :command:`install(EXPORT)`
which the directive matched.
For non-appendices, CMake will also infer additional information from several
CMake variables of the form ``<export-name>_EXPORT_PACKAGE_INFO_<var>``. The
values of these are first processed as if by :command:`string(CONFIGURE)` with
the ``@ONLY`` option. These are optional, and their effect is equivalent to
passing their value to the ``<var>`` option of the
:command:`install(PACKAGE_INFO)` command.
The additional variables are:
* ``<export-name>_EXPORT_PACKAGE_INFO_VERSION``
* ``<export-name>_EXPORT_PACKAGE_INFO_COMPAT_VERSION``
* ``<export-name>_EXPORT_PACKAGE_INFO_VERSION_SCHEMA``
* ``<export-name>_EXPORT_PACKAGE_INFO_LICENSE``
* ``<export-name>_EXPORT_PACKAGE_INFO_DEFAULT_LICENSE``
* ``<export-name>_EXPORT_PACKAGE_INFO_DEFAULT_CONFIGURATIONS``
Ideally, the version should be set to ``@PROJECT_VERSION@``. However,
some projects may not use the ``VERSION`` option of the :command:`project`
command.
Example
^^^^^^^
Consider the following (simplified) project:
.. code-block:: cmake
project(Example VERSION 1.2.3 SPDX_LICENSE "BSD-3-Clause")
add_library(foo ...)
add_library(bar ...)
install(TARGETS foo EXPORT required-targets)
install(TARGETS bar EXPORT optional-targets)
install(EXPORT required-targets FILE example-targets.cmake ...)
install(EXPORT optional-targets FILE example-optional-targets.cmake ...)
In this example, let ``example-targets.cmake`` be a file which is always
installed, and ``example-optional-targets.cmake`` be a file which is
optionally installed (e.g. is distributed as part of a separate package which
depends on the 'base' package).
Now, imagine we are a distributor that wants to make |CPS| package information
files available to our users, but we do not want to modify the project's build
files. We can do this by passing the following arguments to CMake:
.. code-block::
-DCMAKE_EXPERIMENTAL_FIXME=<elided>
-DCMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO=\
required-targets:Example/l;\
optional-targets:Example/laoptional
-Drequired-targets_EXPORT_PACKAGE_INFO_VERSION=@Example_VERSION@
-Drequired-targets_EXPORT_PACKAGE_INFO_LICENSE=@Example_SPDX_LICENSE@
(Whitespace and line continuation characters, added for readability, should
be removed in real usage. Arguments may need to be quoted to prevent being
reinterpreted by the command shell.)
This will cause CMake to also create and install the files ``example.cps`` and
``example-optional.cps`` which describe the ``Example`` package. We could
also specify the version and license information using substitutions provided
by the package build system (e.g. rpm, dpkg) if the project does not provide
this information via the :command:`project` command.
.. _CPS: https://cps-org.github.io/cps/
.. |CPS| replace:: Common Package Specification