单片机与物联网 / 系统课时
工程配置与版本管理
工程配置与版本管理
本课解决同一份单片机源码在不同电脑、不同构建模式下结果不一致的问题。你将建立清晰的目录与配置边界,用 CMake 固化编译参数,并通过 Git 提交、标签和发布记录追踪每个可交付固件。
学习目标
- 组织源码、配置、测试和构建产物,避免文件职责混乱。
- 使用 CMake 缓存变量生成可追踪的构建配置。
- 使用 Git 提交、注释标签和发布记录管理固件版本。
组织目录与配置边界
源码仓库只保存可审查、可复现的输入,不保存编译器临时文件和本机绝对路径。推荐把公共头文件、业务源码、配置模板、测试代码和辅助脚本分开,所有构建产物统一放入仓库外或已忽略的 build 目录。
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_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:
#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:
#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;
}配置、构建并运行:
cmake -S . -B build/debug -DFW_LOG_LEVEL=3 -DFW_FEATURE_DIAGNOSTICS=ON
cmake --build build/debug
./build/debug/firmware_demo预期输出中,CMake 的编译日志会随平台和编译器变化,程序输出应稳定为:
log_level=3
diagnostics=on嵌入式交叉编译时,可额外传入 -DCMAKE_TOOLCHAIN_FILE=<PATH>。<PATH> 的实际值可能不同;仓库应保存工具链文件或可定位 SDK 的脚本,而不是提交某位开发者电脑上的绝对目录。
隔离构建模式与生成文件
调试版可以开启断言、日志和诊断命令,发布版则应关闭测试入口并启用尺寸或速度优化。不同模式必须使用独立构建目录,例如 build/debug 与 build/release,避免旧对象文件和缓存变量污染新固件。
生成的 build_config.h、对象文件、映射文件和最终固件通常不直接提交。发布时应保存构建命令、工具链版本、源代码标签、测试结果和固件哈希,使任何人都能确认“这个二进制由哪次提交、哪组参数生成”。
使用 Git 管理提交与标签
提交应围绕一个可审查变更,避免把格式化、功能修改和生成文件混在一起。下面的命令初始化仓库、创建首次提交并为可发布状态建立注释标签。
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预期输出:
<COMMIT> (HEAD -> main, tag: v1.0.0) feat: add reproducible firmware configuration<COMMIT> 是实际提交哈希的缩写,每次仓库内容不同都会变化。发布标签应指向已通过测试的提交;标签建立后若发现问题,应修复并创建新版本,而不是强制移动已经对外发布的标签。
推荐在发布记录中至少写明版本号、目标板卡、工具链版本、构建模式、配置差异、已知限制、测试结论和固件校验值。这样,现场问题可以快速回溯到准确源码和配置,而不是依赖文件名中的日期。
常见错误与练习
常见错误包括把 build/ 提交进仓库、在源码中硬编码本机 SDK 路径、调试版与发布版共用同一构建目录、发布后移动标签,以及只保存固件而不保存构建参数。修复后应删除污染缓存,重新配置独立目录,并用干净克隆执行一次完整构建验证。
- 为示例工程增加
FW_DEVICE_ID字符串配置,并在程序中输出。分别建立调试与发布构建目录,验收条件是两个目录的配置互不影响,删除任一目录后都能从零重建。 - 模拟发布
v1.1.0:新增一项功能、提交测试结果、建立注释标签并编写发布记录。验收条件是通过标签可查看对应提交,记录中包含构建命令、工具链版本和固件哈希。
本课总结
- 仓库应保存可复现输入,构建产物、本机路径和秘密信息必须隔离。
- 独立构建目录与生成配置头可以防止不同模式互相污染。
- Git 提交、注释标签和发布记录共同建立源码到固件的追踪链。
下一课预告
完成工程配置与版本管理后,下一阶段可继续把主机测试、板级脚本和发布构建接入自动化流水线,并为多人协作建立代码评审与质量门禁。