8 Specify libraries or flags to use when linking a given target and/or
9 its dependents. :ref:`Usage requirements <Target Usage Requirements>`
10 from linked library targets will be propagated. Usage requirements
11 of a target's dependencies affect compilation of its own sources.
16 This command has several signatures as detailed in subsections below.
17 All of them have the general form
21 target_link_libraries(<target> ... <item>... ...)
23 The named ``<target>`` must have been created by a command such as
24 :command:`add_executable` or :command:`add_library` and must not be an
25 :ref:`ALIAS target <Alias Targets>`. If policy :policy:`CMP0079` is not
26 set to ``NEW`` then the target must have been created in the current
27 directory. Repeated calls for the same ``<target>`` append items in
30 .. versionadded:: 3.13
31 The ``<target>`` doesn't have to be defined in the same directory as the
32 ``target_link_libraries`` call.
34 Each ``<item>`` may be:
36 * **A library target name**: The generated link line will have the
37 full path to the linkable library file associated with the target.
38 The buildsystem will have a dependency to re-link ``<target>`` if
39 the library file changes.
41 The named target must be created by :command:`add_library` within
42 the project or as an :ref:`IMPORTED library <Imported Targets>`.
43 If it is created within the project an ordering dependency will
44 automatically be added in the build system to make sure the named
45 library target is up-to-date before the ``<target>`` links.
47 If an imported library has the :prop_tgt:`IMPORTED_NO_SONAME`
48 target property set, CMake may ask the linker to search for
49 the library instead of using the full path
50 (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``).
52 The full path to the target's artifact will be quoted/escaped for
53 the shell automatically.
55 * **A full path to a library file**: The generated link line will
56 normally preserve the full path to the file. The buildsystem will
57 have a dependency to re-link ``<target>`` if the library file changes.
59 There are some cases where CMake may ask the linker to search for
60 the library (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such
61 as when a shared library is detected to have no ``SONAME`` field.
62 See policy :policy:`CMP0060` for discussion of another case.
64 If the library file is in a macOS framework, the ``Headers`` directory
65 of the framework will also be processed as a
66 :ref:`usage requirement <Target Usage Requirements>`. This has the same
67 effect as passing the framework directory as an include directory.
70 On :ref:`Visual Studio Generators` for VS 2010 and above, library files
71 ending in ``.targets`` will be treated as MSBuild targets files and
72 imported into generated project files. This is not supported by other
75 The full path to the library file will be quoted/escaped for
76 the shell automatically.
78 * **A plain library name**: The generated link line will ask the linker
79 to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``).
81 The library name/flag is treated as a command-line string fragment and
82 will be used with no extra quoting or escaping.
84 * **A link flag**: Item names starting with ``-``, but not ``-l`` or
85 ``-framework``, are treated as linker flags. Note that such flags will
86 be treated like any other library link item for purposes of transitive
87 dependencies, so they are generally safe to specify only as private link
88 items that will not propagate to dependents.
90 Link flags specified here are inserted into the link command in the same
91 place as the link libraries. This might not be correct, depending on
92 the linker. Use the :prop_tgt:`LINK_OPTIONS` target property or
93 :command:`target_link_options` command to add link
94 flags explicitly. The flags will then be placed at the toolchain-defined
95 flag position in the link command.
97 .. versionadded:: 3.13
98 :prop_tgt:`LINK_OPTIONS` target property and :command:`target_link_options`
99 command. For earlier versions of CMake, use :prop_tgt:`LINK_FLAGS`
102 The link flag is treated as a command-line string fragment and
103 will be used with no extra quoting or escaping.
105 * **A generator expression**: A ``$<...>`` :manual:`generator expression
106 <cmake-generator-expressions(7)>` may evaluate to any of the above
107 items or to a :ref:`semicolon-separated list <CMake Language Lists>` of them.
108 If the ``...`` contains any ``;`` characters, e.g. after evaluation
109 of a ``${list}`` variable, be sure to use an explicitly quoted
110 argument ``"$<...>"`` so that this command receives it as a
113 Additionally, a generator expression may be used as a fragment of
114 any of the above items, e.g. ``foo$<1:_d>``.
116 Note that generator expressions will not be used in OLD handling of
117 policy :policy:`CMP0003` or policy :policy:`CMP0004`.
119 * A ``debug``, ``optimized``, or ``general`` keyword immediately followed
120 by another ``<item>``. The item following such a keyword will be used
121 only for the corresponding build configuration. The ``debug`` keyword
122 corresponds to the ``Debug`` configuration (or to configurations named
123 in the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set).
124 The ``optimized`` keyword corresponds to all other configurations. The
125 ``general`` keyword corresponds to all configurations, and is purely
126 optional. Higher granularity may be achieved for per-configuration
127 rules by creating and linking to
128 :ref:`IMPORTED library targets <Imported Targets>`.
129 These keywords are interpreted immediately by this command and therefore
130 have no special meaning when produced by a generator expression.
132 Items containing ``::``, such as ``Foo::Bar``, are assumed to be
133 :ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library
134 target names and will cause an error if no such target exists.
135 See policy :policy:`CMP0028`.
137 See the :manual:`cmake-buildsystem(7)` manual for more on defining
138 buildsystem properties.
140 Libraries for a Target and/or its Dependents
141 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
143 .. code-block:: cmake
145 target_link_libraries(<target>
146 <PRIVATE|PUBLIC|INTERFACE> <item>...
147 [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
149 The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
150 specify both the link dependencies and the link interface in one command.
151 Libraries and targets following ``PUBLIC`` are linked to, and are made
152 part of the link interface. Libraries and targets following ``PRIVATE``
153 are linked to, but are not made part of the link interface. Libraries
154 following ``INTERFACE`` are appended to the link interface and are not
155 used for linking ``<target>``.
157 Libraries for both a Target and its Dependents
158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
160 .. code-block:: cmake
162 target_link_libraries(<target> <item>...)
164 Library dependencies are transitive by default with this signature.
165 When this target is linked into another target then the libraries
166 linked to this target will appear on the link line for the other
167 target too. This transitive "link interface" is stored in the
168 :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property and may be overridden
169 by setting the property directly. When :policy:`CMP0022` is not set to
170 ``NEW``, transitive linking is built in but may be overridden by the
171 :prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Calls to other signatures
172 of this command may set the property making any libraries linked
173 exclusively by this signature private.
175 Libraries for a Target and/or its Dependents (Legacy)
176 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
178 .. code-block:: cmake
180 target_link_libraries(<target>
181 <LINK_PRIVATE|LINK_PUBLIC> <lib>...
182 [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
184 The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
185 the link dependencies and the link interface in one command.
187 This signature is for compatibility only. Prefer the ``PUBLIC`` or
188 ``PRIVATE`` keywords instead.
190 Libraries and targets following ``LINK_PUBLIC`` are linked to, and are
191 made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy
192 :policy:`CMP0022` is not ``NEW``, they are also made part of the
193 :prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following
194 ``LINK_PRIVATE`` are linked to, but are not made part of the
195 :prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`).
197 Libraries for Dependents Only (Legacy)
198 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
200 .. code-block:: cmake
202 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
204 The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the
205 :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them
206 for linking. If policy :policy:`CMP0022` is not ``NEW``, then this mode
207 also appends libraries to the :prop_tgt:`LINK_INTERFACE_LIBRARIES` and its
208 per-configuration equivalent.
210 This signature is for compatibility only. Prefer the ``INTERFACE`` mode
213 Libraries specified as ``debug`` are wrapped in a generator expression to
214 correspond to debug builds. If policy :policy:`CMP0022` is
215 not ``NEW``, the libraries are also appended to the
216 :prop_tgt:`LINK_INTERFACE_LIBRARIES_DEBUG <LINK_INTERFACE_LIBRARIES_<CONFIG>>`
217 property (or to the properties corresponding to configurations listed in
218 the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set).
219 Libraries specified as ``optimized`` are appended to the
220 :prop_tgt:`INTERFACE_LINK_LIBRARIES` property. If policy :policy:`CMP0022`
221 is not ``NEW``, they are also appended to the
222 :prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Libraries specified as
223 ``general`` (or without any keyword) are treated as if specified for both
224 ``debug`` and ``optimized``.
226 Linking Object Libraries
227 ^^^^^^^^^^^^^^^^^^^^^^^^
229 .. versionadded:: 3.12
231 :ref:`Object Libraries` may be used as the ``<target>`` (first) argument
232 of ``target_link_libraries`` to specify dependencies of their sources
233 on other libraries. For example, the code
235 .. code-block:: cmake
237 add_library(A SHARED a.c)
238 target_compile_definitions(A PUBLIC A)
240 add_library(obj OBJECT obj.c)
241 target_compile_definitions(obj PUBLIC OBJ)
242 target_link_libraries(obj PUBLIC A)
244 compiles ``obj.c`` with ``-DA -DOBJ`` and establishes usage requirements
245 for ``obj`` that propagate to its dependents.
247 Normal libraries and executables may link to :ref:`Object Libraries`
248 to get their objects and usage requirements. Continuing the above
251 .. code-block:: cmake
253 add_library(B SHARED b.c)
254 target_link_libraries(B PUBLIC obj)
256 compiles ``b.c`` with ``-DA -DOBJ``, creates shared library ``B``
257 with object files from ``b.c`` and ``obj.c``, and links ``B`` to ``A``.
258 Furthermore, the code
260 .. code-block:: cmake
262 add_executable(main main.c)
263 target_link_libraries(main B)
265 compiles ``main.c`` with ``-DA -DOBJ`` and links executable ``main``
266 to ``B`` and ``A``. The object library's usage requirements are
267 propagated transitively through ``B``, but its object files are not.
269 :ref:`Object Libraries` may "link" to other object libraries to get
270 usage requirements, but since they do not have a link step nothing
271 is done with their object files. Continuing from the above example,
274 .. code-block:: cmake
276 add_library(obj2 OBJECT obj2.c)
277 target_link_libraries(obj2 PUBLIC obj)
279 add_executable(main2 main2.c)
280 target_link_libraries(main2 obj2)
282 compiles ``obj2.c`` with ``-DA -DOBJ``, creates executable ``main2``
283 with object files from ``main2.c`` and ``obj2.c``, and links ``main2``
286 In other words, when :ref:`Object Libraries` appear in a target's
287 :prop_tgt:`INTERFACE_LINK_LIBRARIES` property they will be
288 treated as :ref:`Interface Libraries`, but when they appear in
289 a target's :prop_tgt:`LINK_LIBRARIES` property their object files
290 will be included in the link too.
292 .. _`Linking Object Libraries via $<TARGET_OBJECTS>`:
294 Linking Object Libraries via $<TARGET_OBJECTS>
295 """"""""""""""""""""""""""""""""""""""""""""""
297 .. versionadded:: 3.21
299 The object files associated with an object library may be referenced
300 by the :genex:`$<TARGET_OBJECTS>` generator expression. Such object
301 files are placed on the link line *before* all libraries, regardless
302 of their relative order. Additionally, an ordering dependency will be
303 added to the build system to make sure the object library is up-to-date
304 before the dependent target links. For example, the code
306 .. code-block:: cmake
308 add_library(obj3 OBJECT obj3.c)
309 target_compile_definitions(obj3 PUBLIC OBJ3)
311 add_executable(main3 main3.c)
312 target_link_libraries(main3 PRIVATE a3 $<TARGET_OBJECTS:obj3> b3)
314 links executable ``main3`` with object files from ``main3.c``
315 and ``obj3.c`` followed by the ``a3`` and ``b3`` libraries.
316 ``main3.c`` is *not* compiled with usage requirements from ``obj3``,
319 This approach can be used to achieve transitive inclusion of object
320 files in link lines as usage requirements. Continuing the above
323 .. code-block:: cmake
325 add_library(iface_obj3 INTERFACE)
326 target_link_libraries(iface_obj3 INTERFACE obj3 $<TARGET_OBJECTS:obj3>)
328 creates an interface library ``iface_obj3`` that forwards the ``obj3``
329 usage requirements and adds the ``obj3`` object files to dependents'
332 .. code-block:: cmake
334 add_executable(use_obj3 use_obj3.c)
335 target_link_libraries(use_obj3 PRIVATE iface_obj3)
337 compiles ``use_obj3.c`` with ``-DOBJ3`` and links executable ``use_obj3``
338 with object files from ``use_obj3.c`` and ``obj3.c``.
340 This also works transitively through a static library. Since a static
341 library does not link, it does not consume the object files from
342 object libraries referenced this way. Instead, the object files
343 become transitive link dependencies of the static library.
344 Continuing the above example, the code
346 .. code-block:: cmake
348 add_library(static3 STATIC static3.c)
349 target_link_libraries(static3 PRIVATE iface_obj3)
351 add_executable(use_static3 use_static3.c)
352 target_link_libraries(use_static3 PRIVATE static3)
354 compiles ``static3.c`` with ``-DOBJ3`` and creates ``libstatic3.a``
355 using only its own object file. ``use_static3.c`` is compiled *without*
356 ``-DOBJ3`` because the usage requirement is not transitive through
357 the private dependency of ``static3``. However, the link dependencies
358 of ``static3`` are propagated, including the ``iface_obj3`` reference
359 to ``$<TARGET_OBJECTS:obj3>``. The ``use_static3`` executable is
360 created with object files from ``use_static3.c`` and ``obj3.c``, and
361 linked to library ``libstatic3.a``.
363 When using this approach, it is the project's responsibility to avoid
364 linking multiple dependent binaries to ``iface_obj3``, because they will
365 all get the ``obj3`` object files on their link lines.
369 Referencing :genex:`$<TARGET_OBJECTS>` in ``target_link_libraries``
370 calls worked in versions of CMake prior to 3.21 for some cases,
371 but was not fully supported:
373 * It did not place the object files before libraries on link lines.
374 * It did not add an ordering dependency on the object library.
375 * It did not work in Xcode with multiple architectures.
377 Cyclic Dependencies of Static Libraries
378 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
380 The library dependency graph is normally acyclic (a DAG), but in the case
381 of mutually-dependent ``STATIC`` libraries CMake allows the graph to
382 contain cycles (strongly connected components). When another target links
383 to one of the libraries, CMake repeats the entire connected component.
384 For example, the code
386 .. code-block:: cmake
388 add_library(A STATIC a.c)
389 add_library(B STATIC b.c)
390 target_link_libraries(A B)
391 target_link_libraries(B A)
392 add_executable(main main.c)
393 target_link_libraries(main A)
395 links ``main`` to ``A B A B``. While one repetition is usually
396 sufficient, pathological object file and symbol arrangements can require
397 more. One may handle such cases by using the
398 :prop_tgt:`LINK_INTERFACE_MULTIPLICITY` target property or by manually
399 repeating the component in the last ``target_link_libraries`` call.
400 However, if two archives are really so interdependent they should probably
401 be combined into a single archive, perhaps by using :ref:`Object Libraries`.
403 Creating Relocatable Packages
404 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
406 .. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES`
407 .. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt