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.
This commit is contained in:
Brad King 2015-04-02 15:41:06 -04:00
parent 3af137824d
commit 659896d3ed
1 changed files with 121 additions and 81 deletions

View File

@ -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> [item1 [item2 [...]]]
[[debug|optimized|general] <item>] ...)
target_link_libraries(<target>
<PRIVATE|PUBLIC|INTERFACE> <item>...
[<PRIVATE|PUBLIC|INTERFACE> <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.
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>``.
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>``.
Libraries for both a Target and its Dependents
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^