【CMake指南】第5篇：跨平台配置与工具链（实现多环境无缝构建）

本文中的相关代码、文件皆为示例。

1. 跨平台路径处理

1.1 统一路径分隔符

# 将路径转换为当前平台的格式
file(TO_CMAKE_PATH "/usr/local/include" NORMALIZED_PATH)
message("转换后路径: ${NORMALIZED_PATH}")  # Windows输出: usr\local\include

1.2 路径拼接最佳实践

# 错误方式（硬编码分隔符）
set(INC_PATH "include/win")  # 在Windows可能失效

# 正确方式（使用CMake自动转换）
set(INC_PATH "${CMAKE_CURRENT_SOURCE_DIR}/include/win")

---

2. 平台相关编译配置

2.1 Windows DLL符号导出（实战示例）

步骤1：定义导出宏（include/utils.h）​

#pragma once

#ifdef _WIN32
    #ifdef UTILS_EXPORTS
        #define API __declspec(dllexport)
    #else
        #define API __declspec(dllimport)
    #endif
#else
    #define API __attribute__((visibility("default")))
#endif

API void print_message(const char* text);

步骤2：CMake配置导出符号

add_library(utils SHARED src/utils.cpp)
if(WIN32)
    target_compile_definitions(utils PRIVATE UTILS_EXPORTS)
else()
    # Linux/macOS设置默认可见性
    set_target_properties(utils PROPERTIES CXX_VISIBILITY_PRESET hidden)
endif()

2.2 平台特定编译选项

# Windows启用UNICODE
if(WIN32)
    add_definitions(-DUNICODE -D_UNICODE)
endif()

# Linux链接数学库
if(UNIX AND NOT APPLE)
    target_link_libraries(myapp m)
endif()

---

3. 自定义工具链文件

3.1 工具链文件模板（arm-toolchain.cmake）

# 指定交叉编译器
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)

# 编译器路径
set(TOOLCHAIN_DIR "/opt/gcc-arm-10.3-2021.07-x86_64-arm-none-linux-gnueabihf")
set(CMAKE_C_COMPILER "${TOOLCHAIN_DIR}/bin/arm-none-linux-gnueabihf-gcc")
set(CMAKE_CXX_COMPILER "${TOOLCHAIN_DIR}/bin/arm-none-linux-gnueabihf-g++")

# 搜索规则
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

3.2 使用工具链文件

cmake -B build -DCMAKE_TOOLCHAIN_FILE=arm-toolchain.cmake

---

4. 交叉编译核心知识点示例：ARM嵌入式开发

4.1 项目结构

embedded/
  ├── CMakeLists.txt
  ├── src/
  │   └── main.cpp
  └── toolchains/
      └── arm-toolchain.cmake

4.2 配置关键步骤

# 指定目标系统环境
set(CMAKE_SYSROOT /opt/sysroot-arm)  # 目标系统的根文件系统

# 禁用本地编译检测
set(CMAKE_CROSSCOMPILING TRUE)

# 配置Qt交叉编译环境（示例）
set(Qt5Core_DIR /opt/Qt-arm/lib/cmake/Qt5Core)

4.3 完整编译流程

# 生成构建系统
cmake -B build -DCMAKE_TOOLCHAIN_FILE=toolchains/arm-toolchain.cmake

# 编译项目
cmake --build build

# 部署到设备
scp build/demo root@192.168.1.100:/app

---

5. 多平台运行时配置

5.1 动态库搜索路径（RPATH）

# 自动添加构建目录到RPATH
set(CMAKE_BUILD_RPATH_USE_ORIGIN TRUE)

# 动态库安装路径配置
set_target_properties(myapp PROPERTIES
    INSTALL_RPATH "$ORIGIN/../lib"
    BUILD_WITH_INSTALL_RPATH FALSE
)

5.2 Windows清单文件（解决DLL依赖）

# 添加manifest文件防止DLL劫持
if(MSVC)
    set(MANIFEST "${CMAKE_CURRENT_SOURCE_DIR}/app.manifest")
    target_sources(myapp PRIVATE ${MANIFEST})
endif()

---

6. 跨平台问题调试指南

6.1 诊断工具链配置

# 查看CMake缓存变量
cat build/CMakeCache.txt | grep "CMAKE_C_COMPILER"

# 检查系统识别结果
message("目标系统: ${CMAKE_SYSTEM_NAME}")

6.2 常见错误解决

1. “Could NOT find OpenSSL”​
   在工具链文件中设置OPENSSL_ROOT_DIR=/opt/openssl-arm

2. ​​“Unsupported compiler”​
   检查CMAKE_C_COMPILER_ID并添加对应编译选项

3. ​​“GLIBCXX version mismatch”​
   在工具链中指定-D_GLIBCXX_USE_CXX11_ABI=0

---

7. 完整工具链示例（Android NDK）

# android-arm64-toolchain.cmake
set(CMAKE_SYSTEM_NAME Android)
set(CMAKE_SYSTEM_VERSION 21)
set(CMAKE_ANDROID_ARCH_ABI arm64-v8a)
set(CMAKE_ANDROID_NDK /opt/android-ndk-r25c)
set(CMAKE_ANDROID_STL_TYPE c++_shared)