从零构建STM32 HAL库工程：Keil环境下的高效开发指南

1. 为什么你需要一个“干净”的HAL库工程

如果你刚开始接触STM32，或者刚从标准库（Standard Peripheral Library）转向HAL库，你可能会被STM32CubeMX生成的庞大工程吓到。它确实方便，一键生成，但里面文件繁多，结构复杂，对于新手来说，就像走进了一个装满精密仪器的房间，你知道它能干活，但不知道从哪下手，也不敢乱动，生怕碰坏了什么。

我自己刚开始用HAL库时，也依赖CubeMX。但很快我就发现，当我想深入理解一个外设的初始化流程，或者想优化代码结构时，面对那个自动生成的工程，总有种“隔靴搔痒”的感觉。文件之间的依赖关系不清晰，很多配置散落在各个角落。更重要的是，如果你想在不同的项目间复用自己精心编写的驱动模块，从CubeMX工程里剥离出来非常麻烦。

所以，我决定回归“原始”，从零开始，手动搭建一个最精简、最清晰的HAL库工程。这个过程就像自己组装一台电脑，从选择每一个零件（文件）开始，到最终点亮（编译通过）。这么做的好处太多了：首先，你对工程的每一个文件、每一条编译选项都了如指掌，出了问题能快速定位；其次，工程结构完全由你掌控，可以设计出最适合自己或团队开发的目录规范；最后，这个工程模板一旦建立，就是属于你自己的“瑞士军刀”，后续任何新项目都可以基于它快速开始，效率倍增。

这个指南，就是带你一起完成这次“组装”。我们不依赖任何自动化工具，就用最“笨”但最有效的方法，在Keil MDK这个经典的环境里，构建一个专属于你的、高效且易于维护的STM32 HAL库开发地基。不用担心复杂，我会一步步拆解，把每个环节都讲透。

2. 战前准备：理清思路与备齐“弹药”

动手之前，我们得先想清楚这个工程最终要长什么样，以及需要准备哪些材料。盲目开始只会导致中途不断返工。

2.1 规划你的工程目录结构

一个清晰、合理的目录结构是高效开发的基石。它能让你的代码模块化，便于管理和团队协作。我经过多个项目的迭代，总结出了一个非常实用的结构，你可以直接参考：

My_STM32_Project/
├── Core/
│   ├── Inc/           # 核心头文件：启动文件、系统文件、中断文件等
│   └── Src/           # 核心源文件
├── Drivers/
│   ├── HAL_Driver/    # 存放从ST官方包拷贝的HAL库源文件（.c/.h）
│   └── BSP/          # 板级支持包，你的LED、按键、屏幕等硬件驱动
├── Middlewares/       # 中间件，如FatFS、FreeRTOS、USB库等（后续扩展用）
├── User/
│   ├── Inc/           # 用户应用头文件
│   └── Src/           # 用户应用源文件，main.c就在这里
├── Project/
│   └── MDK-ARM/       # Keil工程文件（.uvprojx）及其输出文件（.axf, .hex）
├── Docs/              # 项目文档
└── Utilities/         # 工具脚本，如批处理清理脚本

这个结构的关键在于分离。Core和Drivers/HAL_Driver里的东西，一旦确定基本不会动，它们是ST官方提供的“地基”。Drivers/BSP和User里的才是你发挥创意的地方。Project目录只放工程相关文件，编译生成的中间文件也在这里，这样你用一个简单的Clean.bat脚本就能一键清理，保持仓库干净。

2.2 下载必备的软件与资料包

工欲善其事，必先利其器。我们需要三样东西：

1. Keil MDK-ARM开发环境：这个不用说，你得先安装好。建议使用V5版本，兼容性和稳定性都经过时间检验。
2. STM32F1的Device Family Pack (DFP)：这是Keil用来认识你芯片的“户口本”。没有它，Keil连STM32F103是谁都不知道。
3. STM32CubeF1固件包：这是HAL库的“源代码仓库”，我们需要的所有HAL驱动文件、启动文件、系统文件都从这里取。

获取DFP芯片支持包： 最简单的方法是在Keil软件内直接安装。打开Keil，点击菜单栏的 Pack Installer 图标（那个小盒子）。在打开的窗口中，左侧找到 All Devices -> STMicroelectronics -> STM32F1 Series -> STM32F103 -> STM32F103ZE。选中后，右侧 Packs 选项卡里应该能看到 Keil::STM32F1xx_DFP，点击旁边的 Install 按钮，等待下载安装完成即可。这种方式省去了手动查找的麻烦。

获取STM32CubeF1固件包： 我们需要访问ST的官网。找到 Tools & Software -> Embedded Software -> STM32Cube MCU & MPU Packages 页面。在里面找到 STM32CubeF1 这个包，点击进入其详情页。你会看到一个 Get Latest 或类似版本的下载按钮，通常是一个ZIP压缩包，大小在100MB左右。下载它，这就是我们全部的“原料”。

3. 动手搭建：创建工程与组织文件

现在，让我们在电脑上实际创建这个工程框架，并把必要的文件“搬运”到位。

3.1 创建工程根目录与子文件夹

首先，在你喜欢的位置（比如D:\Projects）创建一个新的文件夹，命名为你的项目名，例如 STM32_HAL_Template。然后，按照我们之前规划的结构，在里面创建好所有子文件夹。你可以直接在资源管理器里手动新建，但我更推荐写一个简单的批处理脚本（create_dirs.bat）来一键生成，方便以后复用。

@echo off
mkdir Core\Inc
mkdir Core\Src
mkdir Drivers\HAL_Driver
mkdir Drivers\BSP
mkdir User\Inc
mkdir User\Src
mkdir Project\MDK-A