add_library

使用指定源文件向项目添加库。

普通库

add_library(<name> [<type>] [EXCLUDE_FROM_ALL] <sources>...)

添加一个名为 <name> 的库目标,该目标将从命令调用中列出的源文件构建。

可选的 <type> 指定要创建的库的类型

STATIC

一个 静态库:用于链接其他目标的对象文件存档。

SHARED

一个 共享库:一个动态库,可以被其他目标链接并在运行时加载。

MODULE

一个 模块库:一个插件,不能被其他目标链接,但可以在运行时使用类似 dlopen 的功能动态加载。

如果未给定 <type>,则默认值为 STATICSHARED,具体取决于 BUILD_SHARED_LIBS 变量的值。

选项包括

EXCLUDE_FROM_ALL

自动设置 EXCLUDE_FROM_ALL 目标属性。详情请参阅该目标属性的文档。

<name> 对应于逻辑目标名称,并且必须在项目内全局唯一。构建的库的实际文件名是根据原生平台的约定构造的(例如 lib<name>.a<name>.lib)。

在版本 3.1 中新增: add_library 的源参数可以使用语法 $<...> 的“生成器表达式”。有关可用表达式的信息,请参阅 cmake-generator-expressions(7) 手册。

在版本 3.11 中新增: 如果源文件稍后使用 target_sources() 添加,则可以省略源文件。

对于 SHAREDMODULE 库,POSITION_INDEPENDENT_CODE 目标属性会自动设置为 ON。一个 SHARED 库可以标记 FRAMEWORK 目标属性以创建 macOS 框架。

在版本 3.8 中新增: STATIC 库可以标记 FRAMEWORK 目标属性以创建静态框架。

如果一个库不导出任何符号,则不能将其声明为 SHARED 库。例如,一个不导出任何非托管符号的 Windows 资源 DLL 或托管 C++/CLI DLL 需要是一个 MODULE 库。这是因为 CMake 期望 SHARED 库在 Windows 上总是有一个关联的导入库。

默认情况下,库文件将在与调用命令的源树目录对应的构建树目录中创建。请参阅 ARCHIVE_OUTPUT_DIRECTORYLIBRARY_OUTPUT_DIRECTORYRUNTIME_OUTPUT_DIRECTORY 目标属性的文档以更改此位置。请参阅 OUTPUT_NAME 目标属性的文档以更改最终文件名的 <name> 部分。

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

另请参阅 HEADER_FILE_ONLY,了解如果某些源文件是预处理过的,并且您希望在 IDE 中访问原始源文件时该怎么做。

在版本 3.30 中更改: 在不支持共享库的平台上,add_library 现在会在创建 SHARED 库的调用时失败,而不是像以前那样自动将其转换为 STATIC 库。请参阅策略 CMP0164

对象库

add_library(<name> OBJECT <sources>...)

添加一个 目标库,用于编译源文件,而不将其目标文件存档或链接到库中。

add_libraryadd_executable() 创建的其他目标可以使用 $<TARGET_OBJECTS:objlib> 形式的表达式作为源来引用对象,其中 objlib 是目标库名称。例如

add_library(... $<TARGET_OBJECTS:objlib> ...)
add_executable(... $<TARGET_OBJECTS:objlib> ...)

将 objlib 的目标文件与其自身源文件编译出的目标文件一起包含在一个库和一个可执行文件中。目标库只能包含可编译的源文件、头文件以及不会影响普通库链接的其他文件(例如 .txt)。它们可以包含生成此类源文件的自定义命令,但不能包含 PRE_BUILDPRE_LINKPOST_BUILD 命令。某些原生构建系统(例如 Xcode)可能不喜欢只包含目标文件的目标,因此请考虑向任何引用 $<TARGET_OBJECTS:objlib> 的目标至少添加一个真实的源文件。

在版本 3.12 中新增: 目标库可以使用 target_link_libraries() 进行链接。

接口库

add_library(<name> INTERFACE)

添加一个 接口库 目标,该目标可以为依赖项指定使用要求,但不编译源文件,也不在磁盘上生成库工件。

不包含源文件的接口库不作为目标包含在生成的构建系统中。但是,它可以设置属性,并且可以安装和导出。通常,INTERFACE_* 属性使用以下命令填充在接口目标上:

然后将其作为参数传递给 target_link_libraries(),就像其他任何目标一样。

在版本 3.15 中新增: 接口库可以拥有 PUBLIC_HEADERPRIVATE_HEADER 属性。由这些属性指定的头文件可以使用 install(TARGETS) 命令安装。

add_library(<name> INTERFACE [EXCLUDE_FROM_ALL] <sources>...)

