把一套多 Provider 的大模型 SDK（ChatGPT / DeepSeek / Gemini / Ollama 各自一个 Provider 类）打包成 Linux 静态库交付，听起来只是"写个 CMakeLists"的事，实际动手会遇到源码管理、依赖宏、安装路径、GLOB 失效一整串问题。这篇按"先跑通、再排错、后验证"的顺序整理一遍完整路径。
源文件管理：手动枚举还是 GLOB_RECURSE
两种方式各有适用面。手动在 add_library 里逐个列出 .cpp：清单一目了然，缺点是每加一个源文件都要改脚本，忘了就"文件存在但没参与编译"，报错却是链接期的 undefined reference，离根因很远。
file(GLOB_RECURSE SDK_SOURCES "src/*.cpp") 递归收集源码，写法省心。但有个经典坑：GLOB 只在 CMake 解析阶段扫一次磁盘，之后新增的文件对构建系统不可见，必须重新 cmake ..。
这里补一个版本差异，很多老教程没写：CMake 3.12 起 GLOB 支持 CONFIGURE_DEPENDS 选项——
file(GLOB_RECURSE SDK_SOURCES CONFIGURE_DEPENDS "src/*.cpp")
加上之后每次执行 make，构建系统会检查目录变化并自动重跑 CMake，新增源文件无需手动重新 configure。代价是官方文档明确提示每次构建多一次目录扫描，超大仓库会拖慢增量构建。3.12 以下的 CMake 只能老实重跑 cmake ..。
可直接使用的 CMakeLists.txt
cmake_minimum_required(VERSION 3.10)
project(ai_chat_sdk)
set(SDK_NAME "ai_chat_sdk")
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_BUILD_TYPE Release)
file(GLOB_RECURSE SDK_SOURCES "src/*.cpp")
file(GLOB_RECURSE SDK_HEADERS "include/*.h")
add_library(${SDK_NAME} STATIC ${SDK_SOURCES} ${SDK_HEADERS})
set(EXECUTABLE_OUTPUT_PATH ${CMAKE_CURRENT_SOURCE_DIR}/build)
target_include_directories(${SDK_NAME} PUBLIC
${CMAKE_CURRENT_SOURCE_DIR}/include)
target_compile_definitions(${SDK_NAME} PUBLIC
CPPHTTPLIB_OPENSSL_SUPPORT)
find_package(OpenSSL REQUIRED)
link_directories(/usr/local/lib)
target_link_libraries(${SDK_NAME}
jsoncpp fmt spdlog sqlite3
OpenSSL::SSL OpenSSL::Crypto)
install(TARGETS ${SDK_NAME} ARCHIVE DESTINATION lib)
install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/
DESTINATION include/ai_chat_sdk
FILES_MATCHING PATTERN "*.h")
几个关键字值得逐个说清：add_library(... STATIC) 产物是 libai_chat_sdk.a；target_include_directories 用 PUBLIC，本库和上层使用方都能看到头文件目录；target_compile_definitions 也用 PUBLIC，宏会传递给链接方——这一点对下面这个宏至关重要。
CPPHTTPLIB_OPENSSL_SUPPORT：不开启就只有 HTTP
SDK 内部用 cpp-httplib 发请求，这个库默认只编入 HTTP 路径，源码里 #ifdef CPPHTTPLIB_OPENSSL_SUPPORT 分支内才会引入 OpenSSL 头文件。调用 HTTPS 接口必须定义这个宏，而且必须通过 target_compile_definitions 定义、不能写进代码里。用 PUBLIC 还有个隐蔽收益：上层项目链接该 SDK 时宏同步生效，否则会出现"SDK 编译时有 HTTPS、上层重编相关翻译单元时没有"的行为分裂，这种 ODR 类问题排错成本极高。
五分钟跑通：编译与安装
cd sdk
mkdir build && cd build
cmake ..
make
sudo make install
装完后的产物位置：静态库在 /usr/local/lib/libai_chat_sdk.a，头文件在 /usr/local/include/ai_chat_sdk/。其他项目 #include <ai_chat_sdk/ChatSDK.h> 后链接 -lai_chat_sdk 即可。
高频报错对照表
| 报错/现象 | 根因 | 处理 |
|---|---|---|
OpenSSL::SSL target was not found |
缺 find_package(OpenSSL REQUIRED)，导入目标不存在 |
在使用 OpenSSL::SSL 之前补上；自定义 OpenSSL 路径还需设 -DOPENSSL_ROOT_DIR=/path/to/openssl |
| Debian/Ubuntu 上找不到 OpenSSL | 只装了运行库没装头文件 | sudo apt install libssl-dev |
cmake_minimum_required should be called prior to project() |
两行顺序写反 | cmake_minimum_required 必须是脚本第一条有效指令 |
make install Permission denied |
写 /usr/local 需要根权限 |
sudo make install，或改 -DCMAKE_INSTALL_PREFIX=$HOME/.local 装到用户目录 |
| 新增源文件没被编译 | GLOB 不监听磁盘变更 | 重新 cmake ..；CMake ≥3.12 可改用 CONFIGURE_DEPENDS |
增量：装完之后怎么确认真的装对了
交付前建议跑三条验证命令，别只看 make 结尾没报错：
# 1. 确认静态库归档内容齐全（应列出所有 Provider 的 .o）
ar -t /usr/local/lib/libai_chat_sdk.a | grep -i provider
# 2. 确认关键符号真的在库内（T = 全局文本符号）
nm /usr/local/lib/libai_chat_sdk.a | grep -E "T.*(ChatSDK|LLMManager)"
# 3. 用一个最小消费工程验证安装路径与宏传递
cat > /tmp/use_sdk.cpp <<'EOF'
#include <ai_chat_sdk/ChatSDK.h>
int main() { return 0; }
EOF
g++ /tmp/use_sdk.cpp -I/usr/local/include/ai_chat_sdk \
-L/usr/local/lib -lai_chat_sdk -o /tmp/use_sdk && echo "consumer OK"
ar -t 验证归档成员，nm 验证符号表，最小消费工程验证头文件与链接路径全链路。三步都过，这个 SDK 才算可交付。顺带说清 install 的 DESTINATION 后缀约定：静态库走 ARCHIVE DESTINATION lib，动态库走 LIBRARY DESTINATION lib，Windows 的 dll 和可执行走 RUNTIME DESTINATION bin——装错后缀是"文件在但链接不到"的常见来源。静态库的本质是 .o 归档，链接期把代码完整复制进可执行文件，部署简单但更新要重编上层；如果 SDK 迭代节奏快、上层项目多，就要在"静态库省心"和"动态库免重编"之间权衡了。
评论0