# elfparser

**Repository Path**: stesen/elfparser

## Basic Information

- **Project Name**: elfparser
- **Description**: elf文件的解析和反汇编工具，基于rust，caoptone，graphviz，代码全是AI xjbx的
- **Primary Language**: Rust
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-02-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ELF Parser

一个功能弱鸡的 ELF 文件解析工具，支持 ARM64/x86 反汇编和控制流图可视化。

**版本**: 0.9.5

## 功能特性

- **ELF 文件解析**：支持 32/64 位 ELF 格式，显示节区（Section）和段（Segment）信息
- **多架构反汇编**：支持 ARM64、x86、x86_64 架构（基于 Capstone 引擎）
- **控制流图生成**：生成函数的控制流图（CFG），支持 DOT/ASCII/PDF 格式
- **GUI 可视化**：交互式控制流图界面，支持拖拽、平缩放、选中高亮
- **TUI 终端界面**：终端交互式控制流图，支持键盘导航、缩放、语法高亮
- **内容复制**：选中 block 后可点击 Copy 按钮复制汇编代码到剪贴板
- **符号解析**：支持函数符号、PLT/GOT 条目解析
- **DWARF 调试信息**：查询符号名称、显示类/结构体内存布局、成员偏移
- **源码位置**：显示函数和类的源码文件路径及行号信息（与 addr2line 一致）
- **智能注释**：`-v` 参数为每条汇编指令添加自然语言解释，并分析函数整体行为
- **地址分析**：显示地址在段和节中的偏移量、LoadBias 计算
- **彩色输出**：Flat 模式使用 Atom Code Dark 主题，PDF 模式使用 Atom Code Light 主题
- **readelf 兼容**：提供与 `readelf -a` 类似的功能，包括程序头、节区头、重定位、动态段、Note 段等
- **🆕 MCP 服务器**：支持作为 Model Context Protocol 服务器运行，提供 AI 助手集成功能

## 使用方法

### 基本用法

```bash
# 显示 ELF 文件基本信息
elfparser <ELF文件> -a

# 反汇编指定地址
elfparser <ELF文件> -d <地址>

# 生成控制流图（DOT 格式）
elfparser <ELF文件> -d <地址> --dot

# 生成控制流图（PDF 格式，需要 Graphviz）
elfparser <ELF文件> -d <地址> --pdf

# ⭐ 推荐：生成 DOT 并自动转换为 PDF（需要 Graphviz）
elfparser <ELF文件> -d <地址> --dot2pdf

# 生成 Excalidraw 格式（可导入 excalidraw.com 编辑）
elfparser <ELF文件> -d <地址> --excalidraw

# 查询符号信息（函数/类/结构体）
elfparser <ELF文件> -s <符号名>

# 启动 TUI 终端交互界面
elfparser <ELF文件> -d <地址> --tui

# 启动 GUI 图形界面
elfparser <ELF文件> -d <地址> --gui
```

### 命令行参数

```
Usage: elfparser <FILE> [OPTIONS]

Arguments:
  <FILE>  ELF文件路径

Options:
  -a                 显示所有 ELF 信息
  -d <ADDRESS>       反汇编指定地址（支持 0x 前缀的十六进制或十进制）
  -v, --verbose      详细模式：为汇编指令添加自然语言解释，并分析函数整体行为
  -V, --version      显示版本信息
      --dot          生成 DOT 格式控制流图
      --dot2pdf      生成 DOT 并自动转换为 PDF（推荐，需要 Graphviz）
      --pdf          生成 PDF 格式控制流图（需要 Graphviz）
      --excalidraw   生成 Excalidraw 格式控制流图（.excalidraw）
      --tui          启动 TUI 终端交互界面
      --gui          启动 GUI 图形界面
      --mcp          启动 MCP 服务器（AI 助手集成模式）
  -s <SYMBOL>        查询符号名称（支持 DWARF 调试信息）
  -h, --help         显示帮助信息
```