3.19 版本新增。

添加一个带有源文件(除了 上述签名 所述的使用要求和属性之外)的 接口库 目标。源文件可以直接在 add_library 调用中列出,也可以稍后通过调用带有 PRIVATEPUBLIC 关键字的 target_sources() 来添加。

如果接口库有源文件(即设置了 SOURCES 目标属性),或者头文件集(即设置了 HEADER_SETS 目标属性),它将在生成的构建系统中显示为一个构建目标,非常类似于由 add_custom_target() 命令定义的目标。它不编译任何源,但包含由 add_custom_command() 命令创建的自定义命令的构建规则。

选项包括

EXCLUDE_FROM_ALL

自动设置 EXCLUDE_FROM_ALL 目标属性。详情请参阅该目标属性的文档。

注意

在大多数命令签名中,如果出现 INTERFACE 关键字,则其后列出的项仅成为该目标的使用要求的一部分,而不属于目标自身的设置。但是,在此 add_library 签名中,INTERFACE 关键字仅指库类型。在 add_library 调用中其后列出的源是接口库的 PRIVATE,不会出现在其 INTERFACE_SOURCES 目标属性中。

导入库

add_library(<name> <type> IMPORTED [GLOBAL])

添加一个名为 <name>IMPORTED 库目标。目标名称可以像项目中构建的任何目标一样被引用,但默认情况下,它仅在创建它的目录及其子目录中可见。

<type> 必须是以下之一:

STATIC, SHARED, MODULE, UNKNOWN

引用位于项目外部的库文件。IMPORTED_LOCATION 目标属性(或其每个配置的变体 IMPORTED_LOCATION_<CONFIG>)指定磁盘上主库文件的位置。

  • 对于大多数非 Windows 平台上的 SHARED 库,主库文件是链接器和动态加载器都使用的 .so.dylib 文件。如果引用的库文件具有 SONAME(或在 macOS 上,具有以 @rpath/ 开头的 LC_ID_DYLIB),则该字段的值应在 IMPORTED_SONAME 目标属性中设置。如果引用的库文件没有 SONAME,但平台支持它,则应设置 IMPORTED_NO_SONAME 目标属性。

  • 对于 Windows 上的 SHARED 库,IMPORTED_IMPLIB 目标属性(或其每个配置的变体 IMPORTED_IMPLIB_<CONFIG>)指定磁盘上 DLL 导入库文件(.lib.dll.a)的位置,而 IMPORTED_LOCATION.dll 运行时库的位置(可选,但 TARGET_RUNTIME_DLLS 生成器表达式需要)。

可以在 INTERFACE_* 属性中指定附加使用要求。

UNKNOWN 库类型通常仅在 Find Modules 的实现中使用。它允许使用导入库的路径(通常使用 find_library() 命令找到),而无需知道它的库类型。这在 Windows 上特别有用,因为静态库和 DLL 的导入库都具有相同的文件扩展名。

OBJECT

引用项目外部的一组目标文件。IMPORTED_OBJECTS 目标属性(或其按配置变体 IMPORTED_OBJECTS_<CONFIG>)指定磁盘上目标文件的位置。附加使用要求可以在 INTERFACE_* 属性中指定。

INTERFACE

不引用磁盘上的任何库或目标文件,但可以在 INTERFACE_* 属性中指定使用要求。

选项包括

GLOBAL

使目标名称全局可见。

未生成用于构建导入目标的规则,并且 IMPORTED 目标属性为 True。导入库对于从 target_link_libraries() 等命令方便引用很有用。

导入库的详细信息通过设置以 IMPORTED_INTERFACE_ 开头的属性来指定。有关更多信息,请参阅此类属性的文档。

别名库

add_library(<name> ALIAS <target>)

创建一个 别名目标,以便 <name> 可以在后续命令中引用 <target><name> 不会作为 make 目标出现在生成的构建系统中。<target> 不能是 ALIAS

在版本 3.11 中新增: ALIAS 可以指向 GLOBAL 导入目标

在版本 3.18 中新增: ALIAS 可以指向非 GLOBAL 导入目标。此类别名作用域限定在创建它的目录及其子目录。可以使用 ALIAS_GLOBAL 目标属性检查别名是否是全局的。

ALIAS 目标可以用作可链接目标,也可以用作读取属性的目标。它们还可以使用常规的 if(TARGET) 子命令进行存在性测试。<name> 不能用于修改 <target> 的属性,也就是说,它不能用作 set_property()set_target_properties()target_link_libraries() 等的操作数。ALIAS 目标不能安装或导出。

另请参阅