kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Help: Reorganize and refine discussion of relocatable packages 

Re-organize the content added to the cmake-packages(7) manual by

* commit v3.0.0-rc1~184^2 (Help: Document export(EXPORT) in the
  cmake-packages manual, 2013-12-23),

* commit v3.0.0-rc1~154^2~1 (Help: Add notes about relocatability
  of config-file packages, 2014-01-07), and

* commit v3.2.0-rc1~345^2 (Help: Warn that paths should not be used
  in INTERFACE_ build properties, 2014-11-22).

These commits broke the natural flow of the original manual and made
wording after the new content make less sense.  Move the content into
new subsections to restore the flow of the original manual and to
make explicitly the purpose of the new content.

Shorten the relocatable usage requirement "warnings".  Refer to the
new cmake-packages(7) manual subsection to reduce duplication.  Also
clarify the distinction between paths to library dependencies and
paths to their header files.
This commit is contained in:
Brad King 2015-04-02 16:12:00 -04:00
parent 031d894fb8
commit 227992c3a6
4 changed files with 106 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
View File

@ -1,30 +1,18 @@
Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the
|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies. |INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
That would hard-code into installed packages the include directory paths directories of dependencies. That would hard-code into installed packages
for dependencies **as found on the machine the package was made on**. the include directory paths for dependencies
**as found on the machine the package was made on**.
The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only
suitable for specifying the required include directories of the target itself, suitable for specifying the required include directories for headers
not its dependencies. provided with the target itself, not those provided by the transitive
dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target
property. Those dependencies should themselves be targets that specify
their own header locations in |INTERFACE_PROPERTY_LINK|.
That is, code like this is incorrect for targets which will be used to See the :ref:`Creating Relocatable Packages` section of the
generate :manual:`cmake-packages(7)`: :manual:`cmake-packages(7)` manual for discussion of additional care
that must be taken when specifying usage requirements while creating
.. code-block:: cmake packages for redistribution.
target_include_directories(mylib INTERFACE
$<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>
)
Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
which have their own |INTERFACE_PROPERTY_LINK| populated
appropriately. Those :ref:`IMPORTED targets <Imported Targets>` may then be
used with the :command:`target_link_libraries` command for ``mylib``.
That way, when a consumer uses the installed package, the
consumer will run the appropriate :command:`find_package` command to find
the dependencies on their own machine and populate the
:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. See
:ref:`Creating Packages` for more. Note that many modules currently shipped
with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`.

25
Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt
View File

@ -1,23 +1,10 @@
Note that it is not advisable to populate the Note that it is not advisable to populate the
|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies. |INTERFACE_PROPERTY_LINK| of a target with absolute paths to dependencies.
That would hard-code into installed packages the include directory paths That would hard-code into installed packages the library file paths
for dependencies **as found on the machine the package was made on**. for dependencies **as found on the machine the package was made on**.
That is, code like this is incorrect for targets which will be used to See the :ref:`Creating Relocatable Packages` section of the
generate :manual:`cmake-packages(7)`: :manual:`cmake-packages(7)` manual for discussion of additional care
that must be taken when specifying usage requirements while creating
.. code-block:: cmake packages for redistribution.
target_link_libraries(mylib INTERFACE
${Boost_LIBRARIES};${OtherDep_LIBRARIES}
)
Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
which have their own :prop_tgt:`IMPORTED_LOCATION` populated
appropriately. That way, when a consumer uses the installed package, the
consumer will run the appropriate :command:`find_package` command to find
the dependencies on their own machine and populate the
:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. See
:ref:`Creating Packages` for more. Note that many modules currently shipped
with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`.

5
Help/manual/cmake-buildsystem.7.rst
View File

@ -143,6 +143,11 @@ use particular :prop_tgt:`COMPILE_OPTIONS` or
the properties must be **requirements**, not merely recommendations or the properties must be **requirements**, not merely recommendations or
convenience. convenience.
See the :ref:`Creating Relocatable Packages` section of the
:manual:`cmake-packages(7)` manual for discussion of additional care
that must be taken when specifying usage requirements while creating
packages for redistribution.
Target Properties Target Properties
----------------- -----------------

152
Help/manual/cmake-packages.7.rst
View File

