summaryrefslogtreecommitdiffstats
path: root/Help
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2015-04-06 12:58:19 (GMT)
committerCMake Topic Stage <kwrobot@kitware.com>2015-04-06 12:58:19 (GMT)
commit89ee57f6c79858bf350a5afce2ef588348dacb1c (patch)
tree8f43659a39cb4c9ff11b7edecd0797ae20e3cb09 /Help
parentb9c1eb4dcc801ea0a8f3f33aec58c5f9ab04026e (diff)
parent659896d3ed21bc7da1cf394c17e1a60e4d4ee5f7 (diff)
downloadCMake-89ee57f6c79858bf350a5afce2ef588348dacb1c.zip
CMake-89ee57f6c79858bf350a5afce2ef588348dacb1c.tar.gz
CMake-89ee57f6c79858bf350a5afce2ef588348dacb1c.tar.bz2
Merge topic 'doc-target_link_libraries'
659896d3 Help: Revise target_link_libraries command documentation
Diffstat (limited to 'Help')
-rw-r--r--Help/command/target_link_libraries.rst208
1 files changed, 124 insertions, 84 deletions
diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst
index 88a555a..393c8b4 100644
--- a/Help/command/target_link_libraries.rst
+++ b/Help/command/target_link_libraries.rst
@@ -1,38 +1,107 @@
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. ``/usr/lib/libfoo.so`` becomes ``-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. ``foo`` becomes ``-lfoo`` or ``foo.lib``).
+
+* **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>`.
+
+Items containing ``::``, such as ``Foo::Bar``, are assumed to be
+:ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library
+target names and will cause an error if no such target exists.
+See policy :policy:`CMP0028`.
+
+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 +114,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 +165,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 +185,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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^