Merge topic 'doc-target_link_libraries'
659896d3 Help: Revise target_link_libraries command documentationThis commit is contained in:
Brad King
CMake Topic Stage
commit
89ee57f6c7
|
|
@ -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
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
|
|
|||
Loading…
Reference in New Issue