cmake构建动态库必须使用add_library(... shared),漏写shared将生成静态库或报错;linux生成libxxx.so,windows生成xxx.dll,需配合target_include_directories、set(library_output_path)、install(targets ... library)等设置头文件路径、输出位置和安装规则。

add_library(... SHARED) 是构建动态库的唯一正确写法
不是用 add_executable,也不是靠改后缀或权限位,CMake 构建动态库必须显式使用 add_library 并指定 SHARED 类型。漏掉这个关键字,哪怕源文件全对、路径全通,最终生成的仍是静态库或报错。
常见错误现象包括:libxxx.a 被意外生成(误用了 STATIC),或者链接时报 undefined reference to `dlopen'(根本没走动态链接流程)。
-
SHARED在 Linux 下生成libxxx.so,在 Windows 下生成xxx.dll(不带lib前缀),macOS 下生成libxxx.dylib - 库名只需写
xxx,前缀和后缀由 CMake 自动补全,硬写libcalc.so会导致构建失败 - 如果源文件中含 Windows 导出符号(如
__declspec(dllexport)),需配合预定义宏(如MYLIB_EXPORT)控制编译行为,否则 Linux 下可忽略
头文件路径和库输出路径必须显式设置
默认情况下,add_library(calc SHARED ...) 只管编译,不负责头文件暴露和产物落盘位置。不设 include_directories,调用方找不到声明;不设输出路径,生成的 .so 可能落在 build/CMakeFiles/... 深层目录里,难以定位和安装。
推荐做法是分两处控制:
- 用
include_directories(${PROJECT_SOURCE_DIR}/include)或更现代的target_include_directories(calc PUBLIC ${PROJECT_SOURCE_DIR}/include)暴露头文件 - 用
set(LIBRARY_OUTPUT_PATH ${PROJECT_BINARY_DIR}/lib)统一指定动态库输出根目录(注意:不是EXECUTABLE_OUTPUT_PATH,后者只影响可执行文件) - 避免用
file(GLOB ...)收集源文件——它不触发增量重编译,改了 .cpp 但没改 CMakeLists.txt 时容易漏更新
动态库链接时 target_link_libraries 的顺序和作用域很关键
构建完动态库只是第一步,调用它的可执行目标必须正确链接。错用 target_link_libraries(myapp calc) 往往失败,原因常出在作用域和依赖传递上。
典型问题:
- 如果
calc库没导出其依赖(比如它自己又用了pthread),而你只写target_link_libraries(myapp calc),链接时可能报undefined reference to `pthread_create' - 在子目录中定义的库(如
add_subdirectory(lib)),主CMakeLists.txt中直接写calc会找不到目标——必须确保add_library(calc SHARED ...)已执行且未加EXCLUDE_FROM_ALL - 正确写法应为:
target_link_libraries(myapp PRIVATE calc),其中PRIVATE表示仅myapp内部使用该链接,不向其依赖者透传
install() 不是可选项,而是部署前提
不加 install(),动态库就只是构建产物,无法被系统级查找(ldconfig)、无法被其他项目 find_package() 发现、也无法打包发布。
最简可用的安装配置:
-
install(TARGETS calc LIBRARY DESTINATION lib)—— 安装动态库到/usr/local/lib(或前缀指定路径下的lib) -
install(DIRECTORY ${PROJECT_SOURCE_DIR}/include/ DESTINATION include)—— 同步安装头文件 - 若省略
LIBRARY关键字而写成install(TARGETS calc DESTINATION lib),Linux 下会安装到lib,但 macOS 可能落到lib,Windows 落到bin,跨平台行为不一致
真正麻烦的是运行时找不到库:即使编译链接全过,./myapp 运行时仍可能报 error while loading shared libraries: libcalc.so: cannot open shared object file。这不是 CMake 问题,而是 LD_LIBRARY_PATH 或 runpath 没配好——这点最容易被忽略,也最难调试。











