跨平台库开发：CMake构建系统、条件编译、平台抽象层、跨平台测试

说实话，跨平台开发这件事，我早年吃过不少亏。那时候刚入行，觉得代码能在Linux上跑通就万事大吉了。结果项目要移植到Windows，好家伙，编译直接挂了三十多个错误。嗯，从那以后我就学乖了——跨平台不是事后补的，得从一开始就设计进去。

这一章，咱们就聊聊怎么用CMake搭一套靠谱的跨平台构建系统，配合条件编译和平台抽象层，让你的库在Linux、macOS、Windows上都能优雅地跑起来。

为什么非得用CMake？

你可能会问：Makefile不也挺好？我个人的看法是，Makefile在单一平台上确实够用，但一旦涉及跨平台，维护成本就直线上升。CMake的好处在于：

• 它生成的是平台原生的构建文件（Linux下是Makefile，Windows下是Visual Studio工程）
• 语法比纯Makefile更高级，支持模块化
• 社区生态好，FindPackage、FetchContent这些功能太实用了

我在一个嵌入式项目里见过有人手写跨平台Makefile，光处理不同编译器的flag就写了200多行。后来换成CMake，50行搞定。你想想看，这差距。

CMake基础结构

一个典型的跨平台库项目，CMakeLists.txt大概长这样：

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

# 设置C++标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 选项控制
option(BUILD_SHARED_LIBS "Build shared libraries" ON)
option(ENABLE_TESTS "Enable unit tests" ON)

# 源文件
set(SOURCES
    src/core.c
    src/platform_linux.c
    src/platform_win.c
    src/platform_mac.c
)

# 根据平台选择源文件
if(WIN32)
    list(REMOVE_ITEM SOURCES src/platform_linux.c src/platform_mac.c)
elseif(APPLE)
    list(REMOVE_ITEM SOURCES src/platform_linux.c src/platform_win.c)
else()
    list(REMOVE_ITEM SOURCES src/platform_win.c src/platform_mac.c)
endif()

# 创建库
add_library(${PROJECT_NAME} ${SOURCES})

# 包含路径
target_include_directories(${PROJECT_NAME}
    PUBLIC
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
        $<INSTALL_INTERFACE:include>
)

# 平台特定链接
if(WIN32)
    target_link_libraries(${PROJECT_NAME} PUBLIC ws2_32)
endif()

# 测试
if(ENABLE_TESTS)
    enable_testing()
    add_subdirectory(tests)
endif()

这里有个细节：$<BUILD_INTERFACE>和$<INSTALL_INTERFACE>是CMake的生成器表达式。说白了就是让头文件路径在编译时和安装后自动切换。我刚开始用的时候也觉得麻烦，但后来发现这玩意儿对库的复用太重要了。

条件编译：别让平台差异污染代码

条件编译是跨平台的最后一道防线。我的原则是：能用CMake解决的，就别用预处理器。但有些场景确实绕不开，比如：

• 不同平台的头文件差异（Windows需要windows.h，Linux不需要）
• 字节序、对齐方式等底层差异
• 特定平台的性能优化

来看一个实际例子：

// platform.h
#ifndef PLATFORM_H
#define PLATFORM_H

// 统一导出宏
#if defined(_WIN32) || defined(_WIN64)
    #define EXPORT __declspec(dllexport)
    #define IMPORT __declspec(dllimport)
    #define PLATFORM_WINDOWS
#elif defined(__linux__)
    #define EXPORT __attribute__((visibility("default")))
    #define IMPORT
    #define PLATFORM_LINUX
#elif defined(__APPLE__)
    #define EXPORT __attribute__((visibility("default")))
    #define IMPORT
    #define PLATFORM_MACOS
#else
    #error "Unsupported platform"
#endif

// 平台抽象：获取当前时间戳
EXPORT uint64_t get_timestamp_ms(void);

#endif

注意看那个#error。我曾经在一个项目里忘了加这个，结果代码被移植到某个嵌入式平台时，编译通过了但运行结果全错。排查了两天才发现是平台宏没定义，默认走了Linux分支。嗯，从那以后我每个平台抽象层都加#error兜底。

平台抽象层：真正的解耦

条件编译只是手段，平台抽象层才是目的。说白了，就是定义一套统一的接口，底层实现各平台自己搞定。这样上层业务代码根本不用关心你在哪个系统上跑。

我习惯把平台抽象层分成三层：

层级	职责	示例
OS抽象	线程、文件、时间、内存	thread_create, file_open, get_time
网络抽象	Socket、DNS、HTTP	socket_connect, dns_resolve
图形抽象	窗口、渲染、输入	window_create, render_frame

来看一个文件操作的抽象层实现：

// file_ops.h
typedef struct FileHandle FileHandle;

EXPORT FileHandle* file_open(const char* path, const char* mode);
EXPORT size_t file_read(FileHandle* f, void* buf, size_t size);
EXPORT void file_close(FileHandle* f);

// file_ops_linux.c
#include <stdio.h>

FileHandle* file_open(const char* path, const char* mode) {
    return (FileHandle*)fopen(path, mode);
}

size_t file_read(FileHandle* f, void* buf, size_t size) {
    return fread(buf, 1, size, (FILE*)f);
}

void file_close(FileHandle* f) {
    fclose((FILE*)f);
}

// file_ops_win.c
#include <windows.h>

FileHandle* file_open(const char* path, const char* mode) {
    // Windows下用CreateFile实现
    HANDLE h = CreateFileA(path, GENERIC_READ, FILE_SHARE_READ,
                           NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
    return (FileHandle*)h;
}

size_t file_read(FileHandle* f, void* buf, size_t size) {
    DWORD bytesRead;
    ReadFile((HANDLE)f, buf, size, &bytesRead, NULL);
    return bytesRead;
}

void file_close(FileHandle* f) {
    CloseHandle((HANDLE)f);
}

你看，上层代码只需要调用file_open，根本不用管底层是fopen还是CreateFile。这就是抽象层的价值。

跨平台测试：别让bug藏到发布后

测试这块，我踩过的坑最多。你以为在Linux上测过了就万事大吉？Windows上的路径分隔符、macOS上的大小写敏感、不同编译器的ABI兼容性……随便一个都能让你翻车。

我的建议是：

• 用CTest做测试框架，它和CMake天然集成
• 每个平台单独跑测试，别偷懒用交叉编译代替
• 关注边界条件：空指针、超大文件、并发访问

一个典型的CTest配置：

# tests/CMakeLists.txt
add_test(NAME test_core COMMAND test_core)
add_test(NAME test_platform COMMAND test_platform)

# 设置测试超时
set_tests_properties(test_platform PROPERTIES TIMEOUT 30)

# 添加自定义测试标签
set_tests_properties(test_core PROPERTIES LABELS "unit;core")

运行测试时，用ctest -C Release指定配置，用ctest -R test_platform只跑特定测试。我一般会在CI里配置三个平台的并行测试，哪个挂了立刻报警。

知识体系总览

下面这张图概括了跨平台库开发的核心逻辑：

好了，跨平台库开发的核心思路就这些。说白了就是：用CMake管好构建，用抽象层管好差异，用测试管好质量。这三板斧抡好了，你的库就能在各大平台上横着走。

---

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