第2章：OpenOCD 安装与编译——从源码开始，把主动权握在自己手里

说实话，我第一次用 OpenOCD 的时候，也是直接 apt-get install 一把梭。省事是真省事，但后来踩了个大坑——板子上用的调试器是某国产 FT2232H 克隆版，系统自带的 OpenOCD 死活认不出来。从那以后，我养成了一个习惯：但凡做嵌入式调试，OpenOCD 一定自己编译。源码在手，驱动版本、补丁、编译选项全都能控，出了问题也知道去哪翻。

这一章，我就带你走一遍从源码编译 OpenOCD 的完整流程。Linux 和 Windows 我都会讲，重点放在 Linux 上——毕竟这是 OpenOCD 的主战场。Windows 那边，我会给一套 MinGW 的可靠方案。

2.1 为什么非要自己编译？

你可能会问：包管理器里直接装不香吗？嗯，分情况。我列个表，你自己对比一下：

对比项 包管理器安装 源码编译
版本控制 通常滞后 1-2 个大版本 Git 主干或任意 tag
驱动支持 只包含发行版打包时的驱动 可选开启/关闭，支持最新调试器
调试器兼容性 常见 J-Link、ST-Link 没问题 FTDI、CMSIS-DAP、USB-JTAG 等全可控
补丁能力 无法修改源码 可打私有补丁，适配非标硬件
调试符号 通常不带 debug 符号 可编译 debug 版本，方便追 OpenOCD 自身问题

我的建议：开发机上至少保留一份源码编译的 OpenOCD。哪怕平时用系统自带的，出问题时切到自编译版本，往往能快速定位是 OpenOCD 版本问题还是配置问题。

2.2 依赖库：先把地基打牢

OpenOCD 的依赖不算多，但每个都很关键。我按重要程度排个序：

2.2.1 libusb —— 一切 USB 通信的基础

OpenOCD 跟调试器通信，99% 走的是 USB。libusb 就是那个桥梁。我个人习惯用 libusb-1.0，稳定且跨平台。

# Ubuntu/Debian
sudo apt-get install libusb-1.0-0-dev

# Fedora/RHEL
sudo dnf install libusb1-devel

# Arch Linux
sudo pacman -S libusb

一个小坑：有些老教程让你装 libusb-0.1，千万别。OpenOCD 从 0.8.0 开始就全面迁移到 libusb-1.0 了。我曾经在一个旧项目里看到有人还在用 0.1 版本，结果编译报错一堆 undefined reference，折腾了半天才发现是 libusb 版本不对。

2.2.2 libftdi —— FTDI 芯片调试器的专属驱动

如果你用的是 FT2232H、FT232H 这类 FTDI 芯片做的调试器，这个库必须装。注意，有两个版本：libftdi1 和 libftdi。OpenOCD 推荐用 libftdi1。

sudo apt-get install libftdi1-dev libftdi-dev

2.2.3 hidapi —— 处理 HID 协议的调试器

有些调试器走的是 HID 协议，比如某些 CMSIS-DAP 实现。hidapi 就是为它们准备的。

sudo apt-get install libhidapi-dev

2.2.4 其他可选依赖

库名 用途 什么时候需要
libjaylink Segger J-Link 支持 用 J-Link 调试器时
libcapstone 反汇编引擎 需要 OpenOCD 内部反汇编时
libgmp / libmpfr 数学库 某些 ARM 目标需要

2.3 Linux 下编译：我的标准流程

好，依赖装完了，开始动手。这是我用了好几年的编译脚本，基本没出过问题：

# 1. 克隆源码（建议用稳定分支）
git clone https://git.code.sf.net/p/openocd/code openocd
cd openocd

# 2. 初始化子模块（重要！）
git submodule init
git submodule update

# 3. 生成 configure 脚本
./bootstrap

# 4. 配置编译选项（这里我开了常用驱动）
./configure \
  --enable-ftdi \
  --enable-stlink \
  --enable-jlink \
  --enable-cmsis-dap \
  --enable-usb-blaster-2 \
  --prefix=/usr/local

# 5. 编译（-j 后面跟 CPU 核心数）
make -j$(nproc)

# 6. 安装
sudo make install

注意：第 2 步的 git submodule update 很多人会漏掉。OpenOCD 依赖的 jimtcl 和 libjaylink 是以子模块形式管理的。不更新的话，编译到一半会报 jim.h: No such file 之类的错误。我刚开始也踩过这个坑，排查了半小时才发现是子模块没拉。

2.3.1 配置选项详解

