第 6 章：库的构建与使用

6.1 库的类型总览

类型	CMake 关键字	文件扩展名	链接方式	使用场景
静态库	`STATIC`	`.a` / `.lib`	编译时嵌入	内部工具库、单体部署
动态库	`SHARED`	`.so` / `.dll` / `.dylib`	运行时加载	插件系统、减少体积
对象库	`OBJECT`	`.o` 文件集合	编译时嵌入	避免重复编译
接口库	`INTERFACE`	无	仅传递属性	纯头文件库
模块库	`MODULE`	`.so` / `.dll`	运行时 `dlopen`	插件

6.2 静态库

6.2.1 创建静态库

add_library(mylib STATIC
    src/parser.cpp
    src/lexer.cpp
    src/codegen.cpp
)

target_include_directories(mylib PUBLIC
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
    $<INSTALL_INTERFACE:include>
)

target_compile_features(mylib PUBLIC cxx_std_17)

6.2.2 设置静态库属性

add_library(mylib STATIC src/mylib.cpp)

# 输出名称
set_target_properties(mylib PROPERTIES
    OUTPUT_NAME "mylib"           # libmylib.a
    PREFIX "lib"                  # 前缀
    ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib
)

# PIC（位置无关代码）— 通常静态库不需要
# 但如果静态库要链接到动态库中，则需要
set_target_properties(mylib PROPERTIES POSITION_INDEPENDENT_CODE ON)

6.2.3 控制库的构建

# BUILD_SHARED_LIBS 控制默认库类型
option(BUILD_SHARED_LIBS "Build shared libraries" OFF)

# 这样 add_library 默认创建静态库
add_library(mylib src/mylib.cpp)
# 等价于 add_library(mylib STATIC src/mylib.cpp)

# 用户可以通过 -DBUILD_SHARED_LIBS=ON 来切换为动态库

6.3 动态库（共享库）

6.3.1 创建动态库

add_library(mylib SHARED
    src/parser.cpp
    src/lexer.cpp
)

# 设置版本号
set_target_properties(mylib PROPERTIES
    VERSION "2.1.0"       # 完整版本号 → libmylib.so.2.1.0
    SOVERSION "2"         # SO 版本   → libmylib.so.2
)

# 生成符号可见性头文件
generate_export_header(mylib
    BASE_NAME MYLIB
    EXPORT_MACRO_NAME MYLIB_EXPORT
    EXPORT_FILE_NAME ${CMAKE_CURRENT_BINARY_DIR}/include/mylib/export.h
    STATIC_DEFINE MYLIB_BUILT_AS_STATIC
)

6.3.2 符号导出（Windows 必需）

# CMake 自动生成的 export 头文件
generate_export_header(mylib)

生成的 mylib_export.h：

#ifndef MYLIB_EXPORT_H
#define MYLIB_EXPORT_H

#ifdef MYLIB_STATIC_DEFINE
#  define MYLIB_EXPORT
#  define MYLIB_NO_EXPORT
#else
#  ifndef MYLIB_EXPORT
#    ifdef mylib_EXPORTS
       /* 正在构建共享库 */
#      define MYLIB_EXPORT __declspec(dllexport)
#    else
       /* 正在使用共享库 */
#      define MYLIB_EXPORT __declspec(dllimport)
#    endif
#  endif
#endif

#endif

在源码中使用：

// parser.h
#include "mylib/export.h"

class MYLIB_EXPORT Parser {
public:
    void parse(const std::string& input);
};

// 可选：隐藏某些函数
class Parser {
public:
    MYLIB_EXPORT void publicMethod();
    void privateMethod();  // 不导出
};

6.3.3 动态库版本管理

Linux 上的 SO 版本机制：
libmylib.so → libmylib.so.2 → libmylib.so.2.1.0

libmylib.so.2.1.0   ← 实际文件
libmylib.so.2       ← SONAME（运行时链接器使用）
libmylib.so         ← 开发链接使用（符号链接）

set_target_properties(mylib PROPERTIES
    VERSION ${PROJECT_VERSION}          # 2.1.0
    SOVERSION ${PROJECT_VERSION_MAJOR}  # 2
)

6.3.4 Windows DLL 特殊处理

# Windows 上动态库需要导入库（.lib）
# CMake 自动处理，但需要注意路径
set_target_properties(mylib PROPERTIES
    RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin   # .dll
    ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib   # .lib（导入库）
)

6.4 对象库

6.4.1 基本用法

# 对象库不产生 .a 或 .so 文件
add_library(mylib_objects OBJECT
    src/a.cpp
    src/b.cpp
    src/c.cpp
)

# 设置编译属性（这些属性可以传递给链接者）
target_include_directories(mylib_objects PUBLIC include/)
target_compile_definitions(mylib_objects PUBLIC HAS_FEATURE_X)
target_compile_features(mylib_objects PUBLIC cxx_std_17)

# 使用对象库创建静态库
add_library(mylib_static STATIC $<TARGET_OBJECTS:mylib_objects>)

