1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
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` and
must not be an :ref:`ALIAS target <Alias Targets>`.
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
|
