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``
150 :ref:`scope <Target Usage Requirements>` keywords can be used to
151 specify both the link dependencies and the link interface in one command.
153 Libraries and targets following ``PUBLIC`` are linked to, and are made
154 part of the link interface. Libraries and targets following ``PRIVATE``
155 are linked to, but are not made part of the link interface. Libraries
156 following ``INTERFACE`` are appended to the link interface and are not
157 used for linking ``<target>``.
159 Libraries for both a Target and its Dependents
160 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
162 .. code-block:: cmake
164 target_link_libraries(<target> <item>...)
166 Library dependencies are transitive by default with this signature.
167 When this target is linked into another target then the libraries
168 linked to this target will appear on the link line for the other
169 target too. This transitive "link interface" is stored in the
170 :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property and may be overridden
171 by setting the property directly. When :policy:`CMP0022` is not set to
172 ``NEW``, transitive linking is built in but may be overridden by the
173 :prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Calls to other signatures
174 of this command may set the property making any libraries linked
175 exclusively by this signature private.
177 Libraries for a Target and/or its Dependents (Legacy)
178 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
180 .. code-block:: cmake
182 target_link_libraries(<target>
183 <LINK_PRIVATE|LINK_PUBLIC> <lib>...
184 [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
186 The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
187 the link dependencies and the link interface in one command.
189 This signature is for compatibility only. Prefer the ``PUBLIC`` or
190 ``PRIVATE`` keywords instead.
192 Libraries and targets following ``LINK_PUBLIC`` are linked to, and are
193 made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy
194 :policy:`CMP0022` is not ``NEW``, they are also made part of the
195 :prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following
196 ``LINK_PRIVATE`` are linked to, but are not made part of the
197 :prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`).
199 Libraries for Dependents Only (Legacy)
200 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
202 .. code-block:: cmake
204 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
206 The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the
207 :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them
208 for linking. If policy :policy:`CMP0022` is not ``NEW``, then this mode
209 also appends libraries to the :prop_tgt:`LINK_INTERFACE_LIBRARIES` and its
210 per-configuration equivalent.
212 This signature is for compatibility only. Prefer the ``INTERFACE`` mode
215 Libraries specified as ``debug`` are wrapped in a generator expression to
216 correspond to debug builds. If policy :policy:`CMP0022` is
217 not ``NEW``, the libraries are also appended to the
218 :prop_tgt:`LINK_INTERFACE_LIBRARIES_DEBUG <LINK_INTERFACE_LIBRARIES_<CONFIG>>`
219 property (or to the properties corresponding to configurations listed in
220 the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set).
221 Libraries specified as ``optimized`` are appended to the
222 :prop_tgt:`INTERFACE_LINK_LIBRARIES` property. If policy :policy:`CMP0022`
223 is not ``NEW``, they are also appended to the
224 :prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Libraries specified as
225 ``general`` (or without any keyword) are treated as if specified for both
226 ``debug`` and ``optimized``.
228 Linking Object Libraries
229 ^^^^^^^^^^^^^^^^^^^^^^^^
231 .. versionadded:: 3.12
233 :ref:`Object Libraries` may be used as the ``<target>`` (first) argument
234 of ``target_link_libraries`` to specify dependencies of their sources
235 on other libraries. For example, the code
237 .. code-block:: cmake
239 add_library(A SHARED a.c)
240 target_compile_definitions(A PUBLIC A)
242 add_library(obj OBJECT obj.c)
243 target_compile_definitions(obj PUBLIC OBJ)
244 target_link_libraries(obj PUBLIC A)
246 compiles ``obj.c`` with ``-DA -DOBJ`` and establishes usage requirements
247 for ``obj`` that propagate to its dependents.
249 Normal libraries and executables may link to :ref:`Object Libraries`
250 to get their objects and usage requirements. Continuing the above
253 .. code-block:: cmake
255 add_library(B SHARED b.c)
256 target_link_libraries(B PUBLIC obj)
258 compiles ``b.c`` with ``-DA -DOBJ``, creates shared library ``B``
259 with object files from ``b.c`` and ``obj.c``, and links ``B`` to ``A``.
260 Furthermore, the code
262 .. code-block:: cmake
264 add_executable(main main.c)
265 target_link_libraries(main B)
267 compiles ``main.c`` with ``-DA -DOBJ`` and links executable ``main``
268 to ``B`` and ``A``. The object library's usage requirements are
269 propagated transitively through ``B``, but its object files are not.
271 :ref:`Object Libraries` may "link" to other object libraries to get
272 usage requirements, but since they do not have a link step nothing
273 is done with their object files. Continuing from the above example,
276 .. code-block:: cmake
278 add_library(obj2 OBJECT obj2.c)
279 target_link_libraries(obj2 PUBLIC obj)
281 add_executable(main2 main2.c)
282 target_link_libraries(main2 obj2)
284 compiles ``obj2.c`` with ``-DA -DOBJ``, creates executable ``main2``
285 with object files from ``main2.c`` and ``obj2.c``, and links ``main2``
288 In other words, when :ref:`Object Libraries` appear in a target's
289 :prop_tgt:`INTERFACE_LINK_LIBRARIES` property they will be
290 treated as :ref:`Interface Libraries`, but when they appear in
291 a target's :prop_tgt:`LINK_LIBRARIES` property their object files
292 will be included in the link too.
294 .. _`Linking Object Libraries via $<TARGET_OBJECTS>`:
296 Linking Object Libraries via $<TARGET_OBJECTS>
297 """"""""""""""""""""""""""""""""""""""""""""""
299 .. versionadded:: 3.21
301 The object files associated with an object library may be referenced
302 by the :genex:`$<TARGET_OBJECTS>` generator expression. Such object
303 files are placed on the link line *before* all libraries, regardless
304 of their relative order. Additionally, an ordering dependency will be
305 added to the build system to make sure the object library is up-to-date
306 before the dependent target links. For example, the code
308 .. code-block:: cmake
310 add_library(obj3 OBJECT obj3.c)
311 target_compile_definitions(obj3 PUBLIC OBJ3)
313 add_executable(main3 main3.c)
314 target_link_libraries(main3 PRIVATE a3 $<TARGET_OBJECTS:obj3> b3)
316 links executable ``main3`` with object files from ``main3.c``
317 and ``obj3.c`` followed by the ``a3`` and ``b3`` libraries.
318 ``main3.c`` is *not* compiled with usage requirements from ``obj3``,
321 This approach can be used to achieve transitive inclusion of object
322 files in link lines as usage requirements. Continuing the above
325 .. code-block:: cmake
327 add_library(iface_obj3 INTERFACE)
328 target_link_libraries(iface_obj3 INTERFACE obj3 $<TARGET_OBJECTS:obj3>)
330 creates an interface library ``iface_obj3`` that forwards the ``obj3``
331 usage requirements and adds the ``obj3`` object files to dependents'
334 .. code-block:: cmake
336 add_executable(use_obj3 use_obj3.c)
337 target_link_libraries(use_obj3 PRIVATE iface_obj3)
339 compiles ``use_obj3.c`` with ``-DOBJ3`` and links executable ``use_obj3``
340 with object files from ``use_obj3.c`` and ``obj3.c``.
342 This also works transitively through a static library. Since a static
343 library does not link, it does not consume the object files from
344 object libraries referenced this way. Instead, the object files
345 become transitive link dependencies of the static library.
346 Continuing the above example, the code
348 .. code-block:: cmake
350 add_library(static3 STATIC static3.c)
351 target_link_libraries(static3 PRIVATE iface_obj3)
353 add_executable(use_static3 use_static3.c)
354 target_link_libraries(use_static3 PRIVATE static3)
356 compiles ``static3.c`` with ``-DOBJ3`` and creates ``libstatic3.a``
357 using only its own object file. ``use_static3.c`` is compiled *without*
358 ``-DOBJ3`` because the usage requirement is not transitive through
359 the private dependency of ``static3``. However, the link dependencies
360 of ``static3`` are propagated, including the ``iface_obj3`` reference
361 to ``$<TARGET_OBJECTS:obj3>``. The ``use_static3`` executable is
362 created with object files from ``use_static3.c`` and ``obj3.c``, and
363 linked to library ``libstatic3.a``.
365 When using this approach, it is the project's responsibility to avoid
366 linking multiple dependent binaries to ``iface_obj3``, because they will
367 all get the ``obj3`` object files on their link lines.
371 Referencing :genex:`$<TARGET_OBJECTS>` in ``target_link_libraries``
372 calls worked in versions of CMake prior to 3.21 for some cases,
373 but was not fully supported:
375 * It did not place the object files before libraries on link lines.
376 * It did not add an ordering dependency on the object library.
377 * It did not work in Xcode with multiple architectures.
379 Cyclic Dependencies of Static Libraries
380 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
382 The library dependency graph is normally acyclic (a DAG), but in the case
383 of mutually-dependent ``STATIC`` libraries CMake allows the graph to
384 contain cycles (strongly connected components). When another target links
385 to one of the libraries, CMake repeats the entire connected component.
386 For example, the code
388 .. code-block:: cmake
390 add_library(A STATIC a.c)
391 add_library(B STATIC b.c)
392 target_link_libraries(A B)
393 target_link_libraries(B A)
394 add_executable(main main.c)
395 target_link_libraries(main A)
397 links ``main`` to ``A B A B``. While one repetition is usually
398 sufficient, pathological object file and symbol arrangements can require
399 more. One may handle such cases by using the
400 :prop_tgt:`LINK_INTERFACE_MULTIPLICITY` target property or by manually
401 repeating the component in the last ``target_link_libraries`` call.
402 However, if two archives are really so interdependent they should probably
403 be combined into a single archive, perhaps by using :ref:`Object Libraries`.
405 Creating Relocatable Packages
406 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
408 .. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES`
409 .. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt