target_link_libraries

指定链接给定目标和/或其依赖项时使用的库或标志。链接库目标的使用要求将传播。目标的依赖项的使用要求会影响其自身源文件的编译。

概述

此命令有多个签名，详情如下小节。所有签名都具有以下通用形式

target_link_libraries(<target> ... <item>... ...)

命名的 <target> 必须已由诸如 add_executable() 或 add_library() 的命令创建，并且不能是 ALIAS 目标。如果策略 CMP0079 未设置为 NEW，则目标必须已在当前目录中创建。对同一个 <target> 的重复调用将按调用顺序追加项目。

3.13 版本新增：<target> 不必与 target_link_libraries 调用在同一目录中定义。

每个 <item> 可以是

• 库目标名称：生成的链接行将包含与目标关联的可链接库文件的完整路径。如果库文件发生更改，构建系统将具有重新链接 <target> 的依赖关系。

  命名目标必须由项目中的 add_library() 或作为 导入库 创建。如果它是在项目中创建的，则会在构建系统中自动添加一个排序依赖关系，以确保在 <target> 链接之前，命名的库目标是最新的。

  如果导入的库设置了 IMPORTED_NO_SONAME 目标属性，CMake 可能会要求链接器搜索库，而不是使用完整路径（例如，/usr/lib/libfoo.so 变为 -lfoo）。

  目标的工件的完整路径将自动为 shell 引用/转义。

• 库文件的完整路径：生成的链接行通常会保留文件的完整路径。如果库文件发生更改，构建系统将具有重新链接 <target> 的依赖关系。

  在某些情况下，CMake 可能会要求链接器搜索库（例如，/usr/lib/libfoo.so 变为 -lfoo），例如当检测到共享库没有 SONAME 字段时。在 CMake 4.0 之前的版本中，请参阅策略 CMP0060 了解另一种情况的讨论。

  如果库文件位于 macOS 框架中，则该框架的 Headers 目录也将作为使用要求进行处理。这与将框架目录作为包含目录传递具有相同的效果。

  3.28 版本新增：库文件可能指向 Apple 平台上的 .xcframework 文件夹。如果指向，目标将获得所选库的 Headers 目录作为使用要求。

  3.8 版本新增：对于 VS 2010 及更高版本的 Visual Studio 生成器，以 .targets 结尾的库文件将被视为 MSBuild targets 文件并导入到生成的项目文件中。其他生成器不支持此功能。

  库文件的完整路径将自动为 shell 引用/转义。

• 纯库名称：生成的链接行将要求链接器搜索库（例如，foo 变为 -lfoo 或 foo.lib）。

  库名称/标志被视为命令行字符串片段，将直接使用，无需额外引用或转义。

• 链接标志：以 - 开头，但不是 -l 或 -framework 的项目名称被视为链接器标志。请注意，此类标志将与其他库链接项目一样进行处理以用于传递依赖项，因此它们通常仅安全地指定为不会传播到依赖项的私有链接项目。

  此处指定的链接标志将插入到链接命令中，与链接库相同的位置。根据链接器，这可能不正确。使用 LINK_OPTIONS 目标属性或 target_link_options() 命令显式添加链接标志。然后，这些标志将放置在链接命令中工具链定义的标志位置。

  3.13 版本新增：LINK_OPTIONS 目标属性和 target_link_options() 命令。对于 CMake 的早期版本，请改用 LINK_FLAGS 属性。

  链接标志被视为命令行字符串片段，将直接使用，无需额外引用或转义。

• 生成器表达式：一个 $<...> 生成器 表达式 可以评估为上述任何项目或它们的分号分隔列表。如果 ... 包含任何 ; 字符，例如在评估 ${list} 变量后，请务必使用显式引用的参数 "$<...>"，以便此命令将其作为单个 <item> 接收。

  此外，生成器表达式可以用作上述任何项目的一部分，例如 foo$<1:_d>。

• debug、optimized 或 general 关键字紧跟另一个 <item>。紧随此类关键字的项目将仅用于相应的构建配置。debug 关键字对应于 Debug 配置（或如果设置了 DEBUG_CONFIGURATIONS 全局属性，则对应于其中命名的配置）。optimized 关键字对应于所有其他配置。general 关键字对应于所有配置，并且是纯粹可选的。这些关键字由此命令立即解释，因此当由生成器表达式生成时没有特殊含义。

  或者，诸如 $<CONFIG> 的生成器表达式提供了更精细的按配置链接 <item>。为了更结构化的方法，可以通过创建和链接到设置了 IMPORTED_CONFIGURATIONS 属性的导入库目标来实现更高的粒度，尤其是在查找模块中。

包含 :: 的项目，例如 Foo::Bar，被假定为 IMPORTED 或 ALIAS 库目标名称，如果不存在此类目标，则会导致错误。请参阅策略 CMP0028。