### TUI 模式（终端交互界面）

```bash
# 启动 TUI 终端交互界面
elfparser <ELF文件> -d <地址> --tui
```

**TUI 功能**：
- **交互式控制流图**：使用键盘导航和选择 block
- **键盘控制**：
  - `q` / `Esc`: 退出
  - `h` / `?`: 显示帮助
  - `Space`: 切换 Split/Merged 显示模式
  - `p`: 切换右侧面板显示
  - `Tab` / `→`: 下一个 block
  - `Shift+Tab` / `←`: 上一个 block
  - `↑` / `w`: 向上滚动
  - `↓` / `s`: 向下滚动
  - `a`: 向左滚动
  - `d`: 向右滚动
  - `+` / `=`: 放大
  - `-`: 缩小
  - `0`: 重置视图
- **右侧面板**：显示选中 block 的详细信息
  - **Selected Block**: 地址、ID、指令数量
  - **Source Lines**: 源代码行信息（如果有 DWARF 调试信息）
  - **Address Info**: 函数地址、符号名
  - **Segment**: PT_LOAD 段信息
  - **Section**: 节区信息
  - **Assembly**: 汇编指令 + 语法高亮 + 中文解释
- **语法高亮**：
  - 地址：青色
  - 字节码：品红
  - 助记符：黄色加粗
  - 操作数：白色
  - 注释：黄色
  - 指令解释：浅蓝色

### GUI 模式（图形界面）

```bash
# 启动 GUI 图形界面
elfparser <ELF文件> -d <地址> --gui
```

**GUI 功能**：
- **交互式控制流图**：点击选中 block，显示详细信息
- **拖拽移动**：按住 block 标题栏可拖拽移动
- **平移画布**：按住空白区域拖拽平移视图
- **滚轮缩放**：使用鼠标滚轮缩放视图
- **信息面板**：右侧显示选中 block 的详细信息
- **复制内容**：点击 Copy 按钮复制汇编代码到剪贴板
  - Verbose 模式：复制汇编 + 注释
  - 普通模式：仅复制汇编

---

## MCP 服务器（AI 助手集成）

elfparser 支持作为 **MCP (Model Context Protocol)** 服务器运行，允许 AI 助手（如 Claude、Cursor）直接调用 elfparser 的分析功能。

### 什么是 MCP？

MCP 是 [Model Context Protocol](https://modelcontextprotocol.io/) 的缩写，是由 Anthropic 推出的开放协议，用于标准化 AI 助手与外部工具的集成。通过 MCP，AI 助手可以直接访问 elfparser 的 ELF 分析能力。

### 启动 MCP 服务器

```bash
elfparser --mcp
```

服务器将以 JSON-RPC 2.0 协议通过标准输入输出 (stdio) 与 AI 助手通信。

### AI 助手配置

#### Claude Desktop 配置

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 或 `%APPDATA%\Claude\claude_desktop_config.json` (Windows)：

```json
{
  "mcpServers": {
    "elfparser": {
      "command": "/path/to/elfparser",
      "args": ["--mcp"]
    }
  }
}
```

#### Cursor 配置

在项目根目录创建 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "elfparser": {
      "command": "/path/to/elfparser",
      "args": ["--mcp"]
    }
  }
}
```

#### 其他 MCP 客户端

任何支持 stdio 传输的 MCP 客户端都可以使用相同的配置方式。

### 提供的工具

| 工具名 | 描述 | 参数 |
|--------|------|------|
| `mcp_elf_analyze_file` | 分析 ELF 文件基本信息 | `file_path` |
| `mcp_elf_list_symbols` | 列出符号表 | `file_path`, `symbol_type`, `limit` |
| `mcp_elf_resolve_address` | 解析地址到源码位置 | `file_path`, `address` |
| `mcp_elf_find_function` | 查找函数信息 | `file_path`, `function_name` |

#### 工具详情

**mcp_elf_analyze_file**
```json
{
  "file_path": "/path/to/libexample.so"
}
```
返回：文件类型、架构、节区数量、段数量、符号数量等基本信息。

**mcp_elf_list_symbols**
```json
{
  "file_path": "/path/to/libexample.so",
  "symbol_type": "function",
  "limit": 10
}
```
- `symbol_type`: 可选 `function` | `object` | `all`
- `limit`: 最多返回的符号数量

返回：符号列表（名称、地址、大小、类型、绑定等）。

**mcp_elf_resolve_address**
```json
{
  "file_path": "/path/to/libexample.so",
  "address": "0x7bc4"
}
```
返回：地址对应的函数名、源文件路径、行号（需 DWARF 调试信息）。

**mcp_elf_find_function**
```json
{
  "file_path": "/path/to/libexample.so",
  "function_name": "main"
}
```
返回：函数地址、大小、源文件位置等详细信息。

### 提供的资源

通过 `elf://` URI 协议访问 ELF 文件数据：

