objdiff CLI使用教程:diff交互模式与report报告模式一次讲清
objdiff CLI使用教程:diff交互模式与report报告模式一次讲清
objdiff 是一个面向反编译项目的本地目标文件对比工具,其命令行版本 objdiff-cli 提供两大核心模式:终端交互的 diff 交互模式(实时汇编差异对比 + 自动重新构建)与批量生成项目进度报告的 report 报告模式。本文从安装到实战,带你一次讲清这两个命令。🛠️
objdiff 是什么:反编译对比工具速览
反编译项目通常有两套目标文件(.o):
- target(目标/期望):从原始固件中提取的参考对象文件;
- base(基准/当前):由你当前反编译出的源码重新编译得到的对象文件。
objdiff 会对两者做逐指令对比,告诉你"还有哪些指令没对上"以及"完成度离 100% 有多近"。它支持 ARM(GBA/DS/3DS)、ARM64(Switch)、MIPS(N64/PS2)、PowerPC(Wii/Xbox 360)、SuperH(Saturn/Dreamcast)、x86/x86_64 等平台,并内置 C++ 符号还原(demangle)能力(GCC、MSVC、CodeWarrior、Itanium 命名约定)。
项目提供 GUI、CLI/TUI、Web 三种前端,其中 CLI(源码位于 objdiff-cli/)与 GUI 共享同一套核心对比逻辑,特别适合在远程服务器、CI 流水线与脚本自动化场景中使用。
上图为 GUI 版对比视图(CLI 交互模式在终端中展示同样的信息):左栏 TARGET、右栏为当前编译结果,中间列标注差异类型,顶部显示匹配率百分比。
快速安装:两种方法拿到 objdiff-cli
方法一:下载预编译二进制(推荐)
官方 releases 页面提供 Windows / Linux / macOS 的 objdiff-cli 可执行文件,下载后即可直接使用。
方法二:从源码构建
需要 Rust 工具链(可用 rustup 安装),然后执行:
git clone https://gitcode.com/gh_mirrors/ob/objdiff
cd objdiff
cargo install --path objdiff-cli --locked
验证安装:
objdiff-cli -V
objdiff-cli diff --help
💡 构建后二进制会安装到
~/.cargo/bin下;GUI 版本命令为objdiff,本文聚焦objdiff-cli。
前置条件:objdiff.json 项目配置文件
多数项目级命令依赖项目根目录下的 objdiff.json,它声明每个对象文件(unit)的 target/base 路径与构建方式。最小示例:
{
"custom_make": "make",
"build_base": true,
"units": [
{
"name": "src/main",
"target_path": "target/main.o",
"base_path": "build/main.o"
}
]
}
常用字段:
custom_make/custom_args:构建系统与额外参数(例如ninja -d keeprsp);build_base:objdiff 是否自动重新编译 base 对象(默认开启);watch_patterns:监听源码变化模式,文件变化时自动触发重建。
全部字段说明见 config.schema.json。
diff 交互模式:一条命令打开 TUI
三种启动方式
# 1) 项目模式:自动在 objdiff.json 中查找包含该符号的 unit
objdiff-cli diff main
# 2) 项目模式:显式指定项目目录与 unit 名称
objdiff-cli diff -p /path/to/project -u src/main main
# 3) 直接对比两个对象文件
objdiff-cli diff -1 target/main.o -2 build/main.o main
启动后终端进入 TUI:左栏 TARGET、右栏 CURRENT,顶栏显示当前符号匹配率与上次重载时间。CLI 会按配置自动重建 base 对象,并在被监听的源文件发生变化时自动重新对比——命令解析与状态管理逻辑见 objdiff-cli/src/cmd/diff.rs。
⌨️ 交互模式按键速查表
按键处理实现于 objdiff-cli/src/views/function_diff.rs:
| 按键 | 功能 |
|---|---|
j / k、↑ / ↓ |
逐行下 / 上滚动 |
h / l、← / → |
左右横向滚动 |
Space / PageDown(或 Ctrl+f) |
向下翻页 |
Shift+Space / PageUp(或 Ctrl+b) |
向上翻页 |
Ctrl+d / Ctrl+u |
半页下 / 上滚动 |
g / G |
跳到顶部 / 底部 |
r |
手动重建并重新加载 |
x |
循环切换重定位显示模式(关 / 名称+地址 / 数据值 / 全部) |
3 |
切换三路对比(多出一列 SAVED) |
o |
打开 / 关闭选项面板 |
q / Esc |
退出 |
| 鼠标滚轮 / 左键点击 | 滚动 / 高亮数值与寄存器 |
一次性模式:同样的 diff,无需交互
加上 -o 参数,对比结果直接写入文件(-o - 表示输出到 stdout):
objdiff-cli diff -1 a.o -2 b.o -o diff.json --format json-pretty
--format支持json(默认)、json-pretty、proto(二进制 protobuf);- 非常适合 CI:每次提交后保存一份 JSON,便于回归对比;
- 输出字段定义见 objdiff-core/protos/diff.proto。
注意:交互模式必须提供函数符号名(位置参数);一次性模式可以省略符号,直接对比整个对象文件。
report 报告模式:一条命令看项目进度
report 子命令读取 objdiff.json,对整个项目并行 diff,生成可驱动进度看板的项目级报告,子命令实现位于 objdiff-cli/src/cmd/report.rs。
report generate:生成进度报告
# 输出到 stdout(默认 json 格式)
objdiff-cli report generate
# 以 proto 二进制格式写入文件,并启用全局符号去重
objdiff-cli report generate -o progress.bin -f proto -d
报告内容包括:每个 unit 的各 section、各函数的匹配率,以及 matched_code / total_code(代码匹配字节数)、complete_units / total_units(完成单元数)等汇总指标,字段定义见 objdiff-core/protos/report.proto。
常用参数:
-p:指定项目目录(默认当前目录);-d:对 global/weak 符号去重(单线程执行,适合重复符号多的项目);-c key=value:覆盖任意 diff 配置项,例如-c combine_text_sections=false。
图中每个函数的匹配百分比(绿色 100% 表示完全匹配)与对象树结构,正是 report generate 汇总进报告的同一份数据。
report changes:对比两份报告
objdiff-cli report changes progress_last.bin progress_now.bin
对比两份报告,输出新增、移除或发生变化的函数与单元,非常适合在 CI 中"看看这次提交推进了多少"。输入文件需为 proto 格式(即用 -f proto 生成),输出字段见 objdiff-core/protos/changes.proto。
实用技巧与常见问题
| 现象 | 解决办法 |
|---|---|
Project config not found in ... |
未找到 objdiff.json,用 -p 指向项目根目录 |
Unit not found: xxx |
-u 名称与配置 units[].name 不一致 |
Symbol not found: xxx |
符号名与对象文件内符号名不匹配,检查拼写 |
| TUI 中构建失败 | 检查 custom_make / custom_args;加 -L debug 查看更详细日志 |
全局常用参数:-C <dir> 切换工作目录、-L <level> 调整日志级别(error ~ trace)、--no-color 关闭彩色输出。
总结
| 使用场景 | 推荐命令 |
|---|---|
| 人工逐函数调试 | objdiff-cli diff SYMBOL(交互 TUI) |
| CI 归档 diff 结果 | objdiff-cli diff -o diff.json(一次性模式) |
| 生成进度看板数据 | objdiff-cli report generate |
| 对比两个时间点的进度 | objdiff-cli report changes a b |
diff 交互模式是反编译过程的"放大镜",report 报告模式则是项目的"仪表盘",两者组合就覆盖了 objdiff CLI 的完整工作流。