有关 CMake 如何在链接器命令行上排列直接链接依赖项的详细信息，请参阅 CMAKE_LINK_LIBRARIES_STRATEGY 变量和相应的 LINK_LIBRARIES_STRATEGY 目标属性。

有关定义构建系统属性的更多信息，请参阅 cmake-buildsystem(7) 手册。

处理编译器驱动差异

4.0 版本新增。

为了将选项传递给链接器工具，每个编译器驱动程序都有其自己的语法。LINKER: 前缀和 , 分隔符可用于以可移植的方式指定传递给链接器工具的选项。LINKER: 将被适当的驱动程序选项替换，, 将被适当的驱动程序分隔符替换。驱动程序前缀和驱动程序分隔符由 CMAKE_<LANG>_LINKER_WRAPPER_FLAG 和 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP 变量的值给出。

例如，"LINKER:-z,defs" 对于 Clang 变为 -Xlinker -z -Xlinker defs，对于 GNU GCC 变为 -Wl,-z,defs。

LINKER: 前缀支持使用 SHELL: 前缀和空格作为分隔符的替代语法来指定参数。前面的示例将变为 "LINKER:SHELL:-z defs"。

注意

不支持在 LINKER: 前缀的开头以外的任何位置指定 SHELL: 前缀。

目标及其依赖项的库

