嵌入式开发环境的搭建是对接硬件之前的第一个坑。本文把整套环境从零到完整的搭建过程整合为一，覆盖 WSL2 配置、工具链安装、VSCode 工程化配置、调试链和 CMake 构建系统。

一、整体架构

这套环境的核心思路：

flowchart TB
    subgraph WSL2[WSL2 环境]
        W1[Ubuntu/Arch]
        W2[工具链安装]
    end
    subgraph VSC[VSCode 配置]
        V1[CMake Presets]
        V2[Cortex-Debug]
        V3[OpenOCD]
    end
    subgraph CHAIN[调试链]
        C1[OpenOCD → GDB]
        C2[Semihosting]
    end
    WSL2 --> VSC --> CHAIN
    style WSL2 fill:transparent,stroke:#8dc7ff,color:#eaf4ff
    style VSC fill:transparent,stroke:#8dc7ff,color:#eaf4ff
    style CHAIN fill:transparent,stroke:#8dc7ff,color:#eaf4ff

• Windows 管 UI、浏览器、微信、Office
• Linux (WSL2 + Arch) 管编译、调试、脚本、自动化
• AI 管代码审查、知识管理、技术写作

三层各司其职，全部在 Windows 11 24H2 上运行。

二、WSL2 + Arch Linux 基础搭建

2.1 启用 WSL2

# 以管理员身份运行 PowerShell
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
# 重启后
wsl --set-default-version 2

2.2 安装 ArchWSL

# 下载 ArchWSL (yuk7 版)
# 解压后双击 Arch.exe 运行，会自动安装到 %LOCALAPPDATA%\Arch\
# 进入 WSL 后立即配置:
echo 'Server = https://mirrors.tuna.tsinghua.edu.cn/archlinux/$repo/os/$arch' > /etc/pacman.d/mirrorlist
pacman-key --init
pacman-key --populate archlinux
pacman -Syu

2.3 嵌入式工具链

 ARM GCC 14.2.0（AUR 安装）
pacman -S arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
# CMake + Ninja（pacman 最新版）
pacman -S cmake ninja
# OpenOCD 0.12.0（AUR）
pacman -S openocd
# clangd + clang-format
pacman -S clang
# 其他工具
pacman -S git python python-pip gdb-multiarch minicom

2.4 Shell 环境

 Zsh + Oh My Zsh + Powerlevel10k
pacman -S zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/themes/powerlevel10k
# .zshrc 中设置 ZSH_THEME="powerlevel10k/powerlevel10k"

2.5 USB 调试器转发

Windows 端安装 usbipd-win，WSL 内转发 DAPLink：

 Windows 端（管理员 PowerShell）
winget install usbipd
usbipd bind --busid <DAPLink的busid>
# WSL 端
sudo modprobe usbip-core
sudo usbip attach -r $(hostname).local -b <busid>

三、VSCode 配置

3.1 工作区结构

双仓库 Multi-root Workspace：MCU 固件仓库 + HMI Flutter 仓库，各自独立 Git 但共用一个 .code-workspace。

3.2 settings.json 核心配置

{
  "C_Cpp.default.compilerPath": "/usr/bin/arm-none-eabi-gcc",
  "C_Cpp.default.intelliSenseMode": "gcc-arm",
  "cmake.configureOnEdit": true,
  "cmake.buildDirectory": "${workspaceFolder}/build",
  "clangd.path": "/usr/bin/clangd",
  "clangd.arguments": ["--background-index", "--clang-tidy"],
  "editor.formatOnSave": true,
  "files.associations": {
    "*.h": "c",
    "*.c": "c"
  }
}

3.3 tasks.json — 编译与烧录

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "cmake-configure",
      "type": "shell",
      "command": "cmake --preset default"
    },
    {
      "label": "cmake-build",
      "type": "shell",
      "command": "cmake --build --preset default"
    },
    {
      "label": "flash-openocd",
      "type": "shell",
      "command": "openocd -f interface/cmsis-dap.cfg -f target/stm32f1x.cfg -c 'program build/firmware.elf verify reset exit'"
    }
  ]
}

四、调试链

4.1 硬件接线

DAPLink 与 STM32 的 4 线连接：SWDIO、SWCLK、NRST、GND。

4.2 OpenOCD 配置

source [find interface/cmsis-dap.cfg]
transport select swd
source [find target/stm32f1x.cfg]
adapter speed 4000
reset_config srst_only

4.3 四种调试模式（launch.json）

1. 硬件复位调试 — 标准模式，OpenOCD 启动后自动复位 MCU 并 halt
2. 软件复位调试 — 通过 Cortex-Debug 的"Restart"按钮触发，不重新烧录
3. Attach 模式 — 连接到正在运行的 MCU，不打断执行
4. pyOCD 模式 — 替代 OpenOCD 的轻量方案

4.4 GDB 自定义命令

在 .gdbinit 中注册 9 个自定义命令：

• conect — 一键连接+加载符号
• hardfault_info — 分析 HardFault 时的寄存器状态
• freertos_tasks — 列出所有 FreeRTOS 任务状态
• stack_usage — 检查栈使用情况
• periph — 查看关键外设寄存器

4.5 WSL USB 调试穿透

详见 2.5 节 USB 调试器转发。启动调试前确保 DAPLink 已正确绑定到 WSL。

五、CMake 构建系统

5.1 CMakePresets.json

{
  "version": 6,
  "configurePresets": [
    {
      "name": "default",
      "displayName": "STM32 Debug",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "${sourceDir}/cmake/arm-none-eabi.cmake",
        "CMAKE_BUILD_TYPE": "Debug"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "default",
      "configurePreset": "default"
    }
  ]
}

5.2 工具链文件 arm-none-eabi.cmake

set(CMAKE_SYSTEM_NAME Generic)
set(CMAKE_SYSTEM_PROCESSOR arm)
set(CMAKE_C_COMPILER arm-none-eabi-gcc)
set(CMAKE_CXX_COMPILER arm-none-eabi-g++)
set(CMAKE_ASM_COMPILER arm-none-eabi-gcc)
set(CMAKE_OBJCOPY arm-none-eabi-objcopy)
set(CMAKE_SIZE arm-none-eabi-size)
set(CMAKE_C_FLAGS "-mcpu=cortex-m3 -mthumb -specs=nano.specs -specs=nosys.specs")

5.3 clangd 配置（.clangd）

CompileFlags:
  Add: [-mcpu=cortex-m3, -mthumb, -std=c11]
  Remove: [-mfp16-format*, -mfpu*, -mvectorize*]
Diagnostics:
  UnusedIncludes: Strict

六、AI Agent 集成

6.1 AGENTS.md 知识库

项目根目录放置 AGENTS.md，包含：构建设置、测试命令、代码规范、架构约束。AI Agent 自动读取后获得项目上下文。

6.2 Hermes Agent 工作流

• 代码审查：git diff → AGENTS.md 约束比照
• 知识管理：session 笔记结构化
• 技术写作：架构复盘文自动生成

七、验收清单

相关文章

• BSP 实现总览：10 个驱动模块的设计模式
• 工程架构复盘：从 STM32 到 Flutter
• AI Agent + AGENTS.md 知识库