跨平台构建：Windows (MSVC)、Linux (GCC/Clang)、macOS (Xcode) 的 CMake 适配

跨平台构建，说白了就是让你的 C++ 代码能在 Windows、Linux、macOS 上都能编译通过，并且跑得一样好。我见过太多项目，在 Linux 上跑得飞起，一到 Windows 就编译报错，或者反过来。嗯，这其实不是代码逻辑的问题，而是构建系统没有做好适配。

CMake 是目前最主流的跨平台构建工具。它不直接生成可执行文件，而是生成对应平台的构建文件——在 Windows 上生成 Visual Studio 的 .sln 解决方案，在 Linux 上生成 Makefile，在 macOS 上生成 Xcode 项目。你想想看，一套 CMakeLists.txt，就能搞定三个平台，省了多少事。

CMake 的平台检测与条件编译

CMake 提供了几个内置变量，用来检测当前构建平台。我个人习惯用 WIN32、APPLE、UNIX 这三个，简单直接。

# 检测操作系统
if(WIN32)
    message(STATUS "当前平台: Windows")
    add_definitions(-DPLATFORM_WINDOWS)
elseif(APPLE)
    message(STATUS "当前平台: macOS")
    add_definitions(-DPLATFORM_MACOS)
elseif(UNIX)
    message(STATUS "当前平台: Linux/Unix")
    add_definitions(-DPLATFORM_LINUX)
endif()

这里要注意，UNIX 在 macOS 上也是 true，所以要先判断 APPLE，再判断 UNIX。我在项目中遇到过有人把顺序写反了，结果 macOS 被当成了 Linux 处理，编译出来的东西路径全不对。

编译器检测与宏定义

除了平台，编译器也要区分。MSVC、GCC、Clang 的语法和特性支持程度不一样。CMake 用 CMAKE_CXX_COMPILER_ID 来识别。

# 检测编译器
if(MSVC)
    message(STATUS "编译器: MSVC")
    add_compile_definitions(COMPILER_MSVC)
