mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-06 05:40:54 -06:00
34343922a5
Add the ability to generate CPS package information when install(EXPORT) is used. This relies on additional information to be passed to CMake, and is intended as a way of getting CPS out of existing projects without needing to make changes to the projects' CMakeLists.txt. (Particularly, this feature is intended for package distributors, not project authors.)
123 lines
5.0 KiB
ReStructuredText
123 lines
5.0 KiB
ReStructuredText
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
|