target_link_libraries(<target>
                      <PRIVATE|PUBLIC|INTERFACE> <item>...
                     [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)

PUBLIC、PRIVATE 和 INTERFACE 作用域关键字可用于在一个命令中指定链接依赖项和链接接口。

跟随 PUBLIC 的库和目标被链接到，并成为链接接口的一部分。跟随 PRIVATE 的库和目标被链接到，但不是链接接口的一部分。跟随 INTERFACE 的库被附加到链接接口，并且不用于链接 <target>。

目标及其依赖项的库

target_link_libraries(<target> <item>...)

使用此签名时，库依赖项默认是可传递的。当此目标链接到另一个目标时，链接到此目标的库也将出现在另一个目标的链接行上。此可传递的“链接接口”存储在 INTERFACE_LINK_LIBRARIES 目标属性中，并且可以通过直接设置属性来覆盖。

在 CMake 4.0 之前的版本中，如果 CMP0022 未设置为 NEW，则内置了传递链接，但可以通过 LINK_INTERFACE_LIBRARIES 属性覆盖。对此命令的其他签名的调用可能会设置该属性，从而使此签名独占链接的任何库成为私有库。

目标和/或其依赖项的库（旧版）

此签名仅用于兼容性。请改用 PUBLIC 或 PRIVATE 关键字。

target_link_libraries(<target>
                      <LINK_PRIVATE|LINK_PUBLIC> <lib>...
                     [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)

LINK_PUBLIC 和 LINK_PRIVATE 模式可用于在一个命令中指定链接依赖项和链接接口。

跟随 LINK_PUBLIC 的库和目标被链接到，并成为 INTERFACE_LINK_LIBRARIES 的一部分。

在 CMake 4.0 之前的版本中，如果策略 CMP0022 不是 NEW，它们也会成为 LINK_INTERFACE_LIBRARIES 及其按配置等效项的一部分。跟随 LINK_PRIVATE 的库和目标被链接到，但不是 INTERFACE_LINK_LIBRARIES（或 LINK_INTERFACE_LIBRARIES）的一部分。

仅依赖项的库（旧版）

此签名仅用于兼容性。请改用 INTERFACE 模式。

target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)

LINK_INTERFACE_LIBRARIES 模式将库附加到 INTERFACE_LINK_LIBRARIES 目标属性，而不是用于链接。

在 CMake 4.0 之前的版本中，如果策略 CMP0022 不是 NEW，则此模式还会将库附加到 LINK_INTERFACE_LIBRARIES 及其按配置等效项。

链接对象库

3.12 版本新增。

对象库可用作 target_link_libraries 的 <target> (第一个) 参数，以指定其源对其他库的依赖关系。例如，以下代码

add_library(A SHARED a.c)
target_compile_definitions(A PUBLIC A)

add_library(obj OBJECT obj.c)
target_compile_definitions(obj PUBLIC OBJ)
target_link_libraries(obj PUBLIC A)

使用 -DA -DOBJ 编译 obj.c，并为 obj 建立传播到其依赖项的使用要求。

普通库和可执行文件可以链接到 对象库 以获取其对象和使用要求。继续上面的示例，以下代码

add_library(B SHARED b.c)
target_link_libraries(B PUBLIC obj)

使用 -DA -DOBJ 编译 b.c，使用 b.c 和 obj.c 的对象文件创建共享库 B，并将 B 链接到 A。此外，以下代码

add_executable(main main.c)
target_link_libraries(main B)

使用 -DA -DOBJ 编译 main.c，并将可执行文件 main 链接到 B 和 A。对象库的使用要求通过 B 传递，但其对象文件不会。

对象库可以“链接”到其他对象库以获取使用要求，但由于它们没有链接步骤，因此它们的内部对象文件不会进行任何处理。继续上面的示例，以下代码

add_library(obj2 OBJECT obj2.c)
target_link_libraries(obj2 PUBLIC obj)

add_executable(main2 main2.c)
target_link_libraries(main2 obj2)

使用 -DA -DOBJ 编译 obj2.c，使用 main2.c 和 obj2.c 的对象文件创建可执行文件 main2，并将 main2 链接到 A。

换句话说，当对象库出现在目标的INTERFACE_LINK_LIBRARIES属性中时，它们将被视为接口库，但当它们出现在目标的LINK_LIBRARIES属性中时，其对象文件也将包含在链接中。

通过 $<TARGET_OBJECTS> 链接对象库

3.21 版本新增。

与对象库关联的对象文件可以通过 $<TARGET_OBJECTS> 生成器表达式引用。这些对象文件放置在链接行上，位于所有库之前，无论它们的相对顺序如何。此外，构建系统将添加一个排序依赖项，以确保对象库在依赖目标链接之前是最新的。例如，以下代码

add_library(obj3 OBJECT obj3.c)
target_compile_definitions(obj3 PUBLIC OBJ3)

add_executable(main3 main3.c)
target_link_libraries(main3 PRIVATE a3 $<TARGET_OBJECTS:obj3> b3)

将可执行文件 main3 链接到 main3.c 和 obj3.c 的对象文件，然后是 a3 和 b3 库。main3.c 不使用来自 obj3 的使用要求（例如 -DOBJ3）进行编译。

此方法可用于实现对象文件在链接行中作为使用要求的传递包含。继续上面的示例，以下代码

add_library(iface_obj3 INTERFACE)
target_link_libraries(iface_obj3 INTERFACE obj3 $<TARGET_OBJECTS:obj3>)

创建了一个接口库 iface_obj3，该库转发 obj3 使用要求，并将 obj3 对象文件添加到依赖项的链接行中。以下代码

add_executable(use_obj3 use_obj3.c)
target_link_libraries(use_obj3 PRIVATE iface_obj3)

使用 -DOBJ3 编译 use_obj3.c，并将可执行文件 use_obj3 链接到 use_obj3.c 和 obj3.c 的对象文件。

这也通过静态库传递工作。由于静态库不链接，因此它不会消耗以这种方式引用的对象库中的对象文件。相反，对象文件成为静态库的传递链接依赖项。继续上面的示例，以下代码

add_library(static3 STATIC static3.c)
target_link_libraries(static3 PRIVATE iface_obj3)

add_executable(use_static3 use_static3.c)
target_link_libraries(use_static3 PRIVATE static3)

使用 -DOBJ3 编译 static3.c，并仅使用其自己的对象文件创建 libstatic3.a。use_static3.c 编译时不包含 -DOBJ3，因为使用要求不会通过 static3 的私有依赖项进行传递。但是，static3 的链接依赖项会传播，包括 iface_obj3 对 $<TARGET_OBJECTS:obj3> 的引用。use_static3 可执行文件是使用 use_static3.c 和 obj3.c 的对象文件创建的，并链接到库 libstatic3.a。

使用此方法时，项目有责任避免将多个依赖二进制文件链接到 iface_obj3，因为它们都将在其链接行上获得 obj3 对象文件。

注意

在 CMake 3.21 之前的版本中，在 target_link_libraries 调用中引用 $<TARGET_OBJECTS> 在某些情况下有效，但未完全支持

• 它没有将对象文件放在链接行中的库之前。

• 它没有在对象库上添加排序依赖项。

• 它在 Xcode 中不支持多种架构。

静态库的循环依赖

库依赖图通常是无环图 (DAG)，但在相互依赖的 STATIC 库的情况下，CMake 允许图包含循环（强连接组件）。当另一个目标链接到其中一个库时，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)

将 main 链接到 A B A B。虽然一次重复通常就足够了，但病态的对象文件和符号排列可能需要更多。可以通过使用 LINK_INTERFACE_MULTIPLICITY 目标属性或在最后的 target_link_libraries 调用中手动重复组件来处理此类情况。但是，如果两个归档确实如此相互依赖，它们可能应该合并到一个归档中，也许通过使用对象库。

创建可重定位包

请注意，不建议使用依赖项的绝对路径填充目标的 INTERFACE_LINK_LIBRARIES。那会将依赖项的库文件路径硬编码到在制作包的机器上找到的已安装包中。

有关在创建用于重新分发的包时必须额外注意指定使用要求的讨论，请参阅 cmake-packages(7) 手册的创建可重定位包部分。

另请参阅

• target_compile_definitions()

• target_compile_features()

• target_compile_options()

• target_include_directories()

• target_link_directories()

• target_link_options()

• target_precompile_headers()

• target_sources()