单片机与物联网 / 系统课时

工程配置与版本管理

工程配置与版本管理

本课解决同一份单片机源码在不同电脑、不同构建模式下结果不一致的问题。你将建立清晰的目录与配置边界,用 CMake 固化编译参数,并通过 Git 提交、标签和发布记录追踪每个可交付固件。

学习目标

  • 组织源码、配置、测试和构建产物,避免文件职责混乱。
  • 使用 CMake 缓存变量生成可追踪的构建配置。
  • 使用 Git 提交、注释标签和发布记录管理固件版本。

组织目录与配置边界

源码仓库只保存可审查、可复现的输入,不保存编译器临时文件和本机绝对路径。推荐把公共头文件、业务源码、配置模板、测试代码和辅助脚本分开,所有构建产物统一放入仓库外或已忽略的 build 目录。

text
firmware/
├── CMakeLists.txt
├── config/
│   └── build_config.h.in
├── include/
├── src/
│   └── main.c
├── tests/
├── scripts/
├── docs/
└── .gitignore

嵌入式工程配置到版本发布的数据流

.gitignore 应忽略 build/、编辑器缓存、日志和本机生成文件,但不能忽略构建脚本、链接脚本、配置模板和测试数据。密钥、生产证书和设备唯一凭据不应进入 Git,应由受控发布环境注入。

用 CMake 固化编译配置

下面的最小工程通过 FW_LOG_LEVEL 和 FW_FEATURE_DIAGNOSTICS 生成头文件。相同的配置命令会得到相同的宏定义,后续替换为交叉编译工具链时仍可沿用这一结构。

将以下内容保存为 CMakeLists.txt:

cmake
cmake_minimum_required(VERSION 3.20)
project(firmware_demo C)

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)
set(FW_LOG_LEVEL "2" CACHE STRING "Firmware log level")
option(FW_FEATURE_DIAGNOSTICS "Enable diagnostics" OFF)

if(FW_FEATURE_DIAGNOSTICS)
    set(FW_FEATURE_DIAGNOSTICS_VALUE 1)
else()
    set(FW_FEATURE_DIAGNOSTICS_VALUE 0)
endif()

configure_file(
    config/build_config.h.in
    generated/build_config.h
    @ONLY
)

add_executable(firmware_demo src/main.c)
target_include_directories(
    firmware_demo
    PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/generated
)

if(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
    target_compile_options(firmware_demo PRIVATE -Wall -Wextra -Werror)
endif()

将配置模板保存为 config/build_config.h.in:

c
#ifndef BUILD_CONFIG_H
#define BUILD_CONFIG_H

#define FW_LOG_LEVEL @FW_LOG_LEVEL@
#define FW_FEATURE_DIAGNOSTICS @FW_FEATURE_DIAGNOSTICS_VALUE@

#endif

将程序保存为 src/main.c:

c
#include <stdio.h>

#include "build_config.h"

int main(void) {
    printf("log_level=%d\n", FW_LOG_LEVEL);
    printf(
        "diagnostics=%s\n",
        FW_FEATURE_DIAGNOSTICS ? "on" : "off"
    );
    return 0;
}

配置、构建并运行:

bash
cmake -S . -B build/debug -DFW_LOG_LEVEL=3 -DFW_FEATURE_DIAGNOSTICS=ON
cmake --build build/debug
./build/debug/firmware_demo

预期输出中,CMake 的编译日志会随平台和编译器变化,程序输出应稳定为:

text
log_level=3
diagnostics=on

嵌入式交叉编译时,可额外传入 -DCMAKE_TOOLCHAIN_FILE=<PATH>。<PATH> 的实际值可能不同;仓库应保存工具链文件或可定位 SDK 的脚本,而不是提交某位开发者电脑上的绝对目录。

隔离构建模式与生成文件

调试版可以开启断言、日志和诊断命令,发布版则应关闭测试入口并启用尺寸或速度优化。不同模式必须使用独立构建目录,例如 build/debug 与 build/release,避免旧对象文件和缓存变量污染新固件。

生成的 build_config.h、对象文件、映射文件和最终固件通常不直接提交。发布时应保存构建命令、工具链版本、源代码标签、测试结果和固件哈希,使任何人都能确认“这个二进制由哪次提交、哪组参数生成”。

使用 Git 管理提交与标签

提交应围绕一个可审查变更,避免把格式化、功能修改和生成文件混在一起。下面的命令初始化仓库、创建首次提交并为可发布状态建立注释标签。

bash
git init -b main
git config user.name "Firmware Team"
git config user.email "firmware@example.invalid"
git add CMakeLists.txt config src
git commit -m "feat: add reproducible firmware configuration"
git tag -a v1.0.0 -m "release: v1.0.0"
git log --oneline --decorate -1

预期输出:

text
<COMMIT> (HEAD -> main, tag: v1.0.0) feat: add reproducible firmware configuration

<COMMIT> 是实际提交哈希的缩写,每次仓库内容不同都会变化。发布标签应指向已通过测试的提交;标签建立后若发现问题,应修复并创建新版本,而不是强制移动已经对外发布的标签。

推荐在发布记录中至少写明版本号、目标板卡、工具链版本、构建模式、配置差异、已知限制、测试结论和固件校验值。这样,现场问题可以快速回溯到准确源码和配置,而不是依赖文件名中的日期。

常见错误与练习

常见错误包括把 build/ 提交进仓库、在源码中硬编码本机 SDK 路径、调试版与发布版共用同一构建目录、发布后移动标签,以及只保存固件而不保存构建参数。修复后应删除污染缓存,重新配置独立目录,并用干净克隆执行一次完整构建验证。

  1. 为示例工程增加 FW_DEVICE_ID 字符串配置,并在程序中输出。分别建立调试与发布构建目录,验收条件是两个目录的配置互不影响,删除任一目录后都能从零重建。
  2. 模拟发布 v1.1.0:新增一项功能、提交测试结果、建立注释标签并编写发布记录。验收条件是通过标签可查看对应提交,记录中包含构建命令、工具链版本和固件哈希。

本课总结

  • 仓库应保存可复现输入,构建产物、本机路径和秘密信息必须隔离。
  • 独立构建目录与生成配置头可以防止不同模式互相污染。
  • Git 提交、注释标签和发布记录共同建立源码到固件的追踪链。

下一课预告

完成工程配置与版本管理后,下一阶段可继续把主机测试、板级脚本和发布构建接入自动化流水线,并为多人协作建立代码评审与质量门禁。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

工程配置与版本管理

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通