elseif(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
    message(STATUS "编译器: GCC")
    add_compile_definitions(COMPILER_GCC)
elseif(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
    message(STATUS "编译器: Clang")
    add_compile_definitions(COMPILER_CLANG)
endif()

为什么需要区分编译器？举个例子，MSVC 对 C++ 标准的支持比较慢，C++17 的某些特性在 GCC 上早就有了，MSVC 可能还要等几个版本。我曾经在项目中用 std::filesystem，GCC 和 Clang 都好好的，MSVC 2017 却报错——后来发现需要额外链接 stdc++fs 库。

平台宏与条件编译

在 C++ 代码里，我们通过预处理器宏来做条件编译。CMake 负责定义这些宏，代码里根据宏来写不同的实现。

// 跨平台的文件路径处理
#ifdef PLATFORM_WINDOWS
    #include <windows.h>
    std::string getHomeDir() {
        char* buf = nullptr;
        size_t sz = 0;
        _dupenv_s(&buf, &sz, "USERPROFILE");
        std::string result(buf ? buf : "");
        free(buf);
        return result;
    }
#elif defined(PLATFORM_LINUX) || defined(PLATFORM_MACOS)
    #include <unistd.h>
    #include <pwd.h>
    std::string getHomeDir() {
        const char* home = getenv("HOME");
        if (home) return std::string(home);
        struct passwd* pw = getpwuid(getuid());
        return pw ? std::string(pw->pw_dir) : "";
    }
#endif

你看，同一个函数，三个平台用了三种不同的系统 API。Windows 用 USERPROFILE 环境变量，Linux 和 macOS 用 HOME 环境变量。这就是条件编译的典型场景。

核心原则：平台相关的代码要尽量隔离，不要散落在业务逻辑里。我建议把所有平台适配代码集中到单独的源文件中，比如 platform_utils_win.cpp、platform_utils_linux.cpp，然后用 CMake 根据平台选择编译哪个文件。

CMake 的生成器表达式

生成器表达式是 CMake 的高级特性，它可以在构建时（而不是配置时）决定某些值。我个人觉得这是 CMake 最强大的功能之一。

# 不同平台链接不同的库
target_link_libraries(myapp
    PRIVATE
    $<$<PLATFORM_ID:Windows>:ws2_32>
    $<$<PLATFORM_ID:Linux>:pthread>
    $<$<PLATFORM_ID:Darwin>:>
)

# 不同编译器设置不同的编译选项
target_compile_options(myapp
    PRIVATE
    $<$<CXX_COMPILER_ID:MSVC>:/W4 /utf-8>
    $<$<CXX_COMPILER_ID:GNU>:-Wall -Wextra>
    $<$<CXX_COMPILER_ID:Clang>:-Wall -Wextra -Wpedantic>
)

生成器表达式的语法有点怪，$<$<条件>:值> 这种嵌套写法，我第一次看的时候也懵了。但用熟了之后，你会发现它比 if/endif 更灵活，尤其是在处理接口库（INTERFACE 库）的时候。

macOS 的特殊处理：Xcode 与 Framework

macOS 上除了用 Clang 编译器，还有一个特殊的东西叫 Framework。Framework 是苹果封装库和资源的方式，跟 Linux 的 .so 和 Windows 的 .dll 不太一样。

# macOS 上链接 Framework
if(APPLE)
    find_library(COCOA_LIBRARY Cocoa)
    find_library(IOKIT_LIBRARY IOKit)
    target_link_libraries(myapp
        PRIVATE
        ${COCOA_LIBRARY}
        ${IOKIT_LIBRARY}
    )
    
    # 设置 macOS 的应用属性
    set_target_properties(myapp PROPERTIES
        MACOSX_BUNDLE TRUE
        MACOSX_BUNDLE_GUI_IDENTIFIER "com.example.myapp"
        MACOSX_BUNDLE_BUNDLE_VERSION "1.0.0"
        MACOSX_BUNDLE_SHORT_VERSION_STRING "1.0"
    )
endif()

我记得第一次在 macOS 上构建 GUI 应用时，忘了链接 Cocoa Framework，结果编译通过了，但运行时窗口死活显示不出来。查了半天才发现是 Framework 没链接上。

Windows 的特殊处理：DLL 导出与运行时库

Windows 上最让人头疼的是 DLL 导出和运行时库（Runtime Library）的选择。MSVC 的运行时库有 /MD（动态多线程）、/MT（静态多线程）、/MDd（调试版动态）、/MTd（调试版静态）四种。混用会导致链接错误。

# Windows 上统一运行时库
if(MSVC)
    # 统一使用动态运行时库
    set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreadedDLL")
    
    # 导出宏定义
    add_compile_definitions(MYAPP_EXPORTS)
    
    # 设置 Windows 子系统
    if(BUILD_GUI)
        set_target_properties(myapp PROPERTIES
            WIN32_EXECUTABLE TRUE
        )
    endif()
endif()

注意：运行时库的选择必须统一。如果你在静态库（.lib）里用了 /MT，而主程序用了 /MD，链接时会报 LNK2038 错误。我曾经在一个大项目里排查了整整两天，才发现是第三方库的运行时库跟主程序不一致。

条件编译的常见陷阱

条件编译虽然好用，但用不好就是灾难。我总结了几条经验：

  • 不要滥用 #ifdef：条件编译太多会让代码变得难以阅读和维护。能用多态解决的，就别用预处理器。
  • 宏命名要规范：平台宏建议用 PLATFORM_ 前缀，编译器宏用 COMPILER_ 前缀，避免跟第三方库的宏冲突。
  • 提供默认实现：如果某个平台没有特殊处理，至少提供一个 fallback 实现，而不是直接报错。
  • 测试所有平台：不要只在你的开发机上测试。CI/CD 里配置三个平台的构建任务，每次提交都跑一遍。

知识体系总览

下面这张图总结了跨平台构建的核心知识点，从 CMake 配置到底层代码实现，一目了然。

跨平台构建知识体系 CMake 配置层 CMakeLists.txt · 平台检测 · 编译器检测 · 生成器表达式 平台适配层 Windows: MSVC · DLL · 运行时库 Linux: GCC/Clang · .so · pthread macOS: Clang · Framework · Bundle 代码实现层 条件编译 · 平台宏 · 系统API封装 · 文件路径处理 CI/CD 验证层 GitHub Actions · Jenkins · 三平台自动构建与测试

我的建议：刚开始做跨平台适配时，不要追求一步到位。先在 Linux 上把核心功能跑通，然后移植到 macOS，最后处理 Windows。每移植一个平台，就写一个对应的 CMake 模块，比如 cmake/PlatformWindows.cmake，这样主 CMakeLists.txt 会干净很多。

跨平台构建不是一蹴而就的事。你想想看，每个平台都有自己的系统调用、库管理方式、文件路径分隔符，甚至换行符都不一样。但有了 CMake 和条件编译这两把利器，再加上合理的架构设计，这些差异都可以被优雅地封装起来。

我在一个大型游戏引擎项目中，用这套方法同时支持了 Windows、Linux、macOS 三个平台，甚至还包括了 Android 和 iOS。核心代码只有一份，平台相关的代码不到 5%。这才是跨平台构建的理想状态。

公众号:蓝海资料掘金营，微信deep3321

← 上一章 📖 返回目录 下一章 →