1. 课程导入
在嵌入式开发领域，STM32 凭借其丰富的产品线、成熟的生态和极高的市场占有率，成为 AI 边缘计算落地的重要载体。然而，当我们将训练好的神经网络模型部署到 STM32 上时，工程构建方式往往成为制约项目交付效率的关键瓶颈。长期以来，Keil MDK 是 STM32 开发者最熟悉的 IDE，其图形化界面和工程管理方式在中小型项目中表现出色。但随着 AI 项目对代码复用、自动化构建、持续集成和跨平台协作的要求不断提高，Keil 工程在版本控制、依赖管理、多目标编译和服务器端构建等方面的局限性逐渐暴露。本课程旨在系统性地解决这一痛点，带领你完成从 Keil 到 CMake 的工程体系迁移，构建一套现代化、可维护、可扩展的 STM32 AI 项目交付工程。
上图清晰地展示了本次课程的核心逻辑：左侧是当前 Keil 工程面临的典型问题，右侧是 CMake 迁移后希望达成的目标状态，中间则是我们将要逐步实施的五个关键迁移步骤。这张图也是整个课程学习路径的缩影——我们不仅要学会操作，更要理解每一步背后的工程决策逻辑。
1.1 为什么 STM32 AI 项目需要工程体系升级
STM32 AI 项目通常包含三个核心组成部分：神经网络模型（如 .tflite 或 .onnx 文件）、推理运行时（如 TensorFlow Lite Micro、CMSIS-NN 或 STM32Cube.AI 生成的代码）、以及应用层业务逻辑。这三部分代码的构建方式直接决定了项目的可维护性和交付质量。Keil 工程将所有这些内容封装在一个 .uvprojx 文件中，这个文件本质上是一个 XML 格式的工程描述，记录了源文件列表、编译选项、头文件路径、设备型号等大量信息。
在实际的 AI 项目交付中，Keil 工程模式暴露出几个关键问题。首先，版本控制体验差。.uvprojx 文件在每次 IDE 操作后都可能产生大量无关 diff，团队成员合并代码时经常出现冲突，且冲突难以手动解决。其次，依赖管理原始。AI 项目往往需要引入 CMSIS、HAL 库、神经网络运行时等多个第三方库，Keil 的 Pack 安装机制在服务器环境或 CI 环境中难以自动化处理。第三，构建不可重复。Keil 的编译过程依赖 Windows 图形界面，无法在 Linux 服务器上执行，导致无法建立标准化的持续集成流水线。最后，多目标支持薄弱。当项目需要同时编译出针对不同 STM32 型号或不同优化级别的固件时，Keil 需要维护多套工程文件，极易出现配置漂移。
核心原理：CMake 是一种跨平台的构建系统生成器，它不直接编译代码，而是根据 CMakeLists.txt 脚本生成特定平台的原生构建文件（如 Makefile、Ninja 文件或 IDE 工程）。对于嵌入式项目，CMake 配合 ARM GCC 工具链，可以实现完全文本化、可脚本化的构建流程。这意味着工程描述从“IDE 私有格式”转变为“标准脚本语言”，从而获得版本控制友好、自动化可行、跨平台一致等关键能力。
1.2 迁移的核心目标与判断标准
在动手迁移之前，我们需要明确这次工程重构的目标。目标不是简单地“把 Keil 工程换成 CMake 工程”，而是建立一套更健康的工程体系。具体而言，迁移后的工程应满足以下判断标准：
| 维度 | Keil 工程现状 | CMake 迁移目标 | 验证方法 |
|---|---|---|---|
| 构建可重复性 | 依赖本机 IDE 配置，换电脑可能编译失败 | 一条命令完成全量构建 | 在干净环境中执行 cmake --build |
| 版本控制友好度 | .uvprojx 文件频繁产生无意义 diff | CMakeLists.txt 文本简洁、diff 清晰 | Git 提交记录中查看变更内容 |
| 依赖管理 | 手动下载 Pack 或复制库文件 | 通过 FetchContent 或子模块管理 | 检查第三方库版本一致性 |
| CI/CD 支持 | 无法在 Linux 服务器构建 | 支持 Linux/Windows 双平台构建 | 搭建 Jenkins/GitHub Actions 验证 |
| 多目标扩展 | 每新增一个板型需复制整个工程 | 通过 CMake 选项切换目标芯片 | 使用 -DSTM32_CHIP=xxx 参数构建 |
这张表不仅是迁移的验收标准，也是我们在后续章节中每一步操作的决策依据。例如，在编写 CMakeLists.txt 时，我们会刻意避免硬编码路径，而是通过变量和选项来支持多目标切换；在集成 AI 库时，我们会优先选择支持 CMake 的库版本，或者编写封装脚本。
1.3 课程整体学习路径与章节安排
本课程共 30 章，按照“理解 → 搭建 → 集成 → 优化 → 交付”的逻辑递进。前 5 章聚焦于基础准备：在完成本章导入后，第 2 章将深入分析 Keil 工程的结构，教你如何提取源文件列表、编译选项和链接脚本；第 3 章介绍 CMake 核心语法和嵌入式项目常用模式；第 4 章讲解 ARM GCC 工具链的配置与链接脚本编写；第 5 章完成第一个可运行的 CMake 版 STM32 空工程。
从第 6 章开始进入 AI 集成阶段。第 6 章到第 8 章分别讲解如何将 STM32Cube.AI 生成的代码、TensorFlow Lite Micro 运行时和 CMSIS-NN 库集成到 CMake 工程中。第 9 章到第 12 章处理内存布局优化、模型文件打包、运行时性能调优等进阶主题。第 13 章到第 18 章聚焦于工程级能力建设，包括单元测试框架、持续集成流水线、多板型支持、版本发布管理等。第 19 章到第 24 章深入调试与优化技巧，涵盖 GDB 调试、日志系统、功耗优化、启动时间优化等。第 25 章到第 28 章讨论团队协作与代码规范，包括 Git 工作流、代码审查、文档生成和依赖管理策略。最后两章通过一个完整的端到端案例，将所学知识串联起来，并总结常见陷阱与最佳实践。
学习建议：本课程不是单纯的“操作教程”，每一章都包含原理讲解、操作步骤、案例拆解和误区分析。建议你在学习过程中准备一块 STM32 开发板（推荐 STM32F407 或 STM32H743），并安装好 VS Code + CMake 插件 + ARM GCC 工具链。每学完一章，亲手在开发板上验证一次，而不是只看不练。特别是第 5 章之后，所有示例代码都应在你的本地环境中实际编译运行。
1.4 迁移中的常见误区与风险预警
在指导多个团队完成 Keil 到 CMake 迁移的过程中，我们发现了一些反复出现的误区，提前了解这些风险能帮助你少走弯路。
误区一：试图一次性完美迁移。很多团队希望在一个大版本中完成所有代码的 CMake 化，结果导致迁移周期过长，业务开发停滞。正确的做法是采用渐进式迁移：先搭建 CMake 工程框架，保持 Keil 工程并行可用，逐步将源文件从 Keil 工程中“搬运”到 CMake 工程，每搬运一部分就编译验证一次。这样即使出现问题，也能快速定位是新增部分还是原有部分导致的。
误区二：忽略链接脚本的重要性。Keil 工程中，链接脚本（.sct 文件）由 IDE 自动管理，开发者很少关注。但在 CMake 工程中，链接脚本是显式指定的 .ld 文件，其内容直接决定了 AI 模型权重、神经网络中间缓冲区等大块数据在 Flash 和 RAM 中的放置位置。如果直接使用默认链接脚本，很可能出现 RAM 溢出或 Flash 空间不足的问题。第 4 章会专门讲解如何编写适用于 AI 项目的链接脚本。
误区三：对 AI 库的构建方式缺乏了解。不同的 AI 库对 CMake 的支持程度不同。STM32Cube.AI 生成的代码是纯 C 文件，集成相对简单；TensorFlow Lite Micro 提供了官方 CMake 支持，但需要正确设置目标平台；CMSIS-NN 则作为 CMSIS 的一部分，需要从 ARM 官方仓库获取。第 6 到 8 章会分别针对这三种情况给出详细的集成方案。
风险提示：在迁移过程中，最危险的操作是直接删除 Keil 工程文件。建议在迁移完成并经过至少两周的稳定运行后，再将 Keil 工程归档到单独的目录或分支中，而不是立即删除。此外，CMake 工程中使用的编译器版本（ARM GCC）与 Keil 自带的 ARMCC/AC6 在编译选项和优化行为上存在差异，可能导致同样的代码产生不同的运行结果。因此，迁移后必须进行完整的功能回归测试，特别是涉及浮点运算、中断处理和内存访问的代码路径。
1.5 案例拆解：一个实际 AI 项目的迁移决策过程
为了更好地说明迁移的决策逻辑，我们来看一个具体的案例。某工业视觉检测设备项目，使用 STM32H743 作为主控芯片，运行一个基于 MobileNetV2 的图像分类模型，用于检测生产线上的零件缺陷。项目最初使用 Keil MDK 开发，团队共 5 人，其中 3 人负责算法与模型优化，2 人负责嵌入式工程与硬件调试。
项目进行到中期时，团队遇到了几个棘手的问题。第一，算法工程师在 Linux 服务器上训练模型并导出 .tflite 文件，但每次更新模型后，都需要手动将新的模型文件复制到 Windows 开发机上，再通过 Keil 的图形界面添加到工程中，整个过程繁琐且容易出错。第二，由于 Keil 工程文件在 Git 中频繁冲突，团队不得不约定“每次只允许一个人修改工程文件”，这严重降低了并行开发的效率。第三，客户要求提供可复现的构建环境，但 Keil 的许可证和安装环境无法在客户的 Linux 服务器上复现。
团队经过评估后决定迁移到 CMake。他们的迁移策略如下：首先，花费两天时间梳理了 Keil 工程中的所有源文件，按照“HAL 库、中间件、AI 运行时、应用代码”四个层次分类，并记录每个文件的编译选项和头文件依赖。其次，编写了第一版 CMakeLists.txt，使用 target_sources 和 target_include_directories 明确声明每个层次的源文件和头文件路径。然后，针对 STM32H743 编写了链接脚本，将神经网络模型的权重数组放置在独立的 Flash 段中，并为 AI 推理预留了 512KB 的 RAM 缓冲区。最后，在 GitLab CI 上配置了构建流水线，每次代码提交后自动在 Linux 服务器上完成编译，并生成固件产物。
迁移完成后，团队的工作效率显著提升。模型更新流程简化为“算法工程师推送模型文件到 Git 仓库 → CI 自动触发编译 → 生成新固件”，整个过程无需人工干预。Git 冲突问题基本消失，因为 CMakeLists.txt 的文本格式使得合并操作变得直观。更重要的是，客户可以在自己的 Linux 环境中复现构建过程，满足了交付审计的要求。当然，迁移也付出了代价：团队花了约一周时间熟悉 CMake 语法和调试构建问题，期间还遇到了 ARM GCC 与 Keil AC6 在浮点 ABI 上的差异，导致部分代码需要调整。但总体而言，这次迁移的投资回报率非常高。
这个案例告诉我们，迁移到 CMake 不是一次简单的“工具替换”，而是一次工程体系的升级。它需要团队在初期投入一定的时间成本，但长期来看，无论是开发效率、协作体验还是交付质量，都能获得显著改善。在接下来的课程中，我们将一步步带你完成这个过程，让你少走弯路，快速掌握这套现代化的 STM32 AI 项目构建方法。