Specify libraries or flags to use when linking a given target and/or
its dependents. Usage requirements
from linked library targets will be propagated. Usage requirements
of a target’s dependencies affect compilation of its own sources.
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 add_executable() or 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 add_library() within
the project or as an IMPORTED library.
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 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 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
usage requirement. 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.
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 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 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
IMPORTED library targets.
Items containing ::, such as Foo::Bar, are assumed to be
IMPORTED or ALIAS library
target names and will cause an error if no such target exists.
See 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 CMP0003 or CMP0004.
See the cmake-generator-expressions(7) manual for available
expressions. See the cmake-buildsystem(7) manual for more on
defining buildsystem properties.
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>.
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
INTERFACE_LINK_LIBRARIES target property and may be overridden
by setting the property directly. When CMP0022 is not set to
NEW, transitive linking is built in but may be overridden by the
LINK_INTERFACE_LIBRARIES property. Calls to other signatures
of this command may set the property making any libraries linked
exclusively by this signature private.
The LINK_INTERFACE_LIBRARIES mode appends the libraries to the
INTERFACE_LINK_LIBRARIES target property instead of using them
for linking. If policy CMP0022 is not NEW, then this mode
also appends libraries to the LINK_INTERFACE_LIBRARIES and its
This signature is for compatibility only. Prefer the INTERFACE mode
Libraries specified as debug are wrapped in a generator expression to
correspond to debug builds. If policy CMP0022 is
not NEW, the libraries are also appended to the
property (or to the properties corresponding to configurations listed in
the DEBUG_CONFIGURATIONS global property if it is set).
Libraries specified as optimized are appended to the
INTERFACE_LINK_LIBRARIES property. If policy CMP0022
is not NEW, they are also appended to the
LINK_INTERFACE_LIBRARIES property. Libraries specified as
general (or without any keyword) are treated as if specified for both
debug and optimized.
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
links main to ABAB. While one repetition is usually
sufficient, pathological object file and symbol arrangements can require
more. One may handle such cases by using the
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 Object Libraries.
Note that it is not advisable to populate the
INTERFACE_LINK_LIBRARIES of a target with absolute paths to dependencies.
That would hard-code into installed packages the library file paths
for dependencies as found on the machine the package was made on.