CSolution Open‑CMSIS 工程生成、开发、团队协作、CI、故障排查落地方案

1. 完整标准化开发操作流程（复现 LAT1696 参考流程）

1. 工程生成阶段
   • 使用 STM32CubeMX2 打开.ioc2工程；
   • Project Settings → IDE Project Generation，Format 选择OpenCMSIS，toolchain 选择AC6；
   • Generate IDE project，得到 ioc2 文件和demo_open‑cmsis文件夹。
2. VSCode 环境准备
   • 安装Arm Keil Studio Pack，执行Install Specific Version指定版本 1.20.1；
   • 进入子组件Arm CMSIS Debugger，指定版本 1.3.0，关闭所有组件 Auto‑Update 自动更新。
3. 打开工程 右键文件夹 Open with Code，VS Code 打开工程目录，识别 demo.csolution.yml。
4. Solution 配置 打开 Manage Solution Settings，Debug Adapter 选择ST‑LINK@pyOCD；调试协议 SWD；时钟 4000kHz；保存 target 配置。
5. 工具链配置 打开 Add Arm Tools Configuration to Workspace，进入 Arm Registry，确认工具链版本，生成 vcpkg‑configuration.json；等待后台自动下载全部工具链组件，必须等待工具安装成功。
6. 编译构建：执行编译，观察终端 cbuild 输出日志。
7. 调试下载：点击调试按钮；如下载完成无法跳转 main，将目标开发板断电重新上电重试。

资料获取：【实战经验】LAT1696 编译与调试STM32CubeMX2生成的Open-CMSIS工程

2. VS Code 插件版本锁定管控实施方案（团队统一环境）

团队多人协作最大风险：插件版本不一致，本地编译结果不一样。

1. 团队统一指定插件版本：Keil Studio Pack 1.20.1；Arm CMSIS Debugger 1.3.0；
2. 每台开发机全部关闭插件 Auto‑Update 自动更新；禁止插件自动升级；
3. 将vcpkg‑configuration.json纳入 Git 版本库，锁定工作区内部工具链版本；
4. 团队文档写明插件安装步骤，禁止成员直接安装最新版本插件；
5. 升级插件版本必须团队统一评审，同步更新文档。

注意：csolution.yml 工程本身不管控 VS Code 插件版本，仅管控底层编译工具链版本，插件版本必须人工管控。

3. 内网离线环境部署实施方案

CSolution 默认需要联网下载编译器、cmake、ninja 组件，内网无外网环境流程复杂：

1. 外网准备机器：完全执行一遍工程，vcpkg 把全部工具链缓存下载完毕；
2. 导出 vcpkg 工具缓存包；
3. 将工程、vcpkg 缓存、Keil Studio Pack vsix 离线插件包拷贝内网机器；
4. VS Code 离线安装 vsix 插件包；配置本地 artifact 源指向本地缓存，不再访问 Arm 外网仓库；
5. 打开工程不再触发外网下载；

现状：官方没有简单一键离线包，离线部署工作量远大于 CMake 工程，评估项目是否值得选用 CSolution。

4. 存量项目迁移方案：ioc → ioc2，uvprojx 迁移 CSolution

1. 新项目场景：直接使用 STM32CubeMX2 建立 ioc2 工程，输出 Open‑CMSIS 工程，流程顺畅。
2. 老项目（旧 ioc + MDK5 uvprojx）
   • 老版本.ioc不能直接给 CubeMX2 使用；需要先将老 ioc 导入新版 STM32CubeMX2，另存转换为.ioc2；
   • 转换 ioc2 后，才可以输出 Open‑CMSIS 工程；
   • 用户业务代码手动迁移到 CSolution 工程 UserCode 目录；
   • 迁移完成后做功能对比测试，确认编译选项、宏定义和原 uvprojx 工程对齐。

风险：自动生成工程不能 100% 复刻老 uvprojx 编译选项，迁移后务必核对编译宏、优化等级。

5. CI/CD 流水线 cbuild 命令自动化编译实施方案

CSolution 的核心优势：图形界面编译底层调用 cbuild 命令，可用于 CI 服务器。

1. CI 服务器不需要完整 VS Code 图形界面；仅部署 cmsis‑toolbox、vcpkg 工具链；
2. 流水线拉取 Git 仓库（包含 csolution.yml、vcpkg‑configuration.json、dfp 包、源码）；
3. 执行 cbuild 命令，示例：

cbuild demo.csolution.yml --target all --active STM32C562RET6 --packs

4. 提取 constructed‑files 目录下 elf/hex/bin 固件产物归档；

限制：CI 服务器同样需要工具链，离线 CI 需要预先准备全部 vcpkg 工具缓存。

6. 典型故障现象、根因与排查修复清单

7. 量产项目工程版本管控最佳实践

1. Git 版本管理：把 csolution.yml、vcpkg‑configuration.json、dfp 驱动目录、UserCode 业务代码全部纳入版本库；
2. 团队文档明确 VS Code 插件固定版本，关闭自动更新；
3. 禁止成员本地随意修改 csolution.yml，修改需要评审；
4. 每次生成工程之后做 diff，确认 CubeMX2 生成的 yml 变更符合预期；
5. 迁移项目务必对比旧工程编译选项，做固件二进制对比验证；
6. CI 流水线使用 cbuild 命令复现构建，保障编译产物可重现。