103 lines
3.2 KiB
Markdown
103 lines
3.2 KiB
Markdown
# 🏷️ 单片机程序版本号生成
|
||
|
||
脚本使用 Python 编写，符合语义化版本规范（[SemVer 2.0.0](https://semver.org/lang/zh-CN/spec/v2.0.0.html)）。
|
||
|
||
## ✨ 功能特点
|
||
|
||
- 自动从项目根目录的 `version.txt` 文件读取版本信息（不存在则创建默认版本文件）
|
||
- 支持主版本号、次版本号、修订版本号和预发行版本号
|
||
- 自动检测 Git 仓库信息，并将 commit ID 添加到版本号中
|
||
- 检测未提交的更改，有未提交内容时在版本号中添加 `*` 标记
|
||
- 使用正则表达式验证生成的版本号是否符合语义化版本规范
|
||
- 生成包含版本信息的 C 源文件，便于在程序中使用
|
||
|
||
## 📝 版本号格式
|
||
|
||
生成的版本号格式为：`major.minor.revision[-prerelease][+commitID]`
|
||
|
||
例如：
|
||
- `0.1.0` - 基本版本号
|
||
- `1.2.3-alpha` - 带预发行标识的版本号
|
||
- `1.2.3+a1b2c3d4` - 带构建元数据（commit ID）的版本号
|
||
- `1.2.3-beta+a1b2c3d4*` - 带预发行标识、构建元数据且有未提交更改的版本号
|
||
|
||
## 📋 使用方法
|
||
|
||
### 📄 版本配置文件
|
||
|
||
在项目根目录创建 `version.txt` 文件，格式如下：
|
||
|
||
```
|
||
major_version=0
|
||
minor_version=1
|
||
revision_version=0
|
||
pre_release_version=alpha
|
||
```
|
||
|
||
若不存在此文件，脚本会自动创建默认配置（主版本号=0，次版本号=1，修订版本号=0，无预发行版本号）。
|
||
|
||
### 🚀 调用脚本
|
||
|
||
基本调用格式：
|
||
```
|
||
python MCUVersionGen.py [程序名称] [项目路径]
|
||
```
|
||
|
||
- `程序名称`：可选参数，默认为 "McuProgram"
|
||
- `项目路径`：可选参数，默认为当前目录 "."
|
||
|
||
### 📂 输出文件
|
||
|
||
脚本生成的版本信息存放在项目目录下的 `./Core/App/AutoGen/autogen_version.c` 文件中，包含以下变量：
|
||
|
||
```c
|
||
const char *g_name = "程序名称";
|
||
const char *g_version = "版本号";
|
||
const char *g_buildTime = "构建时间";
|
||
```
|
||
|
||
在程序中使用时，通过声明这些外部变量即可：
|
||
|
||
```c
|
||
extern const char *g_name;
|
||
extern const char *g_version;
|
||
extern const char *g_buildTime;
|
||
```
|
||
|
||
## 🔧 集成到开发环境
|
||
|
||
### 🛠️ STM32CubeIDE
|
||
|
||
在项目配置中设置"Pre-build steps"：
|
||
|
||
1. 右键点击项目 → 选择"Properties"
|
||
2. 展开"C/C++ Build" → 选择"Settings"
|
||
3. 切换到"Build Steps"标签
|
||
4. 在"Pre-build steps"区域输入：
|
||
```
|
||
python ${ProjDirPath}/Tools/McuVersionGen.py ${PROJECT_NAME_STR} ${ProjDirPath}
|
||
```
|
||
5. 点击"Apply and Close"保存设置
|
||
|
||
### 🔄 CMake
|
||
|
||
在 CMakeLists.txt 中添加：
|
||
|
||
```cmake
|
||
# 在编译前执行版本生成脚本
|
||
execute_process(COMMAND python ${CMAKE_CURRENT_SOURCE_DIR}/Tools/McuVersionGen.py ${PROJECT_NAME_STR} ${CMAKE_CURRENT_SOURCE_DIR}
|
||
RESULT_VARIABLE result
|
||
OUTPUT_VARIABLE script_output)
|
||
message(${script_output})
|
||
|
||
# 每次构建都生成新的版本号
|
||
add_custom_target(version_gen
|
||
COMMAND python ${CMAKE_CURRENT_SOURCE_DIR}/Tools/McuVersionGen.py ${PROJECT_NAME_STR} ${CMAKE_CURRENT_SOURCE_DIR}
|
||
COMMENT "Running McuVersionGen.py script"
|
||
)
|
||
add_dependencies(${CMAKE_PROJECT_NAME} version_gen)
|
||
```
|
||
|
||
## 🤝 贡献与支持
|
||
|
||
欢迎通过 Issue 和 Pull Request 为项目做出贡献。如有任何问题或建议，请在项目仓库中提出。 |