# 使用对象库创建动态库
add_library(mylib_shared SHARED $<TARGET_OBJECTS:mylib_objects>)

6.4.2 直接链接对象库（CMake 3.12+）

add_library(mylib_objects OBJECT src/a.cpp src/b.cpp)
target_include_directories(mylib_objects PUBLIC include)

# 直接链接，无需 $<TARGET_OBJECTS:>
add_executable(app main.cpp)
target_link_libraries(app PRIVATE mylib_objects)

6.4.3 对象库的传播特性

add_library(mylib_objects OBJECT src/mylib.cpp)
target_include_directories(mylib_objects PUBLIC include)
target_compile_definitions(mylib_objects PRIVATE INTERNAL_DEBUG)

# 链接时，PUBLIC 属性会传播
add_executable(app main.cpp)
target_link_libraries(app PRIVATE mylib_objects)
# app 会获得 include 目录
# app 不会获得 INTERNAL_DEBUG 定义（PRIVATE）

6.5 find_package

6.5.1 基本用法

# 查找 OpenSSL
find_package(OpenSSL REQUIRED)

# 使用找到的库
target_link_libraries(myapp PRIVATE OpenSSL::SSL OpenSSL::Crypto)

6.5.2 Config 模式 vs Module 模式

# find_package 有两种查找模式：
# 1. Config 模式：查找 <PackageName>Config.cmake 或 <lower>-config.cmake
# 2. Module 模式：查找 Find<PackageName>.cmake

# 指定 Config 模式
find_package(OpenSSL CONFIG REQUIRED)

# 指定 Module 模式
find_package(OpenSSL MODULE REQUIRED)

# 两种模式都尝试（默认行为）
find_package(OpenSSL REQUIRED)

6.5.3 查找路径

# 命令行指定
# cmake -S . -B build -DCMAKE_PREFIX_PATH="/opt/deps;/usr/local"

# CMakeLists.txt 中设置
list(APPEND CMAKE_PREFIX_PATH "/opt/deps")

# 专用于某个包
# cmake -S . -B build -DOPENSSL_ROOT_DIR=/opt/openssl

6.5.4 版本约束

# 要求最低版本
find_package(Boost 1.70 REQUIRED)

# 精确版本
find_package(Boost 1.70.0 EXACT REQUIRED)

# 版本范围（CMake 3.19+）
find_package(Boost 1.70...1.85 REQUIRED)

6.5.5 组件

# 查找特定组件
find_package(Boost REQUIRED COMPONENTS filesystem system thread)

# 使用组件
target_link_libraries(myapp PRIVATE
    Boost::filesystem
    Boost::system
    Boost::thread
)

# 可选组件
find_package(Qt6 QUIET COMPONENTS Widgets Network)
if(Qt6_FOUND)
    target_link_libraries(myapp PRIVATE Qt6::Widgets Qt6::Network)
endif()

6.5.6 处理查找结果

find_package(OpenSSL)

if(OpenSSL_FOUND)
    message("OpenSSL 版本: ${OPENSSL_VERSION}")
    message("OpenSSL 包含目录: ${OPENSSL_INCLUDE_DIR}")
    target_link_libraries(myapp PRIVATE OpenSSL::SSL)
else()
    message(WARNING "OpenSSL 未找到，禁用 SSL 功能")
    target_compile_definitions(myapp PRIVATE DISABLE_SSL)
endif()

6.5.7 QUIET 和 REQUIRED

# REQUIRED：找不到则报错
find_package(OpenSSL REQUIRED)

# QUIET：不输出信息
find_package(OpenSSL QUIET)

# 两者结合
find_package(OpenSSL QUIET REQUIRED)

# 先尝试查找，找不到用替代方案
find_package(OpenSSL QUIET)
if(NOT OpenSSL_FOUND)
    message(STATUS "使用内置 OpenSSL 实现")
    add_subdirectory(third_party/boringssl)
endif()

6.6 pkg-config

6.6.1 使用 pkg-config 查找库

# 使用 CMake 的 pkg-config 模块
find_package(PkgConfig REQUIRED)

# 查找单个包
pkg_check_modules(OPENSSL REQUIRED openssl)

# 使用结果
target_include_directories(myapp PRIVATE ${OPENSSL_INCLUDE_DIRS})
target_link_libraries(myapp PRIVATE ${OPENSSL_LIBRARIES})
target_compile_options(myapp PRIVATE ${OPENSSL_CFLAGS_OTHER})

# 使用 IMPORTED 目标（推荐）
pkg_check_modules(OPENSSL REQUIRED IMPORTED_TARGET openssl)
target_link_libraries(myapp PRIVATE PkgConfig::OPENSSL)

6.6.2 多个包

pkg_check_modules(
    MY_DEPS REQUIRED
    IMPORTED_TARGET
    gtk+-3.0
    glib-2.0
    pango
)

target_link_libraries(myapp PRIVATE PkgConfig::MY_DEPS)

6.6.3 静态链接

