第四章 自动化构建系统：CMake与Makefile在MCU项目中的配置、构建矩阵管理

说实话，做MCU开发这么多年，我见过太多团队还在用手动点IDE按钮的方式编译固件。一个人开发还好说，一旦上了三五个人的团队，或者要维护多个硬件版本，那简直就是灾难。今天我们就来聊聊，怎么用CMake和Makefile把这套流程管起来。

4.1 为什么MCU项目需要自动化构建

你想想看，一个典型的MCU项目，往往要面对这些情况：

  • 同一套代码，要编译出针对不同芯片型号的固件
  • 调试版要开所有断言和日志，发布版要关掉
  • 不同的客户可能需要不同的功能组合
  • CI服务器上可没有IDE给你点

我刚开始带项目的时候，就吃过这个亏。有一次客户要紧急适配一个新芯片，我手动改了十几个地方的宏定义，结果漏了一个，烧进去直接跑飞。嗯，从那以后我就下定决心，必须把构建过程自动化。

核心观点：自动化构建不是锦上添花，而是MCU项目走向工程化的必经之路。它能保证每次构建的可复现性，消除「在我机器上能编译」这种尴尬。

4.2 Makefile：最底层的构建编排

Makefile是C/C++项目的传统构建工具。虽然现在CMake更流行，但Makefile依然是理解构建流程的基础。说白了，Makefile就是告诉编译器「先编译谁，后链接谁」的一张清单。

4.2.1 一个典型的MCU Makefile骨架

# 工具链定义
CROSS_COMPILE = arm-none-eabi-
CC = $(CROSS_COMPILE)gcc
LD = $(CROSS_COMPILE)ld
OBJCOPY = $(CROSS_COMPILE)objcopy

# 项目配置
TARGET = firmware
MCU = cortex-m4
FLAGS = -mcpu=$(MCU) -mthumb -Wall -O2

# 源文件
SRCS = main.c uart.c gpio.c spi.c
OBJS = $(SRCS:.c=.o)

# 编译规则
%.o: %.c
    $(CC) $(FLAGS) -c $< -o $@

# 链接
$(TARGET).elf: $(OBJS)
    $(LD) -T linker.ld $^ -o $@

# 生成hex
$(TARGET).hex: $(TARGET).elf
    $(OBJCOPY) -O ihex $< $@

# 清理
clean:
    rm -f *.o *.elf *.hex

这个骨架看起来简单，但我在实际项目中踩过不少坑。比如那个 -mcpu 参数，不同芯片要配不同的值。STM32F4系列用 cortex-m4，GD32F3系列用 cortex-m3，搞错了编译出来的代码根本跑不起来。

我的习惯：我会在Makefile顶部用变量把所有可配置项列出来，比如芯片型号、优化等级、是否开启调试输出。这样换芯片时只需要改几个变量，不用满文件找。

4.3 CMake：跨平台的构建系统生成器

Makefile虽然好用，但跨平台能力太弱。Windows上用MinGW，Linux上用GCC，macOS上又是另一套。CMake的出现解决了这个问题——它不直接编译，而是生成对应平台的构建文件。

4.3.1 CMakeLists.txt的基本结构

cmake_minimum_required(VERSION 3.10)
project(mcu_firmware C ASM)

# 设置工具链
set(CMAKE_C_COMPILER arm-none-eabi-gcc)
set(CMAKE_ASM_COMPILER arm-none-eabi-gcc)

# 芯片配置
set(MCU_FAMILY "STM32F4")
set(MCU_MODEL "STM32F407VG")

# 编译选项
add_compile_options(
    -mcpu=cortex-m4
    -mthumb
    -Wall
    -Wextra
    $<$IF>$<CONFIG:Debug>,-O0 -g3,-O2>
)