configure 这一步很关键。我建议你按需开启驱动，不要全开——全开虽然能用，但编译出来的二进制会大不少，而且有些驱动之间有冲突。下面是我常用的选项说明：

选项 对应调试器 备注
--enable-ftdi FT2232H/FT232H 等 FTDI 芯片 最常用，国产调试器大多基于此
--enable-stlink ST-Link/V2/V3 ST 开发板必备
--enable-jlink Segger J-Link 商业调试器，稳定但贵
--enable-cmsis-dap CMSIS-DAP 兼容调试器 ARM 官方标准，很多开源调试器用
--enable-usb-blaster-2 Altera/Intel USB-Blaster II FPGA 调试时用

2.4 Windows 下编译：MinGW 方案

Windows 下编译 OpenOCD 确实比 Linux 麻烦一些。我试过 MSYS2 + MinGW 的方案，是目前最靠谱的。具体步骤：

  1. 安装 MSYS2：从官网下载安装包，一路下一步。
  2. 安装 MinGW 工具链：打开 MSYS2 终端，执行 pacman -S mingw-w64-x86_64-toolchain。
  3. 安装依赖库：pacman -S mingw-w64-x86_64-libusb mingw-w64-x86_64-libftdi mingw-w64-x86_64-hidapi。
  4. 编译：跟 Linux 流程一样，只是 configure 时加上 --host=x86_64-w64-mingw32。
./configure --host=x86_64-w64-mingw32 \
  --enable-ftdi --enable-stlink --enable-jlink \
  --enable-cmsis-dap --prefix=/usr/local
make -j$(nproc)
make install

Windows 用户的避坑指南：我曾经在 Windows 上编译时，libusb 的 .dll 文件没放到 PATH 里，结果 OpenOCD 启动就报 libusb-1.0.dll not found。解决方案很简单：把 MSYS2 安装目录下的 mingw64/bin 加到系统 PATH 里，或者直接把需要的 .dll 复制到 OpenOCD 可执行文件同目录下。

2.5 验证安装：跑几个命令试试

编译安装完了，怎么知道它能不能用？别急着连板子，先跑几个命令验证一下：

# 查看版本
openocd --version

# 查看支持的调试器列表（重点！）
openocd --list-interfaces

# 查看支持的目标芯片列表
openocd --list-targets

# 查看帮助（确认所有驱动都编译进去了）
openocd --help | grep "enable"

正常输出应该类似这样：

Open On-Chip Debugger 0.12.0+dev-xxxxx
Licensed under GNU GPL v2

--list-interfaces 会输出：
  ftdi
  stlink
  jlink
  cmsis-dap
  ...

验证重点：检查 --list-interfaces 的输出里有没有你需要的调试器。比如你用 FT2232H，就必须看到 ftdi。如果没看到，说明 configure 时没开对应的 --enable-xxx 选项，回去重新编译吧。

2.6 本章知识结构图

下面这张 SVG 图，把整个编译流程和关键决策点串起来了。你可以把它当作一张「避坑地图」：

OpenOCD 源码编译流程与关键决策点 OpenOCD 源码编译流程与关键决策点 1. 安装依赖库 libusb libftdi hidapi 2. 克隆源码 ⚠ 别忘了 git submodule update 3. configure --enable-ftdi --enable-stlink 等 4. make -j$(nproc) 5. 验证安装 openocd --version openocd --list-interfaces

2.7 常见编译错误与解决

编译过程中难免遇到问题。我把这些年遇到最多的几个错误列出来，你遇到了可以直接查：

错误信息 原因 解决方案
jim.h: No such file or directory 子模块未初始化 执行 git submodule update --init
libusb-1.0 not found libusb 开发包未安装 安装 libusb-1.0-dev
ftdi.h: No such file libftdi 开发包未安装 安装 libftdi1-dev
undefined reference to 'hid_init' hidapi 未链接 安装 libhidapi-dev 并重新 configure
configure: error: need libjaylink J-Link 支持需要 libjaylink 安装 libjaylink-dev 或去掉 --enable-jlink

终极方案：如果编译报错且一时找不到原因，试试 make clean 然后重新 ./configure。有时候 configure 缓存了错误的检测结果，清掉重来就好了。我遇到过好几次这种「玄学」问题，最后都是 clean 重编解决的。

2.8 小结

这一章的内容其实就三件事：装依赖、编译、验证。但每一步都有细节，漏掉一个就可能卡住半天。我个人建议你把编译脚本保存下来，以后换机器或者升级 OpenOCD 版本时，直接跑一遍就行。

← 上一章 📖 返回目录 下一章 →