From a58bae84653e6d45e36f1b46413d6d4d05219f7c Mon Sep 17 00:00:00 2001
From: admin <admin@admin.me>
Date: Tue, 6 May 2025 21:37:31 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20README.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e6f67a0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# 🏷️ 单片机程序版本号生成
+
+- [版本: 0.4.0](#变更记录)
+
+脚本使用 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 为项目做出贡献。如有任何问题或建议，请在项目仓库中提出。
\ No newline at end of file