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

整理与发布工程

整理与发布工程

项目能运行并不等于可以交付。本课把环境监测终端整理成可复现、可编译、可接线、可追踪版本的发布包,最终得到包含源码、配置、接口说明、接线表、构建步骤和版本记录的完整工程归档。

学习目标

  • 区分必须保留的源码配置与应删除的临时产物
  • 编写足以让他人复现项目的接口、接线和编译说明
  • 完成版本标记、编译验收与压缩归档

发布前的最小交付物

一个可发布工程至少要回答四个问题:使用什么硬件、引脚如何连接、怎样编译、当前版本是什么。建议保留源码、启动文件、链接脚本、CubeMX 配置文件、工程配置和说明文档;删除对象文件、下载缓存、调试日志及本机工作区数据。

整理后的根目录可以保持如下结构。目录名可按实际工程调整,但职责应清晰。

text
environment-terminal/
├─ Core/
├─ Drivers/
├─ Middlewares/
├─ App/
├─ environment-terminal.ioc
├─ README.md
├─ CHANGELOG.md
├─ VERSION
└─ docs/
   ├─ wiring.md
   └─ protocol.md

Core、Drivers 和 App 保存可维护代码,.ioc 用于恢复 CubeMX 配置,docs 存放接线与协议说明。Debug、Release、.metadata、对象文件和临时日志不应进入发布包。

清理工程与固定目录

清理前先提交或备份当前代码,避免误删未保存的文件。下面的命令适用于 Linux、macOS 或 Git Bash,需在工程根目录执行;它只移除常见编译产物,不删除源码和工程配置。

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'

预期输出:

text
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 工具链的终端中运行:

bash
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"

预期结果:

text
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 元数据与构建目录。

bash
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"

预期输出:

text
Archive created: ../environment-terminal-v1.0.0.tar.gz

归档前应核对压缩包能够解压,文档中的路径与引脚名称有效,并保存发布版本对应的 Git 提交号或标签。这样后续出现现场问题时,才能准确还原当时的代码和配置。

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

目录与阅读设置

阅读设置

17

记录一个想法

整理与发布工程

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

登录哪都通