📚 课程目录第4章环境准备

环境准备：操作系统兼容性、依赖库安装、编译工具链

说到SDK开发环境准备，很多新手会觉得不就是装个IDE嘛？其实这里面坑不少。我早期做跨平台SDK时，就因为在Windows上用了不兼容的编译器版本，导致客户集成时链接失败，折腾了两天才定位到问题。所以这一章咱们把环境准备掰开揉碎讲清楚。

操作系统兼容性怎么选

一个成熟的SDK往往要覆盖三大平台：Windows、macOS、Linux。我个人习惯优先评估Linux环境，因为服务器端和嵌入式设备几乎都是Linux。

重点关注的几项：

内核版本：比如glibc版本必须向下兼容，否则在旧系统上直接报错。
架构差异：x86_64、ARM、ARM64需要分别编译。
系统ABI：Linux OneCore、Android Bionic libc等，不同ABI的符号表规则差异明显。

我在项目中遇到过，某个第三方加密库只支持glibc 2.28以上，而客户服务器还是CentOS 7（glibc 2.17）。最后只能静态链接避开依赖。

操作系统	最低版本要求	注意事项
Ubuntu/Debian	glibc ≥ 2.23	避免使用Ubuntu 16.04以下版本
CentOS/RHEL	glibc ≥ 2.17	需额外安装devtoolset-9
macOS	≥ 10.14 (Mojave)	Xcode版本必须对齐
Windows	Windows 10 1809+	Visual Studio 2019及以上

我曾经在macOS 11（Big Sur）上编译的库，拿到macOS 10.14上跑，直接报“Library not loaded: @rpath/libxxx.dylib”。原因就是系统动态链接器版本不兼容。所以一定要在最低支持的OS版本上做集成测试。

依赖库安装

SDK的依赖通常分为两类：基础依赖和业务依赖。基础依赖包括libc、zlib、openssl这些；业务依赖就看你的SDK是做什么的了，比如网络SDK可能依赖libcurl、openssl。

基础依赖清单

zlib（压缩）
OpenSSL / BoringSSL（加密传输）
libcurl（HTTP请求）
protobuf / flatbuffers（序列化）
libuv / libevent（事件循环）

安装方式上，我建议用包管理器配合vcpkg/conan，而不是直接下载源码编译。举个例子：

# Ubuntu
sudo apt install -y build-essential cmake libssl-dev libcurl4-openssl-dev
# macOS
brew install cmake openssl curl protobuf
# Windows (vcpkg)
vcpkg install openssl curl protobuf --triplet x64-windows-static

注意，很多开发者喜欢用系统包管理器的OpenSSL，但我在项目中发现系统默认版本可能不支持TLS 1.3。如果SDK要对接高安全场景，建议自己编译OpenSSL 1.1.1+。

网络库依赖的特殊处理

你想想看，网络库是SDK的“嘴和耳朵”，选错了后面的架构设计全白瞎。我曾经踩过一个坑：用libcurl做多线程请求时，没注意它默认的DNS解析是同步阻塞的，结果在并发场景下直接挂死。

所以我对网络库的依赖原则是：

必须支持异步DNS（比如c-ares）
必须支持连接复用（HTTP/2 multiplexing）
必须支持TLS双向认证（mTLS）

如果你的SDK要跑在嵌入式或IoT设备上，记得检查libc版本。比如OpenWRT用的是musl libc，很多glibc特有的函数（如alloca）在musl下行为不同。

编译工具链

工具链这步做对了，后续的工作能省一半力气。我一般会准备三套工具链：

本地编译工具链：用于开发调试，速度第一。
交叉编译工具链：为嵌入式、ARM、MIPS等目标平台准备。
CI/CD工具链：自动化测试和发版使用，必须与环境完全隔离。

LLVM vs GCC

我个人的偏好是：macOS默认用Apple Clang（基于LLVM），Linux用GCC。虽然LLVM的编译速度和报错信息比GCC好，但GCC对C++异常处理和二进制兼容性更好。做过一次SDK才知道，GCC和Clang混编的C++ ABI兼容性有一堆坑，比如std::string的copy-on-write实现不一样，链接时直接Segfault。

特性	GCC	LLVM/Clang
C++ ABI稳定性	较好（Itanium ABI）	次之（vs2015之后有差异）
编译速度	中等	较快
错误提示	泛泛	清晰友好
交叉编译支持	成熟（很多嵌入式厂商提供GCC）	需要自己配置toolchain

CMake配置最佳实践

写CMakeLists.txt时，我习惯把工具链配置单独抽成一个cmake/toolchain.cmake文件。比如：

# 交叉编译：target=ARM64
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_C_COMPILER   aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
set(CMAKE_FIND_ROOT_PATH /usr/aarch64-linux-gnu)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

构建时用 cmake -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain.cmake .. 即可切换。这样源码里没有任何平台判断，干净利落。

SVG：环境准备核心逻辑图

避坑清单

作为开发者，你肯定会遇到这些问题，我先帮你列出来：

glibc版本不兼容：编译时是glibc 2.31，客户环境是2.17，运行时直接version GLIBC_2.28' not found。解决方案：在最低目标系统上编译。
CMake找不到依赖：明明apt安装了libcurl，find_package还是失败。试试指定路径set(CURL_DIR /usr/lib/x86_64-linux-gnu/cmake)。
静态库vs动态库：给客户提供动态库时，一定要检查所有动态依赖是否存在。我习惯再加一句：用ldd跑一遍，确认没有“not found”。
交叉编译头文件路径：设了CMAKE_CXX_FLAGS但不改CMAKE_FIND_ROOT_PATH，结果链接器找不到target的libc。用CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY搞定。

总结

环境准备说白了就是三步走：选对OS版本、装对依赖库、搭对工具链。每一步听起来简单，但实际项目中的边角问题特别多。我自己的习惯是：写一个 env_check.sh 脚本，在CI中自动校验gcc版本、glibc版本、依赖库路径、链接器行为。跑通这个脚本，环境就算备好了。