| URI 模板 | 描述 |
|----------|------|
| `elf://{file_path}/header` | ELF 头信息 |
| `elf://{file_path}/sections` | 节区列表 |
| `elf://{file_path}/symbols` | 符号列表 |

### MCP 使用场景

**场景 1：调试崩溃日志**
```
用户: 我的程序在地址 0x7bc4 崩溃了，帮我看看这是哪里
      文件: /path/to/libexample.so

AI: 正在解析地址...
    [调用 mcp_elf_resolve_address]
    
    结果:
    - 函数: __unw_remove_dynamic_fde
    - 源文件: libunwind.cpp:309
    - 这是一个 unwind 库函数，用于移除动态 FDE 条目
```

**场景 2：探索二进制文件**
```
用户: 分析这个 so 文件有哪些功能
      文件: /path/to/libcrypto.so

AI: 让我分析该库的功能...
    [调用 mcp_elf_analyze_file]
    [调用 mcp_elf_list_symbols 获取函数列表]
    
    该库包含:
    - 算法: AES_encrypt, RSA_sign, SHA256_Update...
    - 工具: BIO_new, PEM_read...
    - 共 1256 个函数符号
```

**场景 3：源码定位**
```
用户: 查找 RSA_encrypt 函数在源码中的位置
      文件: /path/to/libcrypto.so

AI: 正在查找函数...
    [调用 mcp_elf_find_function]
    
    结果:
    - 地址: 0x45678
    - 大小: 256 字节
    - 源文件: crypto/rsa/rsa_enc.c:89
```

### 交互示例

配置完成后，你可以在 AI 助手中这样使用：

```
用户: 请分析这个文件 /path/to/libexample.so
AI: 我将使用 elfparser 分析该文件...
    [调用 mcp_elf_analyze_file]
    文件架构: ARM64
    符号数量: 447
    ...

用户: 查找地址 0x7bc4 的源码位置
AI: 正在解析地址...
    [调用 mcp_elf_resolve_address]
    文件: libunwind.cpp
    行号: 309
    函数: __unw_remove_dynamic_fde

用户: 列出前 10 个函数符号
AI: [调用 mcp_elf_list_symbols]
    1. __do_init @ 0x5c9c
    2. __do_fini @ 0x5d10
    ...
```

### 测试 MCP 服务器

手动测试 MCP 服务器：

```bash
# 初始化
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | elfparser --mcp

# 列出工具
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | elfparser --mcp

# 分析文件
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"mcp_elf_analyze_file","arguments":{"file_path":"/path/to/file.so"}}}' | elfparser --mcp

# 解析地址
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"mcp_elf_resolve_address","arguments":{"file_path":"/path/to/file.so","address":"0x7bc4"}}}' | elfparser --mcp
```

### MCP 架构说明

elfparser MCP 服务器采用轻量级实现：