# 源文件
file(GLOB_RECURSE SOURCES
    src/*.c
    src/*.s
    drivers/*.c
)

# 头文件路径
include_directories(
    inc
    drivers/inc
    cmsis
)

# 生成目标
add_executable(${PROJECT_NAME}.elf ${SOURCES})

# 链接脚本
target_link_options(${PROJECT_NAME}.elf PRIVATE
    -T ${CMAKE_SOURCE_DIR}/linker/${MCU_MODEL}.ld
)

# 生成hex文件
add_custom_command(TARGET ${PROJECT_NAME}.elf POST_BUILD
    COMMAND ${CMAKE_OBJCOPY} -O ihex ${PROJECT_NAME}.elf ${PROJECT_NAME}.hex
)

你看，CMake用 add_compile_options 和 target_link_options 把编译和链接参数管理得清清楚楚。而且它支持条件判断，比如调试版用 -O0 -g3，发布版用 -O2，这个在Makefile里写起来就麻烦多了。

4.4 构建矩阵管理：一套代码，多目标输出

这才是自动化构建的精髓。什么叫构建矩阵？就是用一个配置文件，定义出所有可能的构建组合，然后批量生成。

4.4.1 用CMake实现构建矩阵

# 定义构建矩阵
set(BUILD_MATRIX
    "STM32F407;Debug;UART_ENABLED"
    "STM32F407;Release;UART_ENABLED"
    "STM32F407;Debug;UART_DISABLED"
    "STM32F103;Debug;UART_ENABLED"
    "STM32F103;Release;UART_ENABLED"
)

# 遍历矩阵生成目标
foreach(CONFIG IN LISTS BUILD_MATRIX)
    # 解析配置
    string(REPLACE ";" ";" ITEMS ${CONFIG})
    list(GET ITEMS 0 CHIP)
    list(GET ITEMS 1 BUILD_TYPE)
    list(GET ITEMS 2 UART_CONFIG)

    # 设置输出目录
    set(OUTPUT_DIR "build/${CHIP}/${BUILD_TYPE}/${UART_CONFIG}")

    # 创建子构建
    add_subdirectory(
        src
        ${OUTPUT_DIR}
        EXCLUDE_FROM_ALL
    )

    # 设置目标属性
    set_target_properties(${PROJECT_NAME}.elf PROPERTIES
        COMPILE_DEFINITIONS "MCU_${CHIP};${BUILD_TYPE};${UART_CONFIG}"
    )
endforeach()

这段代码我用了好几年了。每次新项目来了，我只需要往 BUILD_MATRIX 里加一行，CMake就会自动生成对应的构建目录和编译参数。曾经有个项目要支持6种芯片、3种功能组合，总共18个固件版本，用这个矩阵管理，一次配置，一键生成。

注意：构建矩阵不是越大越好。每增加一个维度，编译时间就会翻倍。我建议把经常变动的参数（如芯片型号、功能开关）放在矩阵里，而像优化等级这种，用CMake的预设配置（Debug/Release）来管理就够了。

4.5 实战中的避坑指南

讲了这么多理论，来点实际的。我在MCU自动化构建上踩过的坑，今天一次性分享出来。

4.5.1 工具链路径问题

不同开发者的电脑上，arm-none-eabi-gcc的安装位置可能不一样。有人装在 /usr/local/bin，有人装在 /opt/gcc-arm。我建议在CMake里用 find_program 来查找，而不是硬编码路径。

find_program(ARM_GCC arm-none-eabi-gcc)
if(NOT ARM_GCC)
    message(FATAL_ERROR "ARM GCC not found!")
endif()
set(CMAKE_C_COMPILER ${ARM_GCC})

4.5.2 链接脚本的管理

每个芯片都有自己的链接脚本，而且不同版本的芯片可能还不一样。我曾经犯过一个错误：把所有链接脚本放在同一个目录，结果STM32F407和STM32F405的脚本搞混了，烧进去芯片直接不工作。

现在我这样管理：

linker/
├── STM32F407VG.ld
├── STM32F405RG.ld
├── STM32F103C8.ld
└── GD32F303CC.ld

然后在CMake里根据芯片型号自动选择：

target_link_options(${PROJECT_NAME}.elf PRIVATE
    -T ${CMAKE_SOURCE_DIR}/linker/${MCU_MODEL}.ld
)

4.5.3 缓存问题

CMake会缓存之前的配置。如果你改了芯片型号，但忘了清理缓存，它可能还在用旧的配置编译。我习惯在构建脚本里加一句：

# 每次构建前清理缓存
if(EXISTS ${CMAKE_BINARY_DIR}/CMakeCache.txt)
    file(REMOVE ${CMAKE_BINARY_DIR}/CMakeCache.txt)
endif()

4.6 与CI/CD的集成

自动化构建做好了，跟CI/CD集成就是水到渠成的事。在Jenkins或GitLab CI里，只需要几行配置：

# .gitlab-ci.yml 示例
build_matrix:
  script:
    - mkdir -p build
    - cd build
    - cmake .. -DCMAKE_BUILD_TYPE=Debug
    - cmake --build . --target all
  artifacts:
    paths:
      - build/*.hex

这样每次代码提交，CI服务器就会自动编译所有固件版本。如果某个版本编译失败，邮件通知会直接发到你的邮箱。嗯，再也不用半夜爬起来手动编译了。

我的建议：刚开始做自动化构建时，不要追求一步到位。先把手动编译的流程写成Makefile，再迁移到CMake，最后加入构建矩阵。每一步都验证通过后，再接入CI。这样出了问题，你能快速定位是哪个环节的锅。

好了，这一章的内容就到这里。自动化构建看起来复杂，但一旦搭好框架，后续的维护成本会直线下降。下一章我们会聊聊MCU项目的单元测试，那又是一个让人又爱又恨的话题。

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