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 by a command such as
add_executable()
or add_library()
and must not be an
ALIAS target. If policy CMP0079
is not
set to NEW
then the target must have been created in the current
directory. 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
).
The full path to the target’s artifact will be quoted/escaped for the shell automatically.
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 macOS 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.
On 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.
The full path to the library file will be quoted/escaped for the shell automatically.
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
).
The library name/flag is treated as a command-line string fragment and will be used with no extra quoting or escaping.
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_OPTIONS
target property or
target_link_options()
command to add link
flags explicitly. The flags will then be placed at the toolchain-defined
flag position in the link command.
The link flag is treated as a command-line string fragment and will be used with no extra quoting or escaping.
A generator expression: A $<...>
generator expression
may evaluate to any of the above
items or to a semicolon-separated list of them.
If the ...
contains any ;
characters, e.g. after evaluation
of a ${list}
variable, be sure to use an explicitly quoted
argument "$<...>"
so that this command receives it as a
single <item>
.
Additionally, a generator expression may be used as a fragment of
any of the above items, e.g. foo$<1:_d>
.
Note that generator expressions will not be used in OLD handling of
policy CMP0003
or policy CMP0004
.
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.
These keywords are interpreted immediately by this command and therefore
have no special meaning when produced by a generator expression.
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
.
See the cmake-buildsystem(7)
manual for more on defining
buildsystem properties.