📚 课程目录第3章开发环境搭建

3. 开发环境搭建：跨平台工具链配置

做跨平台SDK，最头疼的就是环境。Windows上好好的，一到macOS就报链接错误。你想想看，每个平台都有自己的构建习惯——Xcode认xcodeproj，Visual Studio认sln，Linux上大家又习惯写Makefile。总不能每个平台单独维护一套工程吧？

所以就有了元构建系统。说白了，就是用一个描述文件，自动生成各平台的原生工程。CMake是目前事实上的标准。我个人习惯用CMake + Ninja组合，编译速度快，而且能统一命令行流程。下面我把几个常用工具链的配置经验串起来讲。

3.1 工具链全景图

先看一张整体结构图，帮你在脑子里搭个框架：

小建议： 如果你团队里有人只用Xcode，有人只用VS，统一用CMake + 命令行构建。CI/CD 里跑 Ninja，本地开发用各自 IDE 打开生成的工程文件——互不干扰。

3.2 CMake 安装与基本配置

CMake 官网下载二进制包就行。Windows 上记得勾选“Add CMake to system PATH”。macOS 我推荐 brew install cmake。Linux 各发行版源里都有，但版本可能偏老——我曾经在 Ubuntu 18.04 上遇到 CMake 3.10 不支持某些新语法，最后手动装 3.20 才解决问题。

写一个最简单的 CMakeLists.txt：

cmake_minimum_required(VERSION 3.16)
project(MySDK VERSION 1.0.0 LANGUAGES C CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_library(mylib SHARED src/mylib.cpp)
target_include_directories(mylib PUBLIC include)

这里有几个坑。第一，CMAKE_CXX_STANDARD 最好明确指定，否则不同平台默认值不一样。第二，别用 add_definitions(-DXXX)，用 target_compile_definitions 更精细。

3.3 Ninja —— 轻量级构建器

Ninja 的设计哲学就一个字：快。它没有 Makefile 那些复杂推导，只管跑编译任务。我在一个大型项目上测过，Ninja 比 Make 快 30%-50%，尤其是增量编译。

安装：Windows 下载 ninja.exe 放 PATH；macOS brew install ninja；Linux 包管理器直接装。然后 CMake 生成 Ninja 工程：

cmake -B build -G "Ninja" -DCMAKE_BUILD_TYPE=Release
cmake --build build

注意：-G "Ninja" 必须写对。如果系统没装 Ninja，CMake 会报错“Could not find Ninja”。我建议把 Ninja 装在标准位置，或设置 CMAKE_MAKE_PROGRAM。

3.4 Visual Studio 生成器

Windows 上开发，Visual Studio 是绕不开的。CMake 默认会检测 VS 版本。如果想指定 2022：

cmake -B build -G "Visual Studio 17 2022" -A x64

-A x64 指定架构，别漏掉。我曾经接手过一个项目，同事忘了加 -A，结果生成的是 Win32 工程，链接时符号找不到……排查半天。

Visual Studio 版本	CMake 生成器名	架构参数 (-A)
VS 2019	Visual Studio 16 2019	Win32 / x64 / ARM64
VS 2022	Visual Studio 17 2022	Win32 / x64 / ARM64
VS 2022 (工具集 v143)	Visual Studio 17 2022	同上

注意： 用 VS 生成器时，CMake 会自动选默认工具集。如果你装了多个 VS 版本，可以用 -T v142 指定。但小心——跨版本工具集可能导致 ABI 不兼容。

3.5 Xcode 生成器

macOS 上，Xcode 是首选 IDE。CMake 生成 Xcode 工程很简单：

cmake -B build -G "Xcode" -DCMAKE_OSX_SYSROOT=macosx

不过要注意：CMAKE_OSX_SYSROOT 最好显式指定，否则可能飘到 iOS 或 watchOS 的 SDK 上。我之前踩过这个坑——在 macOS 13 上生成项目，默认 SDK 是 macOS 14，但部署目标机器是 macOS 12，结果 macOS 14 的 API 在旧系统上崩溃。解决方法：

cmake -B build -G "Xcode" \
    -DCMAKE_OSX_DEPLOYMENT_TARGET=12.0 \
    -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX14.sdk

3.6 跨平台配置清单

我整理了一个表格，每次新建项目时对照着检查：

配置项	建议值	原因
C++ 标准	C++17 或 C++20	各平台编译器都支持了
构建类型	Release / Debug	别漏了 RelWithDebInfo 用于分析
安装前缀	`CMAKE_INSTALL_PREFIX`	统一输出目录
共享库后缀	自动（.dll/.dylib/.so）	CMake 处理
运行时库(MSVC)	`/MD` 或 `/MT`	混用会导致崩溃

个人心得： 把上述配置写进一个 cmake/compiler_settings.cmake 文件里，然后用 include() 包含。不同项目复用，省事。

3.7 避坑指南：工具链检测与缓存

CMake 第一次运行会检测编译器，并把结果缓存到 CMakeCache.txt。如果你换编译器或 SDK，记得删掉 build 目录重新生成。我曾经在同一个构建目录切换 VS 版本，结果链接器报错，清空重来就好了。

另一个常见问题是跨平台条件编译。比如 Windows 需要 dllexport，Linux 不需要。可以这样处理：

#include <Export.h>
#if defined(_WIN32)
  #define MY_API __declspec(dllexport)
#else
  #define MY_API __attribute__((visibility("default")))
#endif

但更好的做法是在 CMake 里定义导出宏：

target_compile_definitions(mylib PRIVATE MYLIB_EXPORTS)

然后在代码里用 #ifdef MYLIB_EXPORTS 做条件。嗯，这样更干净，不会污染用户代码。

3.8 总结一下工具链选择

本地开发： Windows 用 VS 生成器，macOS 用 Xcode 生成器，Linux 用 Ninja 或 Unix Makefiles。
CI/CD： 统一用 Ninja，跨平台且无界面依赖。GitHub Actions 或 Jenkins 上跑 cmake -G Ninja 最简单。
跨平台调试： 有个技巧——在 Windows 上用 Ninja + Clang-cl 能模拟很多 Linux 下的行为，减少平台差异。

核心原则： 用 CMake 做一次描述，用 Ninja 做统一构建，用平台原生工程做局部调试。三句话搞定环境搭建。

我见过不少团队在“用什么生成器”上反复横跳。其实不用纠结：把 CMakeLists.txt 写扎实了，生成器只是个参数。你甚至可以一条命令跑所有平台：cmake -B build -G "$GENERATOR"，在脚本里根据 uname 或环境变量设置 GENERATOR。真正做到一次编写，到处编译。