generated from Template/H563ZI-HAL-CMake-Template
165 lines
6.0 KiB
Markdown
165 lines
6.0 KiB
Markdown
# 🚀 STM32H563ZI HAL CMake 模板使用指南
|
||
|
||
## 📋 项目简介
|
||
|
||
这是一个基于 STM32H563ZI 微控制器的项目模板，使用 HAL 库和 CMake 构建系统。该模板提供了开发 STM32H563ZI 微控制器项目所需的基本框架，让你能够快速开始开发，而无需从零开始配置构建系统。
|
||
|
||
## ✨ 特性
|
||
|
||
- 支持 C/C++ 混合编程
|
||
- 集成 `.clang-format` `.clang-tidy` 配置，支持代码格式化和静态分析
|
||
- 集成 STM32 HAL 和 LL 驱动库
|
||
- 使用 CMake 作为构建系统，支持跨平台开发
|
||
- 自动生成版本信息（通过 Python 脚本）
|
||
- 集成 Gitea CI/CD 配置，支持自动化构建
|
||
- 支持 Debug 和 Release 等构建配置
|
||
- 适用于 ARM GCC 编译器
|
||
- 预配置的链接器脚本
|
||
- 配置基本的外设（时钟、串口、调试）
|
||
|
||
## 🔧 开发环境要求
|
||
|
||
- [STM32CubeCLT](https://www.st.com/en/development-tools/stm32cubeclt.html) 或 [ARM GCC 工具链](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads)
|
||
- [CMake](https://cmake.org/download/) 3.22 或更高版本
|
||
- [Ninja](https://ninja-build.org/) 构建工具
|
||
- [Python](https://www.python.org/downloads/) 3.6 或更高版本（用于版本管理脚本）
|
||
- [Git](https://git-scm.com/downloads)（可选，用于版本管理）
|
||
|
||
## 📁 目录结构
|
||
|
||
```
|
||
.
|
||
├── .gitea/ # Gitea CI/CD 配置
|
||
├── assert/ # 图像等资源文件
|
||
├── cmake/ # CMake 配置文件
|
||
│ ├── gcc-arm-none-eabi.cmake # ARM GCC 工具链配置
|
||
│ └── stm32cubemx/ # STM32CubeMX 生成的 CMake 配置
|
||
├── Core/ # 项目核心代码
|
||
│ ├── App/ # 应用程序代码目录
|
||
│ │ ├── AutoGen/ # 自动生成的版本信息代码
|
||
│ │ ├── Common/ # 通用功能组件
|
||
│ │ └── Helper/ # 辅助功能类和工具
|
||
│ │ └── app.cpp # 应用程序入口
|
||
│ ├── Inc/ # 头文件
|
||
│ └── Src/ # 源文件
|
||
├── Drivers/ # STM32 HAL/LL 驱动
|
||
├── Tools/ # 工具脚本
|
||
│ └── MCUVersionGen.py # 版本信息生成脚本
|
||
├── .gitignore # Git 忽略配置
|
||
├── CMakeLists.txt # 主 CMake 文件
|
||
├── CMakePresets.json # CMake 预设配置
|
||
├── README.md # 项目说明文档
|
||
├── STM32H563ZI-HAL-CMake-Template.ioc # STM32CubeMX 项目文件
|
||
├── STM32H563XX_FLASH.ld # 链接器脚本
|
||
└── startup_stm32h563xx.s # 启动文件
|
||
```
|
||
|
||
## 📝 使用方法
|
||
|
||
### 1. 从模板创建新项目
|
||
|
||
1. 在 Gitea 上访问此模板仓库
|
||
2. 点击仓库页面上的 "使用模板创建" 按钮
|
||
3. 输入您的新项目名称、描述等信息
|
||
4. 点击 "创建仓库" 完成
|
||
|
||
### 2. 获取项目代码
|
||
|
||
```bash
|
||
# 克隆您刚创建的仓库
|
||
git clone <新仓库URL> --recursive
|
||
cd <您的项目名称>
|
||
|
||
# 如果已经克隆但没有加载子模块，可以运行：
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
### 3. 配置项目
|
||
|
||
可以使用 STM32CubeMX 修改硬件配置：
|
||
1. 打开 `.ioc` 文件
|
||
2. 根据需要修改外设配置
|
||
3. 生成代码
|
||
|
||
### 4. 构建项目
|
||
|
||
#### 使用 CMake 预设
|
||
|
||
```bash
|
||
# 列出可用的预设
|
||
cmake --list-presets
|
||
|
||
# 使用预设配置项目（例如 Debug 预设）
|
||
cmake --preset=debug
|
||
|
||
# 构建项目
|
||
cmake --build --preset=debug
|
||
```
|
||
|
||
### 5. 烧录程序
|
||
|
||
编译完成后，在 `build/Debug` 目录下会生成 `.elf`、`.hex` 和 `.bin` 文件。使用 ST-Link 或其他烧录工具通过 `OpenOcd`，`STM32CubeProgrammer` 等软件将程序烧录到 STM32H563ZI 芯片上。
|
||
|
||
## 💻 添加自定义代码
|
||
|
||
### 在 Core/Src 和 Core/Inc 目录下添加
|
||
1. 自定义源文件：在 `Core/Src` 目录下添加 `.c` 文件
|
||
2. 自定义头文件：在 `Core/Inc` 目录下添加 `.h` 文件
|
||
3. 更新 CMakeLists.txt：在主 CMakeLists.txt 文件中的 `target_sources` 部分添加自定义源文件
|
||
|
||
```cmake
|
||
target_sources(${CMAKE_PROJECT_NAME} PRIVATE
|
||
# Add user sources here
|
||
Core/Src/your_custom_file.c
|
||
)
|
||
```
|
||
|
||
### 在 Core/App 目录下添加
|
||
在 `Core/App` 目录及其子目录下添加的 `.c`、`.cpp`、`.h` 和 `.hpp` 文件会被自动包含在构建中，无需手动修改 CMakeLists.txt 文件。
|
||
|
||
### 在其他目录下添加
|
||
在其他目录下添加的源文件需要手动更新 CMakeLists.txt 文件，将其添加到 `target_sources` 部分。
|
||
|
||
```cmake
|
||
target_sources(${CMAKE_PROJECT_NAME} PRIVATE
|
||
# Add user sources here
|
||
path/to/your_custom_file.c
|
||
)
|
||
|
||
target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE
|
||
# Add user include directories here
|
||
path/to/your_custom_include
|
||
)
|
||
```
|
||
|
||
## 📊 版本管理
|
||
|
||
项目使用 MCUVersionGen.py 脚本自动生成版本信息。版本号在该 `version.txt` 中定义：
|
||
|
||
```python
|
||
# 语义化版本 https://semver.org/lang/zh-CN/spec/v2.0.0.html
|
||
major_version = 0 # 主版本号
|
||
minor_version = 1 # 次版本号
|
||
revision_version = 0 # 修订版本号
|
||
pre_release_version = "" # 预发行版本号
|
||
```
|
||
|
||
生成的版本信息会写入 autogen_version.c 文件中，可以在程序中通过以下变量访问：
|
||
|
||
```c
|
||
extern const char *g_name; // 项目名称
|
||
extern const char *g_version; // 版本号
|
||
extern const char *g_buildTime; // 构建时间
|
||
```
|
||
|
||
## ❓ 常见问题与解决方案
|
||
|
||
1. **编译错误**：确保已正确安装 ARM GCC 工具链并已添加到 PATH 环境变量中
|
||
2. **找不到 .elf 文件**：检查编译输出，确保没有编译错误
|
||
3. **烧录失败**：检查连接，确保 ST-Link 正确连接到 STM32H563ZI
|
||
4. **版本脚本错误**：确保已安装 Python 3.6 以上版本
|
||
5. **内存配置问题**：STM32H5系列有多个内存区域，确保正确配置了内存映射
|
||
|
||
## 🤝 贡献与支持
|
||
|
||
欢迎通过 Issue 和 Pull Request 为项目做出贡献。如有任何问题或建议，请在项目仓库中提出。 |