单片机与物联网 / 系统课时
整理与发布工程
整理与发布工程
项目能运行并不等于可以交付。本课把环境监测终端整理成可复现、可编译、可接线、可追踪版本的发布包,最终得到包含源码、配置、接口说明、接线表、构建步骤和版本记录的完整工程归档。
学习目标
- 区分必须保留的源码配置与应删除的临时产物
- 编写足以让他人复现项目的接口、接线和编译说明
- 完成版本标记、编译验收与压缩归档
发布前的最小交付物
一个可发布工程至少要回答四个问题:使用什么硬件、引脚如何连接、怎样编译、当前版本是什么。建议保留源码、启动文件、链接脚本、CubeMX 配置文件、工程配置和说明文档;删除对象文件、下载缓存、调试日志及本机工作区数据。
整理后的根目录可以保持如下结构。目录名可按实际工程调整,但职责应清晰。
environment-terminal/
├─ Core/
├─ Drivers/
├─ Middlewares/
├─ App/
├─ environment-terminal.ioc
├─ README.md
├─ CHANGELOG.md
├─ VERSION
└─ docs/
├─ wiring.md
└─ protocol.mdCore、Drivers 和 App 保存可维护代码,.ioc 用于恢复 CubeMX 配置,docs 存放接线与协议说明。Debug、Release、.metadata、对象文件和临时日志不应进入发布包。
清理工程与固定目录
清理前先提交或备份当前代码,避免误删未保存的文件。下面的命令适用于 Linux、macOS 或 Git Bash,需在工程根目录执行;它只移除常见编译产物,不删除源码和工程配置。
find . -type d \( -name Debug -o -name Release -o -name .metadata \) -prune -exec rm -rf {} +
find . -type f \( -name '*.o' -o -name '*.d' -o -name '*.su' -o -name '*.log' \) -delete
printf 'Temporary build artifacts removed.\n'预期输出:
Temporary build artifacts removed.清理后再次检查 .ioc、启动文件、链接脚本和工程配置是否仍在。若工程使用 Git,还应把构建目录和临时文件规则写入 .gitignore,防止下一次编译重新污染仓库。
补齐接口说明和接线表
接口文档不需要复述全部实现代码,但必须写清方向、格式、单位和边界。例如串口上报协议至少说明波特率、数据位、帧结构、字段含义、校验方式和异常响应;传感器接口还要注明采样周期与无效值处理。
接线表应以开发板丝印和外设引脚为准,不能只写“连接 I2C”。下面是环境监测终端的示例格式,实际发布时替换为项目真实引脚。
| 模块 | 模块引脚 | STM32 引脚 | 方向 | 说明 |
|---|---|---|---|---|
| 温湿度传感器 | SDA | PB7 | 双向 | I2C1 数据线,需上拉 |
| 温湿度传感器 | SCL | PB6 | 输出 | I2C1 时钟线,需上拉 |
| OLED | DC | PA1 | 输出 | 数据/命令选择 |
| 蜂鸣器 | SIG | PA8 | 输出 | 高电平有效,按实际电路确认 |
| 所有模块 | GND | GND | 电源 | 必须共地 |
接口说明中还应标出电压等级。若模块只能使用 3.3 V,必须明确禁止接入 5 V;若引脚存在复用冲突,也要写出启用条件和替代方案。
编译与验收
发布包必须经过一次“从干净目录重新编译”的验证。使用 STM32CubeIDE 时,先执行 Project > Clean,再执行 Project > Build Project;使用 Makefile 的工程可在已配置 ARM GCC 工具链的终端中运行:
make clean
make -j
elf_file=$(find . -type f -name 'environment-terminal.elf' -print -quit)
test -n "$elf_file"
arm-none-eabi-size "$elf_file"预期结果:
Build completed successfully.
text data bss dec hex filename
<SIZE> <SIZE> <SIZE> <SIZE> <SIZE> <PATH>/environment-terminal.elf<PATH> 和 <SIZE> 会随工程目录及编译结果变化。验收时不仅要看“编译成功”,还要确认无新增错误、关键警告已处理、生成的 ELF 或 HEX 文件存在,并在目标板上完成上电、传感器采集、显示刷新、告警输出和串口通信测试。
记录版本并归档
在根目录创建 VERSION,只保存当前发布版本,例如 1.0.0。CHANGELOG.md 记录本版新增功能、修复问题、已知限制和升级注意事项;README.md 则说明硬件型号、工具链版本、编译入口、烧录方式、文档位置和最小运行步骤。
完成验收后,可使用下面的命令生成带版本号的压缩包。命令会从 VERSION 读取版本,并排除 Git 元数据与构建目录。
version=$(tr -d '\r\n' < VERSION)
archive="../environment-terminal-v${version}.tar.gz"
tar --exclude='.git' --exclude='Debug' --exclude='Release' -czf "$archive" .
printf 'Archive created: %s\n' "$archive"预期输出:
Archive created: ../environment-terminal-v1.0.0.tar.gz归档前应核对压缩包能够解压,文档中的路径与引脚名称有效,并保存发布版本对应的 Git 提交号或标签。这样后续出现现场问题时,才能准确还原当时的代码和配置。