target_link_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. | |
If an imported library has the :prop_tgt:`IMPORTED_NO_SONAME` | |
target property set, CMake may ask the linker to search for | |
the library instead of using the full path | |
(e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``). | |
* **A full path to a library file**: The generated link line will | |
normally preserve the full path to the file. The buildsystem will | |
have a dependency to re-link ``<target>`` if the library file changes. | |
There are some cases where CMake may ask the linker to search for | |
the library (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such | |
as when a shared library is detected to have no ``SONAME`` field. | |
See policy :policy:`CMP0060` for discussion of another case. | |
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. | |
On :ref:`Visual Studio Generators` for VS 2010 and above, library files | |
ending in ``.targets`` will be treated as MSBuild targets files and | |
imported into generated project files. This is not supported by other | |
generators. | |
* **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. | |
Link flags specified here are inserted into the link command in the same | |
place as the link libraries. This might not be correct, depending on | |
the linker. Use the :prop_tgt:`LINK_FLAGS` target property to add link | |
flags explicitly. The flags will then be placed at the toolchain-defined | |
flag position in the link command. | |
* 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> <item>...) | |
Library dependencies are transitive by default with this signature. | |
When this target is linked into another target then the libraries | |
linked to this target will appear on the link line for the other | |
target too. This transitive "link interface" is stored in the | |
:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property and may be overridden | |
by setting the property directly. When :policy:`CMP0022` is not set to | |
``NEW``, transitive linking is built in but may be overridden by the | |
:prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Calls to other signatures | |
of this command may set the property making any libraries linked | |
exclusively by this signature private. | |
Libraries for a Target and/or its Dependents (Legacy) | |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
:: | |
target_link_libraries(<target> | |
<LINK_PRIVATE|LINK_PUBLIC> <lib>... | |
[<LINK_PRIVATE|LINK_PUBLIC> <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`). | |
Libraries for Dependents Only (Legacy) | |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
:: | |
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 | |
for linking. If policy :policy:`CMP0022` is not ``NEW``, then this mode | |
also appends libraries to the :prop_tgt:`LINK_INTERFACE_LIBRARIES` and its | |
per-configuration equivalent. | |
This signature is for compatibility only. Prefer the ``INTERFACE`` mode | |
instead. | |
Libraries specified as ``debug`` are wrapped in a generator expression to | |
correspond to debug builds. If policy :policy:`CMP0022` is | |
not ``NEW``, the libraries are also appended to the | |
:prop_tgt:`LINK_INTERFACE_LIBRARIES_DEBUG <LINK_INTERFACE_LIBRARIES_<CONFIG>>` | |
property (or to the properties corresponding to configurations listed in | |
the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). | |
Libraries specified as ``optimized`` are appended to the | |
:prop_tgt:`INTERFACE_LINK_LIBRARIES` property. If policy :policy:`CMP0022` | |
is not ``NEW``, they are also appended to the | |
:prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Libraries specified as | |
``general`` (or without any keyword) are treated as if specified for both | |
``debug`` and ``optimized``. | |
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 | |
contain cycles (strongly connected components). When another target links | |
to one of the libraries, CMake repeats the entire connected component. | |
For example, the code | |
.. code-block:: cmake | |
add_library(A STATIC a.c) | |
add_library(B STATIC b.c) | |
target_link_libraries(A B) | |
target_link_libraries(B A) | |
add_executable(main main.c) | |
target_link_libraries(main A) | |
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 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 | |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` | |
.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt |