[Cmake-commits] CMake branch, next, updated. v3.2.1-1433-gb887785
Brad King
brad.king at kitware.com
Fri Apr 3 10:53:53 EDT 2015
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".
The branch, next has been updated
via b887785b7a0c921ef59f1de451d2f26f343c33b1 (commit)
via 2e6ea309b38acc915aff0b6dec13c5eda1ad1739 (commit)
via 3af137824d993ca0a7c18c0768efb12b76154ad0 (commit)
via 227992c3a693bb56ee6f6600a10c6eb19c6fb311 (commit)
via 031d894fb882ca2e8c2269ba1674578f82155420 (commit)
via 6e331ce9d47c8f9adbf29ee0158b4307debbc02c (commit)
via ba9b9d79fb1a753c564be44e17e2d3b979f8108c (commit)
from 006f54976dc6aee8aee37730171b19724cac852a (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=b887785b7a0c921ef59f1de451d2f26f343c33b1
commit b887785b7a0c921ef59f1de451d2f26f343c33b1
Merge: 006f549 2e6ea309
Author: Brad King <brad.king at kitware.com>
AuthorDate: Fri Apr 3 10:53:52 2015 -0400
Commit: CMake Topic Stage <kwrobot at kitware.com>
CommitDate: Fri Apr 3 10:53:52 2015 -0400
Merge topic 'doc-target_link_libraries' into next
2e6ea309 Help: Revise target_link_libraries command documentation
3af13782 Help: Update discussion of relocable packages in cmake-packages(7)
227992c3 Help: Reorganize and refine discussion of relocatable packages
031d894f Help: Place relocatable package notes in their own subsections
6e331ce9 Help: Fix typo in cmake-packages(7) manual
ba9b9d79 Help: Fix syntax in non-relocatable usage requirements example
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=2e6ea309b38acc915aff0b6dec13c5eda1ad1739
commit 2e6ea309b38acc915aff0b6dec13c5eda1ad1739
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Apr 2 15:41:06 2015 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Fri Apr 3 10:52:36 2015 -0400
Help: Revise target_link_libraries command documentation
Organize the documentation into subsections to separate the signatures.
Refactor the discussion of allowed link items into bullet points and
expand into more detail on each.
diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst
index 88a555a..e0b1667 100644
--- a/Help/command/target_link_libraries.rst
+++ b/Help/command/target_link_libraries.rst
@@ -1,38 +1,102 @@
target_link_libraries
---------------------
-Link a target to given libraries.
+.. only:: html
+
+ .. contents::
+
+Specify libraries or flags to use when linking a given target and/or
+its dependents. :ref:`Usage requirements <Target Usage Requirements>`
+from linked library targets will be propagated. Usage requirements
+of a target's dependencies affect compilation of its own sources.
+
+Overview
+^^^^^^^^
+
+This command has several signatures as detailed in subsections below.
+All of them have the general form::
+
+ target_link_libraries(<target> ... <item>... ...)
+
+The named ``<target>`` must have been created in the current directory by
+a command such as :command:`add_executable` or :command:`add_library`.
+Repeated calls for the same ``<target>`` append items in the order called.
+Each ``<item>`` may be:
+
+* **A library target name**: The generated link line will have the
+ full path to the linkable library file associated with the target.
+ The buildsystem will have a dependency to re-link ``<target>`` if
+ the library file changes.
+
+ The named target must be created by :command:`add_library` within
+ the project or as an :ref:`IMPORTED library <Imported Targets>`.
+ If it is created within the project an ordering dependency will
+ automatically be added in the build system to make sure the named
+ library target is up-to-date before the ``<target>`` links.
+
+* **A full path to a library file**: The generated link line will
+ normally preserve the full path to the file. However, there are
+ some cases where CMake must ask the linker to search for the library
+ (e.g. ``-lfoo``), such as when it appears in a system library directory
+ that the compiler front-end may replace with an alternative.
+ Either way, the buildsystem will have a dependency to re-link
+ ``<target>`` if the library file changes.
+
+ If the library file is in a Mac OSX framework, the ``Headers`` directory
+ of the framework will also be processed as a
+ :ref:`usage requirement <Target Usage Requirements>`. This has the same
+ effect as passing the framework directory as an include directory.
+
+* **A plain library name**: The generated link line will ask the linker
+ to search for the library (e.g. ``-lfoo``).
+
+* **A link flag**: Item names starting with ``-``, but not ``-l`` or
+ ``-framework``, are treated as linker flags. Note that such flags will
+ be treated like any other library link item for purposes of transitive
+ dependencies, so they are generally safe to specify only as private link
+ items that will not propagate to dependents.
+
+* A ``debug``, ``optimized``, or ``general`` keyword immediately followed
+ by another ``<item>``. The item following such a keyword will be used
+ only for the corresponding build configuration. The ``debug`` keyword
+ corresponds to the ``Debug`` configuration (or to configurations named
+ in the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set).
+ The ``optimized`` keyword corresponds to all other configurations. The
+ ``general`` keyword corresponds to all configurations, and is purely
+ optional. Higher granularity may be achieved for per-configuration
+ rules by creating and linking to
+ :ref:`IMPORTED library targets <Imported Targets>`.
+
+Arguments to ``target_link_libraries`` may use "generator expressions"
+with the syntax ``$<...>``. Note however, that generator expressions
+will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`.
+See the :manual:`cmake-generator-expressions(7)` manual for available
+expressions. See the :manual:`cmake-buildsystem(7)` manual for more on
+defining buildsystem properties.
+
+Libraries for a Target and/or its Dependents
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+ target_link_libraries(<target>
+ <PRIVATE|PUBLIC|INTERFACE> <item>...
+ [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
+
+The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
+specify both the link dependencies and the link interface in one command.
+Libraries and targets following ``PUBLIC`` are linked to, and are made
+part of the link interface. Libraries and targets following ``PRIVATE``
+are linked to, but are not made part of the link interface. Libraries
+following ``INTERFACE`` are appended to the link interface and are not
+used for linking ``<target>``.
+
+Libraries for both a Target and its Dependents
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
- target_link_libraries(<target> [item1 [item2 [...]]]
- [[debug|optimized|general] <item>] ...)
-
-Specify libraries or flags to use when linking a given target. The
-named ``<target>`` must have been created in the current directory by a
-command such as :command:`add_executable` or :command:`add_library`. The
-remaining arguments specify library names or flags. Repeated calls for
-the same ``<target>`` append items in the order called.
-
-If a library name matches that of another target in the project a
-dependency will automatically be added in the build system to make sure
-the library being linked is up-to-date before the target links. Item names
-starting with ``-``, but not ``-l`` or ``-framework``, are treated as
-linker flags. Note that such flags will be treated like any other library
-link item for purposes of transitive dependencies, so they are generally
-safe to specify only as private link items that will not propagate to
-dependents of ``<target>``.
-
-A ``debug``, ``optimized``, or ``general`` keyword indicates that the
-library immediately following it is to be used only for the
-corresponding build configuration. The ``debug`` keyword corresponds to
-the Debug configuration (or to configurations named in the
-:prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). The
-``optimized`` keyword corresponds to all other configurations. The
-``general`` keyword corresponds to all configurations, and is purely
-optional (assumed if omitted). Higher granularity may be achieved for
-per-configuration rules by creating and linking to
-:ref:`IMPORTED library targets <Imported Targets>`.
+ target_link_libraries(<target> <item>...)
Library dependencies are transitive by default with this signature.
When this target is linked into another target then the libraries
@@ -45,37 +109,34 @@ by setting the property directly. When :policy:`CMP0022` is not set to
of this command may set the property making any libraries linked
exclusively by this signature private.
-CMake will also propagate :ref:`usage requirements <Target Usage Requirements>`
-from linked library targets. Usage requirements of dependencies affect
-compilation of sources in the ``<target>``.
-
-If an ``<item>`` is a library in a Mac OX framework, the ``Headers``
-directory of the framework will also be processed as a
-:ref:`usage requirement <Target Usage Requirements>`. This has the same
-effect as passing the framework directory as an include directory.
-
---------------------------------------------------------------------------
+Libraries for a Target and/or its Dependents (Legacy)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
target_link_libraries(<target>
- <PRIVATE|PUBLIC|INTERFACE> <lib> ...
- [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...])
+ <LINK_PRIVATE|LINK_PUBLIC> <lib>...
+ [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
-The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
-specify both the link dependencies and the link interface in one command.
-Libraries and targets following ``PUBLIC`` are linked to, and are made
-part of the link interface. Libraries and targets following ``PRIVATE``
-are linked to, but are not made part of the link interface. Libraries
-following ``INTERFACE`` are appended to the link interface and are not
-used for linking ``<target>``.
+The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
+the link dependencies and the link interface in one command.
---------------------------------------------------------------------------
+This signature is for compatibility only. Prefer the ``PUBLIC`` or
+``PRIVATE`` keywords instead.
+
+Libraries and targets following ``LINK_PUBLIC`` are linked to, and are
+made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy
+:policy:`CMP0022` is not ``NEW``, they are also made part of the
+:prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following
+``LINK_PRIVATE`` are linked to, but are not made part of the
+:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`).
+
+Libraries for Dependents Only (Legacy)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
- target_link_libraries(<target> LINK_INTERFACE_LIBRARIES
- [[debug|optimized|general] <lib>] ...)
+ target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the
:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them
@@ -99,28 +160,8 @@ is not ``NEW``, they are also appended to the
``general`` (or without any keyword) are treated as if specified for both
``debug`` and ``optimized``.
---------------------------------------------------------------------------
-
-::
-
- target_link_libraries(<target>
- <LINK_PRIVATE|LINK_PUBLIC>
- [[debug|optimized|general] <lib>] ...
- [<LINK_PRIVATE|LINK_PUBLIC>
- [[debug|optimized|general] <lib>] ...])
-
-The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
-the link dependencies and the link interface in one command.
-
-This signature is for compatibility only. Prefer the ``PUBLIC`` or
-``PRIVATE`` keywords instead.
-
-Libraries and targets following ``LINK_PUBLIC`` are linked to, and are
-made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy
-:policy:`CMP0022` is not ``NEW``, they are also made part of the
-:prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following
-``LINK_PRIVATE`` are linked to, but are not made part of the
-:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`).
+Cyclic Dependencies of Static Libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The library dependency graph is normally acyclic (a DAG), but in the case
of mutually-dependent ``STATIC`` libraries CMake allows the graph to
@@ -139,17 +180,11 @@ For example, the code
links ``main`` to ``A B A B``. While one repetition is usually
sufficient, pathological object file and symbol arrangements can require
-more. One may handle such cases by manually repeating the component in
-the last ``target_link_libraries`` call. However, if two archives are
-really so interdependent they should probably be combined into a single
-archive.
-
-Arguments to target_link_libraries may use "generator expressions"
-with the syntax ``$<...>``. Note however, that generator expressions
-will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`.
-See the :manual:`cmake-generator-expressions(7)` manual for available
-expressions. See the :manual:`cmake-buildsystem(7)` manual for more on
-defining buildsystem properties.
+more. One may handle such cases by using the
+:prop_tgt:`LINK_INTERFACE_MULTIPLICITY` target property or by manually
+repeating the component in the last ``target_link_libraries`` call.
+However, if two archives are really so interdependent they should probably
+be combined into a single archive, perhaps by using :ref:`Object Libraries`.
Creating Relocatable Packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=3af137824d993ca0a7c18c0768efb12b76154ad0
commit 3af137824d993ca0a7c18c0768efb12b76154ad0
Author: Brad King <brad.king at kitware.com>
AuthorDate: Fri Apr 3 09:57:05 2015 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Fri Apr 3 10:52:35 2015 -0400
Help: Update discussion of relocable packages in cmake-packages(7)
Explain at the beginning of the section the requirements for a package
to be relocatable to justify the rest of the section content.
Generalize example to use fictional package names instead of real ones,
especially because FindBoost provides no alternative yet. Reword the
discussion to represent the preferred approach as "ideal" but also
suggest workarounds when find modules do not provide the imported
targets.
diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst
index 28c0798..b9073a5 100644
--- a/Help/manual/cmake-packages.7.rst
+++ b/Help/manual/cmake-packages.7.rst
@@ -475,6 +475,10 @@ without installation. Consumers of the build tree can simply ensure that the
Creating Relocatable Packages
-----------------------------
+A relocatable package must not reference absolute paths of files on
+the machine where the package is built that will not exist on the
+machines where the package may be installed.
+
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
@@ -509,34 +513,56 @@ 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:
+For example, this code may not work well for a relocatable package:
.. code-block:: cmake
target_link_libraries(ClimbingStats INTERFACE
- ${Boost_LIBRARIES} ${OtherDep_LIBRARIES}
+ ${Foo_LIBRARIES} ${Bar_LIBRARIES}
)
target_include_directories(ClimbingStats INTERFACE
- "$<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>"
+ "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_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>`.
+The referenced variables may contain the absolute paths to libraries
+and include directories **as found on the machine the package was made on**.
+This would create a package with hard-coded paths to dependencies and not
+suitable for relocation.
+
+Ideally such dependencies should be used through their own
+:ref:`IMPORTED targets <Imported Targets>` that have their own
+:prop_tgt:`IMPORTED_LOCATION` and usage requirement properties
+such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated
+appropriately. Those imported targets may then be used with
+the :command:`target_link_libraries` command for ``ClimbingStats``:
+
+.. code-block:: cmake
+
+ target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar)
+
+With this approach the package references its external dependencies
+only through the names of :ref:`IMPORTED targets <Imported Targets>`.
+When a consumer uses the installed package, the consumer will run the
+appropriate :command:`find_package` commands (via the ``find_dependency``
+macro described above) to find the dependencies and populate the
+imported targets with appropriate paths on their own machine.
+
+Unfortunately many :manual:`modules <cmake-modules(7)>` shipped with
+CMake do not yet provide :ref:`IMPORTED targets <Imported Targets>`
+because their development pre-dated this approach. This may improve
+incrementally over time. Workarounds to create relocatable packages
+using such modules include:
+
+* When building the package, specify each ``Foo_LIBRARY`` cache
+ entry as just a library name, e.g. ``-DFoo_LIBRARY=foo``. This
+ tells the corresponding find module to populate the ``Foo_LIBRARIES``
+ with just ``foo`` to ask the linker to search for the library
+ instead of hard-coding a path.
+
+* Or, after installing the package content but before creating the
+ package installation binary for redistribution, manually replace
+ the absolute paths with placeholders for substitution by the
+ installation tool when the package is installed.
.. _`Package Registry`:
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=227992c3a693bb56ee6f6600a10c6eb19c6fb311
commit 227992c3a693bb56ee6f6600a10c6eb19c6fb311
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Apr 2 16:12:00 2015 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Fri Apr 3 10:52:24 2015 -0400
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.
diff --git a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
index 33f7183..a54d728 100644
--- a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
+++ b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
@@ -1,30 +1,18 @@
Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the
-|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies.
-That would hard-code into installed packages the include directory paths
-for dependencies **as found on the machine the package was made on**.
+|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
+directories of dependencies. That would hard-code into installed packages
+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
-suitable for specifying the required include directories of the target itself,
-not its dependencies.
+suitable for specifying the required include directories for headers
+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
-generate :manual:`cmake-packages(7)`:
-
-.. code-block:: cmake
-
- 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>`.
+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.
diff --git a/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt
index ceefa4d..46e84ac 100644
--- a/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt
+++ b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt
@@ -1,23 +1,10 @@
Note that it is not advisable to populate the
-|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies.
-That would hard-code into installed packages the include directory paths
+|INTERFACE_PROPERTY_LINK| of a target with absolute paths to dependencies.
+That would hard-code into installed packages the library file 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 :manual:`cmake-packages(7)`:
-
-.. code-block:: cmake
-
- 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>`.
+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.
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index 002f2c2..ae5e58e 100644
--- a/Help/manual/cmake-buildsystem.7.rst
+++ b/Help/manual/cmake-buildsystem.7.rst
@@ -143,6 +143,11 @@ use particular :prop_tgt:`COMPILE_OPTIONS` or
the properties must be **requirements**, not merely recommendations or
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
-----------------
diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst
index 6ee9df9..28c0798 100644
--- a/Help/manual/cmake-packages.7.rst
+++ b/Help/manual/cmake-packages.7.rst
@@ -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
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
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
@@ -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
that property.
+Creating a Package Configuration File
+-------------------------------------
+
In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as:
.. 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
``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:
.. 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``,
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
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=031d894fb882ca2e8c2269ba1674578f82155420
commit 031d894fb882ca2e8c2269ba1674578f82155420
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Apr 2 15:45:48 2015 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Fri Apr 3 10:52:22 2015 -0400
Help: Place relocatable package notes in their own subsections
These notes apply only for the use case of creating a package for
redistribution on machines other than that where it is built. Clarify
this to readers by placing the discussion in dedicated sections titled
accordingly.
diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst
index 1d236ce..30ec2cb 100644
--- a/Help/command/target_include_directories.rst
+++ b/Help/command/target_include_directories.rst
@@ -55,5 +55,8 @@ installation prefix. For example:
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
+Creating Relocatable Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst
index e6a82b6..88a555a 100644
--- a/Help/command/target_link_libraries.rst
+++ b/Help/command/target_link_libraries.rst
@@ -49,9 +49,6 @@ CMake will also propagate :ref:`usage requirements <Target Usage Requirements>`
from linked library targets. Usage requirements of dependencies affect
compilation of sources in the ``<target>``.
-.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES`
-.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt
-
If an ``<item>`` is a library in a Mac OX framework, the ``Headers``
directory of the framework will also be processed as a
:ref:`usage requirement <Target Usage Requirements>`. This has the same
@@ -153,3 +150,9 @@ will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`.
See the :manual:`cmake-generator-expressions(7)` manual for available
expressions. See the :manual:`cmake-buildsystem(7)` manual for more on
defining buildsystem properties.
+
+Creating Relocatable Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES`
+.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt
diff --git a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst
index 1cfd7a8..b1c40b2 100644
--- a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst
+++ b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst
@@ -22,5 +22,8 @@ installation prefix. For example:
$<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
)
+Creating Relocatable Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
.. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_INCLUDE_DIRECTORIES``
.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst
index 55b7b8d..832d12b 100644
--- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst
+++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst
@@ -17,5 +17,8 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
+Creating Relocatable Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
.. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_LINK_LIBRARIES``
.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt
diff --git a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst
index 2e859eb..2dcf45c 100644
--- a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst
+++ b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst
@@ -24,5 +24,8 @@ property if policy :policy:`CMP0022` is ``NEW``.
This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES`
instead.
+Creating Relocatable Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
.. |INTERFACE_PROPERTY_LINK| replace:: ``LINK_INTERFACE_LIBRARIES``
.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt
diff --git a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst
index 7f2b5dd..22ee5a6 100644
--- a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst
+++ b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst
@@ -13,5 +13,8 @@ property if policy :policy:`CMP0022` is ``NEW``.
This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES`
instead.
+Creating Relocatable Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
.. |INTERFACE_PROPERTY_LINK| replace:: ``LINK_INTERFACE_LIBRARIES_<CONFIG>``
.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=6e331ce9d47c8f9adbf29ee0158b4307debbc02c
commit 6e331ce9d47c8f9adbf29ee0158b4307debbc02c
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Apr 2 17:17:36 2015 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Fri Apr 3 10:52:21 2015 -0400
Help: Fix typo in cmake-packages(7) manual
relevnt => relevant
diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst
index b477cab..6ee9df9 100644
--- a/Help/manual/cmake-packages.7.rst
+++ b/Help/manual/cmake-packages.7.rst
@@ -375,7 +375,7 @@ 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 relevnt to dependencies.
+: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**.
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=ba9b9d79fb1a753c564be44e17e2d3b979f8108c
commit ba9b9d79fb1a753c564be44e17e2d3b979f8108c
Author: Brad King <brad.king at kitware.com>
AuthorDate: Thu Apr 2 16:16:14 2015 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Fri Apr 3 10:52:16 2015 -0400
Help: Fix syntax in non-relocatable usage requirements example
The example in cmake-packages(7) is meant to be incorrect for use of
absolute paths, not for its syntax.
diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst
index 3367ba4..b477cab 100644
--- a/Help/manual/cmake-packages.7.rst
+++ b/Help/manual/cmake-packages.7.rst
@@ -385,11 +385,11 @@ generate config file packages:
.. code-block:: cmake
target_link_libraries(ClimbingStats INTERFACE
- ${Boost_LIBRARIES};${OtherDep_LIBRARIES}>
- )
+ ${Boost_LIBRARIES} ${OtherDep_LIBRARIES}
+ )
target_include_directories(ClimbingStats INTERFACE
- $<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>
- )
+ "$<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
-----------------------------------------------------------------------
Summary of changes:
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list