- **协议**: JSON-RPC 2.0 over stdio
- **无外部 SDK 依赖**: 直接使用 serde/serde_json 实现 MCP 协议
- **文件缓存**: 已解析的 ELF 文件会被缓存，重复查询更快
- **DWARF 支持**: 完整支持 DWARF 调试信息解析

**协议流程**:
```
AI 客户端 → JSON-RPC 请求 → elfparser --mcp → JSON-RPC 响应 → AI 客户端
                ↓
         ELF 文件解析
         符号表查询
         DWARF 行号解析
```

### 故障排除

**MCP 服务器无法启动**
```bash
# 检查 elfparser 是否安装正确
elfparser --version

# 检查 MCP 模式是否正常
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | elfparser --mcp
```

**AI 助手无法连接**
- 检查配置文件路径是否正确
- 确保 `elfparser` 在系统 PATH 中，或使用绝对路径
- 查看 AI 助手的 MCP 日志排查问题

**地址解析失败**
- 确认 ELF 文件包含 DWARF 调试信息: `readelf --debug-dump=line <文件>`
- 检查地址格式是否正确（需 `0x` 前缀）
- 确认地址在可执行段范围内

**符号查找失败**
- 确认符号在 ELF 符号表中: `nm -C <文件> | grep <符号名>`
- 注意符号名区分大小写
- C++ 符号可能需要使用 mangled 名称

### 与 addr2line 对比

| 功能 | addr2line | elfparser MCP |
|------|-----------|---------------|
| 地址解析 | ✅ | ✅ |
| 符号列表 | ❌ | ✅ |
| 函数查找 | ❌ | ✅ |
| AI 集成 | ❌ | ✅ |
| 批量查询 | ❌ | ✅ |
| 文件缓存 | ❌ | ✅ |

**精度验证**:
elfparser 的地址解析精度与 `addr2line` 完全一致，已在多个 ARM64 SO 文件上验证。

---

### 使用示例

#### 1. 查看 ELF 文件信息

```bash
elfparser /bin/ls -a
```

输出示例：
```
ELF Header:
  Magic:                           7f 45 4c 46
  Class:                           64-bit
  Data:                            Little Endian
  ...
```

#### 2. 反汇编指定地址

```bash
# 使用十六进制地址
elfparser libexample.so -d 0x9db94c

# 使用十进制地址
elfparser libexample.so -d 10342380
```

输出示例：
```
Looking for address 0x9db94c:
Found in PT_LOAD segment:
  Type: PT_LOAD
  VirtAddr: 0x9d9000
  PhysAddr: 0x9d9000
  Offset:   0x5d9000
  FileSiz:  0x...
  MemSiz:   0x...
  Flags:    0x5 (r-x)
  Align:    0x1000
  LoadBias: 0x400000 (calculated as VirtAddr - Offset)
  Segment Offset: 0x294c (10572 bytes from segment start)
Found in section .text (.text)
  Type:    PROGBITS
  Address: 0x9d9000
  Offset:  0x5d9000
  Size:    0x...
  Section Offset: 0x294c (10572 bytes from section start)
This is a code section, disassembling...
Function: example_function
Address range: 0x9db800 - 0x9dbb00
  --> 0x9db94c: mov  x0, x1    ; some_function.plt
      0x9db950: blr  x2
      ...
```

#### 3. 详细模式（智能注释）

```bash
# 为反汇编添加自然语言注释
elfparser libexample.so -d 0x9db94c -v

# 生成带注释的 PDF 控制流图
elfparser libexample.so -d 0x9db94c -v --pdf

# 生成带注释的 DOT 文件
elfparser libexample.so -d 0x9db94c -v --dot
```

输出示例：
```
[函数分析]
这是一个子程序函数。分配了 32 字节的栈空间用于局部变量。包含条件分支。调用了一个外部函数。进行比较操作。

Disassembly:
  --> 0x9db93c: sub sp, sp, #0x20
      # 减法运算: sp, sp, #0x20 (从第一个操作数中减去第二个操作数)
      0x9db940: stp x29, x30, [sp, #0x10]
      # 存储一对寄存器: x29, x30, [sp, #0x10] (将两个64位值同时写入内存)
      0x9db944: add x29, sp, #0x10
      # 加法运算: x29, sp, #0x10 (将两个操作数相加)
      ...
```