# 使用静态链接
pkg_check_modules(LIBSSH2 REQUIRED STATIC libssh2)

6.6.4 pkg_check_modules 变量

变量	说明
`<PREFIX>_FOUND`	是否找到
`<PREFIX>_VERSION`	版本号
`<PREFIX>_INCLUDE_DIRS`	包含目录
`<PREFIX>_LIBRARIES`	库文件
`<PREFIX>_LINK_LIBRARIES`	链接库（完整路径）
`<PREFIX>_CFLAGS`	编译标志
`<PREFIX>_CFLAGS_OTHER`	其他编译标志

6.7 find_library

# 查找单个库文件
find_library(MATH_LIBRARY m)
if(MATH_LIBRARY)
    target_link_libraries(myapp PRIVATE ${MATH_LIBRARY})
endif()

# 指定搜索路径
find_library(SSL_LIBRARY
    NAMES ssl libssl
    PATHS /opt/openssl/lib
    NO_DEFAULT_PATH
)

# 查找头文件
find_path(SSL_INCLUDE_DIR
    NAMES openssl/ssl.h
    PATHS /opt/openssl/include
)

6.8 库的链接策略

6.8.1 链接顺序

# 链接顺序很重要（静态库）
# 依赖者放在前面，被依赖者放在后面
target_link_libraries(app PRIVATE mylib utils base pthread)
# 顺序：app → mylib → utils → base → pthread

6.8.2 链接器标志

# 传递链接器选项
target_link_options(mylib PRIVATE
    -Wl,--no-undefined    # 检查未定义符号（Linux）
    -Wl,-z,defs           # 类似效果
)

# 设置链接依赖
set_target_properties(mylib PROPERTIES
    LINK_DEPENDS_NO_SHARED ON  # 不因为共享库变化而重新链接
)

6.8.3 循环依赖

# 静态库之间循环依赖时，需要特殊处理

# 方式一：使用链接组
target_link_libraries(app PRIVATE
    -Wl,--start-group
    libA
    libB
    -Wl,--end-group
)

# 方式二：合并为一个库
target_link_libraries(libA PUBLIC libB)
target_link_libraries(libB PUBLIC libA)

# 方式三：使用对象库（推荐）
add_library(libA OBJECT src/a.cpp)
add_library(libB OBJECT src/b.cpp)
target_link_libraries(libA PUBLIC libB)
target_link_libraries(libB PUBLIC libA)

6.9 业务场景

场景：构建一个可选依赖的库

option(USE_OPENSSL "使用 OpenSSL 支持" ON)
option(USE_ZLIB "使用 zlib 压缩支持" ON)

add_library(mylib src/core.cpp)

if(USE_OPENSSL)
    find_package(OpenSSL REQUIRED)
    target_link_libraries(mylib PUBLIC OpenSSL::SSL)
    target_compile_definitions(mylib PUBLIC HAS_OPENSSL)
endif()

if(USE_ZLIB)
    find_package(ZLIB REQUIRED)
    target_link_libraries(mylib PRIVATE ZLIB::ZLIB)
    target_compile_definitions(mylib PRIVATE HAS_ZLIB)
endif()

6.10 注意事项

问题	说明
静态库不链接其他库	静态库本身不进行链接，链接在最终可执行文件时进行
Windows DLL 符号导出	Windows 上必须显式导出符号
Linux SO 版本	设置 SOVERSION 管理 ABI 兼容性
find_package 顺序	设置 `CMAKE_PREFIX_PATH` 或具体包的 `*_ROOT_DIR`
pkg-config 可能不可用	Windows 上较少使用 pkg-config

6.11 扩展阅读

上一章：第 5 章 — 目标与属性 | 下一章：第 7 章 — 查找模块详解 →

强曰为道

第 6 章：库的构建与使用

第 6 章：库的构建与使用

6.1 库的类型总览

6.2 静态库

6.2.1 创建静态库

6.2.2 设置静态库属性

6.2.3 控制库的构建

6.3 动态库（共享库）

6.3.1 创建动态库

6.3.2 符号导出（Windows 必需）

6.3.3 动态库版本管理

6.3.4 Windows DLL 特殊处理

6.4 对象库

6.4.1 基本用法

6.4.2 直接链接对象库（CMake 3.12+）

6.4.3 对象库的传播特性

6.5 find_package

6.5.1 基本用法

6.5.2 Config 模式 vs Module 模式

6.5.3 查找路径

6.5.4 版本约束

6.5.5 组件

6.5.6 处理查找结果

6.5.7 QUIET 和 REQUIRED

6.6 pkg-config

6.6.1 使用 pkg-config 查找库

6.6.2 多个包

6.6.3 静态链接

6.6.4 pkg_check_modules 变量

6.7 find_library

6.8 库的链接策略

6.8.1 链接顺序

6.8.2 链接器标志

6.8.3 循环依赖

6.9 业务场景

场景：构建一个可选依赖的库

6.10 注意事项

6.11 扩展阅读