Zig 工具链编译 STM32 开发指南

Zig 工具链编译 STM32 开发指南参考仓库ZigEmbeddedGroup/stmicro-stm32本项目为 STM32 提供 Zig 嵌入式开发支持全程使用 Zig 原生工具链无需额外安装 ARM GCC 交叉编译器。目录环境准备仓库与 build.zig 简介编译官方示例工程固件烧录ST-Link基于 build.zig 创建自定义工程调试OpenOCD Zig GDB常见问题参考资料1. 环境准备1.1 安装 Zig访问 Zig 官网下载对应操作系统的 Zig 二进制包推荐使用仓库兼容的稳定版本。Zig 内置交叉编译能力不需要单独安装arm-none-eabi-gcc。验证安装zig version1.2 克隆 stmicro-stm32 仓库gitclone https://github.com/ZigEmbeddedGroup/stmicro-stm32.gitcdstmicro-stm32仓库目录结构stmicro-stm32/ ├── build.zig # 核心构建脚本 ├── build.zig.zon # 依赖清单 ├── src/ # 芯片寄存器定义、启动文件、底层支持 ├── examples/ # 示例项目blink 点灯等 └── README.md2. 仓库与 build.zig 简介build.zig是 Zig 的构建脚本作用等同于 C/C 开发中的CMakeLists.txt或Makefile。仓库内build.zig主要完成以下工作定义嵌入式目标架构ARM Cortex-Mthumbv7m-none-eabi加载链接脚本引入.ld文件配置 Flash、RAM 内存地址布局引入底层文件加载芯片启动汇编文件、寄存器定义设置编译选项配置无标准库freestanding、优化等级、链接垃圾回收自动生成固件输出.elf和.bin文件注意嵌入式环境为 freestanding不依赖 libc。3. 编译官方示例工程3.1 编译点灯示例 blink# 指定示例 blink 指定芯片 stm32f103c8t6zig build-Dexampleblink-Dchipstm32f103c8t6参数说明-Dexamplexxx选择examples/目录下的示例名称-Dchipxxx指定 STM32 芯片型号3.2 编译产物说明编译输出目录位于zig-out/firmware/firmware.elf带调试信息的 ELF 文件用于 GDB 调试firmware.bin纯二进制固件用于烧录到芯片 Flash查看产物命令lszig-out/firmware/4. 固件烧录ST-Link安装 stlink 工具集后使用st-flash进行烧录。# 将 bin 固件烧录到 STM32 Flash 起始地址 0x08000000st-flashwritezig-out/firmware/firmware.bin 0x8000000# 复位芯片运行程序st-flash reset备选方案也可以使用 OpenOCD 进行烧录。5. 基于 build.zig 创建自定义工程新建工程最简build.zig模板如下const std import(std); pub fn build(b: *std.Build) void { // 嵌入式目标配置 Cortex-M3 const target b.standardTargetOptions(.{ .default_target .{ .cpu_arch .thumb, .cpu_model .{ .explicit std.Target.arm.cpu.cortex_m3 }, .os .freestanding, .abi .eabi, }, }); const optimize b.standardOptimizeOption(.{ .default .ReleaseSmall }); // 创建可执行固件 const exe b.addExecutable(.{ .name my_firmware, .root_source_file b.path(src/main.zig), .target target, .optimize optimize, .strip false, }); // 嵌入式关键配置 exe.setLinkerScript(b.path(stm32f103.ld)); exe.addAssemblyFile(b.path(src/startup_stm32f103.s)); exe.link_gc_sections true; exe.link_data_sections true; // 生成 .bin 文件 const bin b.addObjCopy(exe, .{ .format .bin, }); bin.step.dependOn(exe.step); b.installArtifact(bin); // 安装 ELF b.installArtifact(exe); }6. 调试OpenOCD Zig GDB第一步启动 OpenOCD在新终端中运行以下命令openocd-finterface/stlink.cfg-ftarget/stm32f1x.cfg第二步启动 Zig GDB在另一个终端中运行zig gdb zig-out/firmware/firmware.elf第三步GDB 调试指令进入 GDB 交互界面后依次执行(gdb) target remote :3333 (gdb) monitor reset halt (gdb) load (gdb) continue7. 常见问题7.1 链接报错找不到内存区域原因检查链接脚本.ld中的 Flash/RAM 大小是否和你实际使用的芯片匹配。7.2 烧录成功芯片不运行原因确认启动文件 startup 汇编、中断向量表配置是否正确。确认 Flash 起始地址是否为0x08000000。7.3 编译提示无法使用 libc 函数原因嵌入式是 freestanding 环境没有 libc必须使用 Zig 无标准库写法。8. 参考资料stmicro-stm32 仓库Zig 构建系统官方文档Zig Embedded GroupZig 嵌入式社区