#### 4. 查询符号信息（DWARF 调试信息）

```bash
# 查询函数符号
elfparser libexample.so -s ngtcp2_gaptr_free

# 查询类/结构体符号
elfparser libexample.so -s RpcStreamProvider

# 查询带命名空间的符号
elfparser libexample.so -s ignet::RpcStreamProvider
```

输出示例：
```
Looking up symbol 'ngtcp2_gaptr_free'...
Found symbol 'ngtcp2_gaptr_free'
Type: Function
Address: 0x9db93c
Size: 64 bytes
Source: /path/to/source.c:116
```

类/结构体符号输出：
```
Looking up symbol 'RpcStreamProvider'...
Found symbol in DWARF: RpcStreamProvider
Type: Class
Source: src/rpc_stream_provider.h:15

Memory Layout for class 'RpcStreamProvider'
Total Size: 32 bytes (0x20)

Members:
Offset       | Size   | Name (Type)
------------------------------------------------------------
0x0000000000 | 0x0010 | [base: enable_shared_from_this<...>]
0x0000000000 | 0x0000 | _vptr$RpcStreamProvider (unknown)
0x0000000008 | 0x0000 | mRequestId (uint32_t)
```

#### 5. 生成控制流图

**⭐ 推荐方式：使用 `--dot2pdf`（一键生成 DOT + 自动转换 PDF）**

```bash
# 推荐：生成 DOT 并自动转换为 PDF（需要 Graphviz）
elfparser libexample.so -d 0x9db94c --dot2pdf

# 仅生成 DOT 文件（可手动编辑后再转换）
elfparser libexample.so -d 0x9db94c --dot

# 生成 PDF（需要 Graphviz，直接生成，不保留 DOT）
elfparser libexample.so -d 0x9db94c --pdf

# 生成 Excalidraw 格式（可导入 excalidraw.com 编辑）
elfparser libexample.so -d 0x9db94c --excalidraw

# 启动 TUI 终端交互界面
elfparser libexample.so -d 0x9db94c --tui

# 启动 GUI 图形界面
elfparser libexample.so -d 0x9db94c --gui
```

##### 输出格式对比

| 格式 | 参数 | 特点 | 适用场景 |
|------|------|------|----------|
| **DOT + PDF** | `--dot2pdf` ⭐ | 先生成 DOT，再自动调用 Graphviz 转换为 PDF | **推荐**，保留源文件且可直接查看 |
| DOT | `--dot` | 纯文本图描述文件，可手动编辑 | 需要自定义样式或后续处理 |
| PDF | `--pdf` | 直接生成 PDF，不保留 DOT | 仅需查看，不需要编辑 |
| Excalidraw | `--excalidraw` | 可导入 excalidraw.com 手绘风格编辑 | 需要手绘风格或在线协作 |

##### `--dot2pdf` 详细说明（推荐）

**工作流程：**
1. 生成 `.dot` 文件（Graphviz 图描述文件）
2. 自动调用 `dot` 命令转换为 `.pdf` 文件
3. 保留 `.dot` 源文件，方便后续手动调整

**优势：**
- ✅ 一键完成，无需手动执行转换命令
- ✅ 保留 DOT 源文件，可随时修改样式
- ✅ PDF 适合查看、打印和分享
- ✅ 支持彩色语法高亮和详细注释（使用 `-v` 参数）

**示例：**
```bash
# 基本用法
elfparser libexample.so -d 0x9db94c --dot2pdf

# 带详细注释的 PDF
elfparser libexample.so -d 0x9db94c -v --dot2pdf

# 输出文件：
# - function_name_0x9db94c.dot   (源文件)
# - function_name_0x9db94c.pdf   (PDF 文件)
```

