objdiff CLI使用教程:diff交互模式与report报告模式一次讲清

原创2026-11-14 15:40:30301 阅读

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 流水线与脚本自动化场景中使用。

objdiff 反编译 diff 对比视图:两栏汇编并排展示,用颜色高亮差异指令与函数匹配率

上图为 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。

objdiff 项目符号列表与各函数匹配百分比视图

图中每个函数的匹配百分比(绿色 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 的完整工作流。

登录后查看全文
objdiff