@ -373,38 +373,6 @@ attempt to use version 3 together with version 4. Packages can choose to
employ such a pattern if different major versions of the package are designed employ such a pattern if different major versions of the package are designed
to be incompatible. to be incompatible.
Note that it is not advisable to populate any properties which may contain
paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies.
That would hard-code into installed packages the include directory or library
paths for dependencies **as found on the machine the package was made on**.
That is, code like this is incorrect for targets which will be used to
generate config file packages:
.. code-block:: cmake
target_link_libraries(ClimbingStats INTERFACE
${Boost_LIBRARIES} ${OtherDep_LIBRARIES}
)
target_include_directories(ClimbingStats INTERFACE
"$<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>"
)
Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
:prop_tgt:`IMPORTED_LOCATION` populated appropriately. Those
:ref:`IMPORTED targets <Imported Targets>` may then be
used with the :command:`target_link_libraries` command for ``ClimbingStats``.
That way, when a consumer uses the installed package, the
consumer will run the appropriate :command:`find_package` command (via the
find_dependency macro described below) to find
the dependencies on their own machine and populate the
:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. Note that
many modules currently shipped with CMake do not currently provide
:ref:`IMPORTED targets <Imported Targets>`.
A ``NAMESPACE`` with double-colons is specified when exporting the targets A ``NAMESPACE`` with double-colons is specified when exporting the targets
for installation. This convention of double-colons gives CMake a hint that for installation. This convention of double-colons gives CMake a hint that
the name is an :prop_tgt:`IMPORTED` target when it is used by downstreams the name is an :prop_tgt:`IMPORTED` target when it is used by downstreams
@ -418,6 +386,9 @@ directory in the :variable:`CMAKE_INSTALL_PREFIX`. When the ``IMPORTED``
target is used by downsteam, it automatically consumes the entries from target is used by downsteam, it automatically consumes the entries from
that property. that property.
Creating a Package Configuration File
-------------------------------------
In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as: In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as:
.. code-block:: cmake .. code-block:: cmake
@ -429,44 +400,6 @@ should be provided by the ``ClimbingStats`` package, they should
be in a separate file which is installed to the same location as the be in a separate file which is installed to the same location as the
``ClimbingStatsConfig.cmake`` file, and included from there. ``ClimbingStatsConfig.cmake`` file, and included from there.
Packages created by :command:`install(EXPORT)` are designed to be relocatable,
using paths relative to the location of the package itself. When defining
the interface of a target for ``EXPORT``, keep in mind that the include
directories should be specified as relative paths which are relative to the
:variable:`CMAKE_INSTALL_PREFIX`:
.. code-block:: cmake
target_include_directories(tgt INTERFACE
# Wrong, not relocatable:
$<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
)
target_include_directories(tgt INTERFACE
# Ok, relocatable:
$<INSTALL_INTERFACE:include/TgtName>
)
The ``$<INSTALL_PREFIX>``
:manual:`generator expression <cmake-generator-expressions(7)>` may be used as
a placeholder for the install prefix without resulting in a non-relocatable
package. This is necessary if complex generator expressions are used:
.. code-block:: cmake
target_include_directories(tgt INTERFACE
# Ok, relocatable:
$<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
)
The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets
definition file which is specific to the build-tree, and is not relocatable.
This can similiarly be used with a suitable package configuration file and
package version file to define a package for the build tree which may be used
without installation. Consumers of the build tree can simply ensure that the
:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the
``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache.
This can also be extended to cover dependencies: This can also be extended to cover dependencies:
.. code-block:: cmake .. code-block:: cmake
@ -526,6 +459,85 @@ could not be found because an invalid component was specified. This message
variable can be set for any case where the ``_FOUND`` variable is set to ``False``, variable can be set for any case where the ``_FOUND`` variable is set to ``False``,
and will be displayed to the user. and will be displayed to the user.
Creating a Package Configuration File for the Build Tree
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets
definition file which is specific to the build-tree, and is not relocatable.
This can similiarly be used with a suitable package configuration file and
package version file to define a package for the build tree which may be used
without installation. Consumers of the build tree can simply ensure that the
:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the
``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache.
.. _`Creating Relocatable Packages`:
Creating Relocatable Packages
-----------------------------
Packages created by :command:`install(EXPORT)` are designed to be relocatable,
using paths relative to the location of the package itself. When defining
the interface of a target for ``EXPORT``, keep in mind that the include
directories should be specified as relative paths which are relative to the
:variable:`CMAKE_INSTALL_PREFIX`:
.. code-block:: cmake
target_include_directories(tgt INTERFACE
# Wrong, not relocatable:
$<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
)
target_include_directories(tgt INTERFACE
# Ok, relocatable:
$<INSTALL_INTERFACE:include/TgtName>
)
The ``$<INSTALL_PREFIX>``
:manual:`generator expression <cmake-generator-expressions(7)>` may be used as
a placeholder for the install prefix without resulting in a non-relocatable
package. This is necessary if complex generator expressions are used:
.. code-block:: cmake
target_include_directories(tgt INTERFACE
# Ok, relocatable:
$<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
)
This also applies to paths referencing external dependencies.
It is not advisable to populate any properties which may contain
paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies.
That would hard-code into installed packages the include directory or library
paths for dependencies **as found on the machine the package was made on**.
That is, code like this is incorrect for targets which will be used to
generate config file packages:
.. code-block:: cmake
target_link_libraries(ClimbingStats INTERFACE
${Boost_LIBRARIES} ${OtherDep_LIBRARIES}
)
target_include_directories(ClimbingStats INTERFACE
"$<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>"
)
Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
:prop_tgt:`IMPORTED_LOCATION` populated appropriately. Those
:ref:`IMPORTED targets <Imported Targets>` may then be
used with the :command:`target_link_libraries` command for ``ClimbingStats``.
That way, when a consumer uses the installed package, the
consumer will run the appropriate :command:`find_package` command (via the
find_dependency macro described below) to find
the dependencies on their own machine and populate the
:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. Note that
many modules currently shipped with CMake do not currently provide
:ref:`IMPORTED targets <Imported Targets>`.
.. _`Package Registry`: .. _`Package Registry`:
Package Registry Package Registry