**手动转换 DOT 到 PDF（可选）：**
如果已经生成了 DOT 文件，可以手动转换：
```bash
# 使用 Graphviz 转换为 PDF
dot -Tpdf input.dot -o output.pdf

# 转换为 PNG 图片
dot -Tpng input.dot -o output.png

# 转换为 SVG 矢量图
dot -Tsvg input.dot -o output.svg
```

##### `--excalidraw` 详细说明

生成 `.excalidraw` 文件，可导入 [excalidraw.com](https://excalidraw.com) 进行手绘风格编辑：

```bash
# 生成 Excalidraw 文件
elfparser libexample.so -d 0x9db94c --excalidraw

# 使用步骤：
# 1. 打开 https://excalidraw.com
# 2. 文件 → 打开 → 选择生成的 .excalidraw 文件
# 3. 即可在手绘风格的画布上编辑控制流图
```

**特点：**
- 手绘风格，适合演示和文档
- 支持在线协作编辑
- 可导出为 PNG/SVG/PDF

生成的文件：
- `function_name_<address>.dot` - DOT 格式图文件
- `function_name_<address>.pdf` - PDF 格式图（使用 --dot2pdf 或 --pdf 时）
- `function_name_<address>.excalidraw` - Excalidraw 格式图（使用 --excalidraw 时）

DOT 文件包含：
- 函数基本信息（地址、段、节区）
- 函数分析（使用 `-V` 参数时）
- 源码文件信息（如果有 DWARF 调试信息）
- 反汇编指令（使用 `-V` 参数时带自然语言注释）
- 控制流边和跳转关系

### 输出格式说明

#### Flat 模式（默认）

使用 Atom Code Dark 颜色主题：
- **地址**: 橙色 (#d19a66)
- **跳转指令**: 红色 (#e06c75)
- **普通指令**: 紫色 (#c678dd)
- **操作数**: 青色 (#56b6c2)
- **注释**: 灰色 (#5c6370)

#### PDF 模式

DOT 文件中使用 Atom Code Light 颜色主题，包含：
- 指令地址和偏移
- 彩色指令助记符
- Segment/Section 信息节点
- 跳转边标签（true/false）
- **边箭头指示**：蓝色表示 true 分支，红色表示 false 分支，灰色表示 fall-through

## 项目结构

```
elfparser/
├── Cargo.toml          # 项目配置
├── src/
│   ├── main.rs         # 主程序入口
│   ├── dwarf_parser.rs # DWARF 调试信息解析
│   ├── generate_function_graph.rs  # 函数图生成
│   ├── tui.rs          # TUI 终端交互界面
│   └── mcp/            # MCP 服务器模块
│       ├── mod.rs      # MCP 服务器入口
│       ├── handlers.rs # 工具和资源处理器
│       └── protocol.rs # MCP 协议定义
├── tests/
│   ├── test_elfparser.rs    # 单元测试
│   ├── test_symbol_search.rs # 符号搜索测试
│   ├── test_default_mode.rs # 默认模式测试
│   ├── test_mode_behavior.rs # 模式行为测试
│   └── test_graph.rs   # 图生成测试
├── README.md           # 本文件
└── TEST_REPORT.md      # 测试报告
```

## 技术细节

### 支持的架构
- ARM64 (AArch64)
- x86 (32-bit)
- x86_64 (64-bit)
- ARM (32-bit)

### 跳转指令支持
- **ARM64**: `b`, `b.cond`, `bl`, `blr`, `br`, `cbz`, `cbnz`, `tbz`, `tbnz`, `ret`
- **x86/x64**: `jmp`, `je/jne`, `jz/jnz`, `call`, `ret`, etc.

### DWARF 调试信息支持

支持的 DWARF 标签：
- `DW_TAG_subprogram` - 函数/子程序
- `DW_TAG_class_type` - 类类型
- `DW_TAG_structure_type` - 结构体类型
- `DW_TAG_union_type` - 联合体类型
- `DW_TAG_member` - 成员变量
- `DW_TAG_inheritance` - 继承关系
- `DW_TAG_typedef` - 类型定义
- `DW_TAG_enumeration_type` - 枚举类型

支持的源码位置属性：
- `DW_AT_decl_file` - 声明文件
- `DW_AT_decl_line` - 声明行号
- `DW_AT_decl_column` - 声明列号

### 颜色主题

#### Atom Code Dark（Flat 模式）
| 元素 | 颜色 | RGB |
|------|------|-----|
| 地址 | 橙色 | #d19a66 |
| 跳转指令 | 红色 | #e06c75 |
| 普通指令 | 紫色 | #c678dd |
| 操作数 | 青色 | #56b6c2 |
| 注释 | 灰色 | #5c6370 |

#### Atom Code Light（PDF 模式）
| 元素 | 颜色 | RGB |
|------|------|-----|
| 地址 | 橙色 | #986801 |
| 跳转指令 | 红色 | #ca1243 |
| 普通指令 | 紫色 | #a626a4 |
| 操作数 | 绿色 | #50a14f |
| 注释 | 灰色 | #a0a1a7 |

## 编译方法

### 从源码编译

```bash
# 克隆仓库
git clone <repository-url>
cd elfparser

# 编译发布版本
cargo build --release

# 编译调试版本
cargo build
```

编译完成后，可执行文件位于：
- **Linux/macOS**: `./target/release/elfparser`
- **Windows**: `.\target\release\elfparser.exe`

### 运行测试

```bash
# 运行单元测试
cargo test

# 运行所有测试（包括需要 ELF 文件的集成测试）
cargo test -- --ignored
```

## 运行依赖

### 必需依赖
- **Rust 工具链** (1.70+): https://rustup.rs/
- **Capstone 库**: 反汇编引擎
- **gimli**: DWARF 解析库 (Rust crate)
- **object**: 对象文件解析库 (Rust crate)

#### 安装 Capstone

**Ubuntu/Debian:**
```bash
sudo apt-get install libcapstone-dev
```

**macOS:**
```bash
brew install capstone
```

**Windows:**

Capstone 在 Windows 上没有官方的安装包，需要通过以下方式安装：

**方法 1：下载预编译版本（推荐）**
```powershell
# 1. 下载 Capstone 预编译版本
# 访问 https://github.com/capstone-engine/capstone/releases
# 下载 capstone-5.0.1-win64.zip 或 capstone-5.0.1-win32.zip

# 2. 解压到系统目录
# 将 capstone.dll 复制到以下位置之一：
# - 系统目录: C:\Windows\System32\ (64位系统)
# - 系统目录: C:\Windows\SysWOW64\ (32位系统)
# - 或项目目录

# 3. 设置环境变量（可选）
# 将包含 capstone.dll 的目录添加到 PATH
```

**方法 2：使用 vcpkg**
```powershell
# 安装 vcpkg（如果尚未安装）
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

# 安装 Capstone
.\vcpkg install capstone

# 集成到 Visual Studio（可选）
.\vcpkg integrate install
```

**方法 3：从源码编译**
```powershell
# 1. 克隆源码
git clone https://github.com/capstone-engine/capstone.git
cd capstone

# 2. 使用 Visual Studio 编译
# 打开 msvc\capstone.sln 并编译
# 或使用 CMake:
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release

# 3. 安装
cmake --install . --prefix "C:\Program Files\Capstone"
```

### 可选依赖（用于 PDF 生成）
- **Graphviz**: 用于将 DOT 文件转换为 PDF

#### 安装 Graphviz

**Ubuntu/Debian:**
```bash
sudo apt-get install graphviz
```

**macOS:**
```bash
brew install graphviz
```

**Windows (使用 winget):**
```powershell
# 使用 winget 安装 Graphviz
winget install graphviz

# 或者使用 chocolatey
choco install graphviz

# 或者下载安装包从 https://graphviz.org/download/
```

## 故障排除

### 编译错误：找不到 capstone

确保已安装 Capstone 开发库：
```bash
# Ubuntu/Debian
sudo apt-get install libcapstone-dev

# 设置环境变量（如果需要）
export CAPSTONE_LIB_DIR=/usr/lib
export CAPSTONE_INCLUDE_DIR=/usr/include
```

### PDF 生成失败

确保 Graphviz 已安装且 `dot` 命令在 PATH 中：
```bash
# 检查 Graphviz 安装
dot -V

# 手动生成 PDF
dot -Tpdf input.dot -o output.pdf
```

### 反汇编失败

确保 ELF 文件架构受支持，且文件未损坏：
```bash
# 检查 ELF 文件类型
file <ELF文件>
readelf -h <ELF文件>
```

### DWARF 调试信息查询失败

确保 ELF 文件包含 DWARF 调试信息：
```bash
# 检查 DWARF 信息
readelf --debug-dump=info <ELF文件> | head -20

# 检查行号信息
readelf --debug-dump=line <ELF文件> | head -20
```

如果 ELF 文件没有调试信息，可以使用 `-s` 参数查询符号表中的符号（功能受限）。

## 许可证

Apache License 2.0

Copyright 2026

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

## 更新日志

### v0.9.5 (2026-02-16)

#### 修复
- **命令行参数**：修复 clap 参数冲突，移除重复的 `-V/--version` flag（clap 自动处理版本显示）
- **编译警告**：修复 MCP 模块的编译警告
  - 移除未使用的 `handlers::*` 导入
  - 为协议合规字段添加 `#[allow(dead_code)]` 属性

### v0.9.2 (2026-02-16)

#### 新增
- **MCP 服务器支持**：添加 Model Context Protocol 服务器模式，支持 AI 助手集成
  - 新增 `--mcp` 参数启动 MCP 服务器
  - 提供 4 个分析工具：`analyze_file`, `list_symbols`, `resolve_address`, `find_function`
  - 支持 `elf://` URI 协议访问 ELF 资源（header, sections, symbols）
  - 兼容 Claude Desktop、Cursor 等 MCP 客户端
  - 地址解析精度与 `addr2line` 一致

### v0.9.1 (2026-02-15)

#### 修复
- **源位置查找**：修复 DWARF 行程序解析逻辑，地址到源文件/行号的映射现在与 `addr2line` 完全一致
  - 正确处理序列边界处的多个行条目
  - 实现行条目范围匹配（半开区间 `[start, end)`）
  - 改进匹配优先级：精确边界 > 范围匹配 > 最接近的上一行

#### 改进
- **readelf 功能对等**：增强 ELF 信息输出，提供与 `readelf -a` 类似的功能
  - 程序头标志显示为可读格式（R/RE/RW/RWE）
  - 支持 GNU_HASH 节区类型显示
  - 新增重定位节区输出（.rela.dyn / .rela.plt）
  - 新增动态段（Dynamic Section）输出
  - 新增 Note 段解析（支持 OHOS/GNU build-id）
  - 新增 GNU_STACK 程序头显示
  
- **反汇编对比**（ARM64）：
  - 修复条件码显示（支持 `b.ne`、`b.hs` 等）
  - 添加条件码别名转换（hs→cs, lo→cc）
  - 规范化立即数显示（统一为十六进制）
  - 反汇编匹配率：48.4% → 94.2%

- **类型解析对比**：
  - 过滤前向声明类型
  - 过滤内部类型（lhash_st_*, stack_st_* 等）
  - 类型匹配率：88.4% → 93.7%

### v0.9.0 (2026-02)

- 初始版本发布
- 支持 ELF 文件解析、反汇编、控制流图生成
- 支持 DWARF 调试信息查询
- 支持 GUI/TUI 交互界面

## 贡献

欢迎提交 Issue 和 Pull Request！