# wsl_toolchain_build

**Repository Path**: taylorxp/wsl_toolchain_build

## Basic Information

- **Project Name**: wsl_toolchain_build
- **Description**: 通用linux下的所有mcu编译
- **Primary Language**: C
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-08
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WSL ARM Cortex-M 编译工具链

> 🚀 通用的 Cortex-M MCU 编译工具链 - 支持 STM32/GD32/NXP/Nordic 等主流厂商

---

## 📋 目录

- [快速开始](#快速开始)
- [功能特性](#功能特性)
- [支持的MCU](#支持的mcu)
- [使用方法](#使用方法)
- [项目结构](#项目结构)
- [高级配置](#高级配置)
- [常见问题](#常见问题)
- [文档索引](#文档索引)

---

## 🚀 快速开始

### 前置要求

```bash
# 安装 ARM GCC 工具链和 CMake
sudo apt install gcc-arm-none-eabi cmake make

# 验证安装
arm-none-eabi-gcc --version
cmake --version
```

### 三步快速上手

```bash
# 进入工具链目录
cd toolchain

# Step 1: 设置MCU型号（可选，默认STM32F103）
./build.sh mcu STM32F103

# Step 2: 编译项目
./build.sh build

# Step 3: 查看输出文件
ls ../demo_project/build/
```

### 输出文件

编译成功后在 `build/` 目录生成：

- `*.elf` - ELF可执行文件（用于调试）
- `*.hex` - Intel HEX格式（用于烧录）
- `*.bin` - 二进制格式（用于烧录）
- `*.map` - 内存映射文件
- `*.lst` - 反汇编文件

---

## ✨ 功能特性

### ✅ 通用性强
- 支持所有 Cortex-M 系列 MCU（M0/M0+/M3/M4/M7/M23/M33/M35P/M52/M55/M85）
- 支持主流厂商：STM32、GD32、NXP、Nordic、TI 等
- 跨平台支持：Windows、Linux、WSL

### 🔧 配置简单
- **一行命令切换MCU**：`cd toolchain && ./build.sh mcu STM32H743`
- **自动工具链检测**：自动查找 ARM GCC 工具链
- **智能平台适配**：自动识别 Windows/Linux/macOS

### 📦 开箱即用
- 提供完整的 demo 项目
- 包含启动文件、链接脚本模板
- 清晰的项目结构

### 🎯 测试工具
- **统一测试脚本**：`test_all.sh` 整合所有测试功能
- 支持快速测试、Cortex-M核心测试、STM32全系列测试
- 自动保存和恢复MCU配置

---

## 🔌 支持的MCU

### 厂商系列（推荐使用）

#### STMicroelectronics STM32

```bash
STM32F0       # Cortex-M0    (超低功耗)
STM32F1       # Cortex-M3    (主流，如STM32F103)
STM32F4       # Cortex-M4F   (高性能，如STM32F407)
STM32H7       # Cortex-M7DP  (双精度FPU，如STM32H743)
STM32L4       # Cortex-M4F   (低功耗)
STM32G0       # Cortex-M0+   (超值系列)
```

#### GigaDevice GD32

```bash
GD32F1        # Cortex-M3    (兼容STM32F1)
GD32F4        # Cortex-M4F
GD32H7        # Cortex-M7DP  (高性能)
```

#### Nordic nRF

```bash
NRF52         # Cortex-M4F
NRF53         # Cortex-M33
```

#### NXP LPC

```bash
LPC11XX       # Cortex-M0
LPC17XX       # Cortex-M3
LPC55XX       # Cortex-M33F
```

### 核心 CPU 类型

```bash
CORTEX_M0     # ARMv6-M, 最小
CORTEX_M0PLUS # ARMv6-M, 改进版
CORTEX_M3     # ARMv7-M, 高性能无FPU
CORTEX_M4F    # ARMv7E-M, 单精度FPU
CORTEX_M7DP   # ARMv7E-M, 双精度FPU扩展
CORTEX_M23    # ARMv8-M.baseline, 安全基础
CORTEX_M33F   # ARMv8-M.mainline, 硬件FPU
```

### FPU 配置对比

| 核心配置 | CPU | FPU | 浮点ABI | 说明 |
|---------|-----|-----|---------|------|
| CORTEX_M0 | M0 | 无 | soft | 基础型，最小面积 |
| CORTEX_M3 | M3 | 无 | soft | 高性能，无FPU |
| CORTEX_M4F | M4 | fpv4-sp-d16 | hard | 单精度，硬件浮点 |
| CORTEX_M7DP | M7 | fpv5-sp-d16 | hard | 双精度扩展，最快 |

---

## 📖 使用方法

### 方法1: 使用 build.sh 脚本（推荐）

#### 基本命令

```bash
cd toolchain              # 进入工具链目录
./build.sh                # 编译项目（默认）
./build.sh build          # 编译项目
./build.sh clean          # 清理构建文件
./build.sh rebuild        # 清理并重新编译
./build.sh mcu <型号>     # 切换MCU型号并编译
./build.sh list           # 列出所有支持的MCU
./build.sh info           # 显示构建环境信息
./build.sh help           # 显示帮助
```

#### 典型工作流

```bash
cd toolchain              # 进入工具链目录

# 1. 首次使用 - 设置MCU型号
./build.sh mcu STM32F103

# 2. 编译项目
./build.sh build

# 3. 修改代码后重新编译
./build.sh rebuild

# 4. 切换到不同的MCU
./build.sh mcu STM32H743

# 5. 查看环境信息
./build.sh info
```

### 方法2: 直接使用 CMake

```bash
cd demo_project

# 配置项目（指定MCU型号）
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake-config/toolchain-gcc-arm-none-eabi.cmake \
      -DMCU=STM32F103 \
      -B build

# 编译
cmake --build build

# 查看详细编译输出
cmake --build build -- VERBOSE=1
```

### 使用测试脚本

```bash
# 查看测试帮助
cd toolchain && ./scripts/test.sh help

# 快速测试（2个常用MCU）
./scripts/test.sh quick

# 测试所有Cortex-M核心（11个）
./scripts/test.sh cortex

# 测试STM32全系列（27个型号）
./scripts/test.sh stm32

# 运行所有测试
./scripts/test.sh all

# 详细模式
./scripts/test.sh stm32 --verbose

# 不恢复原始配置
./scripts/test.sh quick --no-restore
```

---

## 📁 项目结构

```
wsl_toolchain_build/
├── README.md                    # 项目主文档
├── QUICK_START.md               # 快速开始指南
├── docs/                        # 详细文档目录
│   ├── UNIVERSAL_CONFIG_GUIDE.md    # 通用配置指南
│   ├── MCU_CONFIG_IMPLEMENTATION.md # MCU配置实现文档
│   ├── DEPLOYMENT.md                # 部署指南
│   ├── REVIEW_REPORT.md             # 项目审查报告
│   ├── VERSION_CONTROL_GUIDE.md     # 版本控制指南
│   └── WSL_SETUP_GUIDE.md           # WSL环境设置指南
├── toolchain/                   # 工具链目录 ⭐
│   ├── build.sh                 # 通用MCU编译脚本 ⭐
│   ├── version.conf             # 版本配置文件
│   ├── scripts/                 # 脚本配置文件目录
│   │   ├── flash_download.sh    # 烧录脚本
│   │   ├── test.sh              # 测试脚本
│   │   ├── jlink_config.sh      # J-Link配置脚本
│   │   ├── device-mappings.sh   # 设备映射配置
│   │   ├── load_mcu_config.sh   # MCU配置加载脚本
│   │   ├── MCU_CONFIG_README.md # MCU配置说明文档
│   │   └── .mcu-config.example  # MCU配置示例文件
│   └── cmake-config/            # CMake配置文件目录
│       ├── toolchain-gcc-arm-none-eabi.cmake  # 工具链配置 ⭐
│       └── common-mcu-config.cmake     # MCU型号配置 ⭐
├── demo_project/                # 演示项目
│   ├── CMakeLists.txt           # 项目构建文件
│   ├── src/                     # 源文件
│   ├── include/                 # 头文件
│   ├── ld/                      # 链接脚本
│   └── startup/                 # 启动文件
└── docs/                        # 详细文档目录
    └── WSL_SETUP_GUIDE.md       # WSL环境设置指南
```

### 核心文件说明

#### build.sh
- 通用 MCU 编译脚本
- 支持所有 Cortex-M 系列 MCU
- 提供 build、clean、rebuild、mcu 切换等功能
- 自动工具链检测和错误处理

#### scripts/test.sh
- 统一的 MCU 测试脚本
- 整合了所有测试功能到一个文件
- 支持多种测试模式：quick、cortex、stm32、all 等
- 自动保存和恢复 MCU 配置

#### cmake-config/toolchain-gcc-arm-none-eabi.cmake
- 工具链配置文件
- 自动检测操作系统和工具链
- 加载 MCU 配置并设置编译选项

#### cmake-config/common-mcu-config.cmake
- MCU 配置数据库
- 定义所有 Cortex-M 核心的编译选项
- 厂商 MCU 型号到核心的映射表

#### scripts/ 目录
- `flash_download.sh` - 烧录脚本，支持 J-Link 自动检测和烧录
- `test.sh` - 测试脚本，支持多种测试模式
- `jlink_config.sh` - J-Link 配置脚本
- `device-mappings.sh` - 设备映射配置
- `load_mcu_config.sh` - MCU 配置加载脚本
- `MCU_CONFIG_README.md` - MCU 配置说明文档

---

## 🔧 高级配置

### 自定义链接脚本

```bash
cmake -DMCU=STM32F103 \
      -DLD_SCRIPT=custom.ld \
      -B build
```

### 指定优化级别

```bash
# 在命令行
cmake -DMCU=STM32F103 -DOPT_LEVEL=O2 -B build

# 或在 CMakeLists.txt 中
set(CMAKE_C_FLAGS_RELEASE "-O3")
```

### 多 MCU 项目管理

创建多个构建目录：

```bash
# STM32F103 版本
cmake -DMCU=STM32F103 -B build_f103
cmake --build build_f103

# STM32H743 版本
cmake -DMCU=STM32H743 -B build_h743
cmake --build build_h743
```

### 添加预定义宏

在 `CMakeLists.txt` 中：

```cmake
target_compile_definitions(${PROJECT_NAME}.elf PRIVATE
    USE_HAL_DRIVER
    STM32F103xE
    MY_CUSTOM_DEFINE=1
)
```

### 浮点 ABI 选择

理解三种浮点 ABI 的区别：

| ABI | 说明 | 优缺点 | 使用场景 |
|-----|------|--------|----------|
| **soft** | 纯软件浮点 | ✅ 最大兼容性<br>❌ 最慢性能 | 无 FPU 的 MCU (M0, M3) |
| **softfp** | 硬件 FPU + 软件兼容 | ✅ 兼容软浮点库<br>✅ 硬件加速<br>❌ 函数调用开销 | 需要调用第三方软浮点库 |
| **hard** | 纯硬件浮点 | ✅ 最快性能<br>❌ 不兼容软浮点 | 纯硬件浮点项目 |

---

## ❓ 常见问题

### Q1: 如何添加新的MCU型号？

**A**: 编辑 `cmake-config/common-mcu-config.cmake`，添加映射：

```cmake
# 添加厂商映射
set(STM32G4_SERIES    CORTEX_M4F)

# 或添加核心配置（如果需要新核心）
set(MCU_CONFIG_CORTEX_MXXX
    CPU_FLAGS         "-mcpu=cortex-mxxx -mthumb"
    FPU_FLAGS         "-mfpu=xxx"
    FLOAT_ABI         "hard"
    CORE_TYPE         "MXXX"
    ARCH              "vX-m"
)
```

### Q2: 编译时提示找不到工具链？

**A**: 确保 ARM GCC 工具链已安装并在 PATH 中：

```bash
# 检查工具链
arm-none-eabi-gcc --version

# 如果未安装
sudo apt install gcc-arm-none-eabi
```

### Q3: 浮点未定义引用错误？

**A**: 浮点配置错误。检查：
- 如果使用 `-mfloat-abi=hard`，确保所有库都使用 hard 编译
- 如果链接第三方库，改用 `softfp` 或 `soft`

### Q4: 如何查看完整的编译命令？

**A**: 使用 `VERBOSE=1`：

```bash
cmake --build build -- VERBOSE=1
```

### Q5: Windows 下如何使用？

**A**: 如果使用 MinGW：

```cmd
cmake -DCMAKE_TOOLCHAIN_FILE=toolchain-gcc-arm-none-eabi.cmake ^
      -DMCU=STM32F103 ^
      -G "MinGW Makefiles" ^
      -B build
cmake --build build
```

### Q6: 如何为不同的 MCU 使用不同的链接脚本？

**A**: 在 `cmake-config/common-mcu-config.cmake` 中添加链接脚本映射：

```cmake
# 为每个 MCU 添加链接脚本路径
set(MCU_CONFIG_CORTEX_M4_LD_SCRIPT "${CMAKE_CURRENT_LIST_DIR}/ld/cortex-m4.ld")
set(MCU_CONFIG_CORTEX_M7_LD_SCRIPT "${CMAKE_CURRENT_LIST_DIR}/ld/cortex-m7.ld")
```

---

## 📚 文档索引

### 快速入门

- **[QUICK_START.md](QUICK_START.md)** - 快速开始指南
  - 环境准备
  - 5分钟快速上手
  - 常用命令速查

### 配置指南

- **[docs/UNIVERSAL_CONFIG_GUIDE.md](docs/UNIVERSAL_CONFIG_GUIDE.md)** - 通用配置指南
  - MCU 配置详解
  - 工具链配置
  - 编译选项说明

- **[docs/MCU_CONFIG_IMPLEMENTATION.md](docs/MCU_CONFIG_IMPLEMENTATION.md)** - MCU配置实现文档
  - 配置系统架构
  - 实现细节说明
  - 扩展指南

- **[toolchain/scripts/MCU_CONFIG_README.md](toolchain/scripts/MCU_CONFIG_README.md)** - MCU配置说明文档
  - 配置文件格式
  - 环境变量说明
  - 使用示例

### 部署与运维

- **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** - 部署指南
  - 环境部署
  - CI/CD 集成
  - 生产环境配置

- **[docs/VERSION_CONTROL_GUIDE.md](docs/VERSION_CONTROL_GUIDE.md)** - 版本控制指南
  - 固件版本号管理
  - 版本历史记录
  - Git标签集成

- **[docs/WSL_SETUP_GUIDE.md](docs/WSL_SETUP_GUIDE.md)** - WSL环境设置指南
  - WSL 安装配置
  - 工具链安装
  - 常见问题解决

### 开发文档

- **[docs/REVIEW_REPORT.md](docs/REVIEW_REPORT.md)** - 项目审查报告
  - 代码审查结果
  - 改进建议
  - 最佳实践

---

## 🚀 VSCode 集成

创建 `.vscode/tasks.json`：

```json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "编译 MCU 项目",
      "type": "shell",
      "command": "./build.sh",
      "group": {"kind": "build", "isDefault": true},
      "problemMatcher": []
    },
    {
      "label": "清理并重新编译",
      "type": "shell",
      "command": "./build.sh",
      "args": ["rebuild"],
      "problemMatcher": []
    },
    {
      "label": "运行快速测试",
      "type": "shell",
      "command": "./scripts/test.sh",
      "args": ["quick"],
      "problemMatcher": []
    }
  ]
}
```

创建 `.vscode/launch.json` 用于调试：

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Cortex Debug",
      "cwd": "${workspaceRoot}",
      "executable": "./build/mcu_demo.elf",
      "request": "launch",
      "type": "cortex-debug",
      "servertype": "jlink",
      "device": "STM32F103C8T6",
      "interface": "swd"
    }
  ]
}
```

---

## 📚 参考资料

- [CMake 官方文档](https://cmake.org/documentation/)
- [ARM GCC 工具链文档](https://developer.arm.com/documentation/dui0473/)
- [Cortex-M 处理器参考手册](https://developer.arm.com/documentation/)
- [J-Link 软件下载](https://www.segger.com/downloads/jlink/)

---

## 📝 版本历史

### v2.2 (2025-02-09)
- 📝 更新 README.md 文档，反映当前项目结构
- 📁 修正文件路径和脚本名称
- 📚 添加文档索引部分，整理所有相关文档
- ✨ 新增多个详细文档：QUICK_START.md、UNIVERSAL_CONFIG_GUIDE.md、MCU_CONFIG_IMPLEMENTATION.md 等
- 🔧 优化项目结构说明

### v2.1 (2025-02-08)
- ✨ 重组项目结构，分离脚本和配置文件
- 📁 脚本文件移至 `scripts/` 目录
- 📁 CMake配置移至 `cmake-config/` 目录
- 📝 更新文档以反映新结构

### v2.0 (2025-02-08)
- ✨ 整合所有测试脚本到 `test.sh`
- ✨ 优化编译脚本文档和帮助信息
- ✨ 统一项目文档结构
- 🐛 删除冗余的测试脚本

### v1.0 (2025-02-07)
- 🎉 初始版本
- ✅ 基础编译和测试功能
- ✅ 支持所有 Cortex-M 系列 MCU
- ✅ 跨平台支持

---

## 📄 许可证

本项目采用 MIT 许可证。

---

**祝你开发顺利！🎉**

如有问题或建议，欢迎反馈。