# objc-symboltool

**Repository Path**: lisongrui/objc-symboltool

## Basic Information

- **Project Name**: objc-symboltool
- **Description**: 如果集成iOS SDK后 发现App/SDK表现异常/Crash 可以使用此工具检查App的Objective-C运行时符号冲突问题
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-22
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SymbolTool

iOS ipa 内 Objective-C **Class / Category 冲突**静态检测工具。

- 无第三方 Python 依赖（纯标准库）。
- 依赖 Apple / Xcode CLT 自带的 `otool`（macOS）。来源可信、无仓库内二进制。
- 覆盖主二进制 / `.framework` / `.dylib` / `.appex`。
- 遍历 Fat binary 所有 slice。
- 结构化 JSON 报告 + 严重级驱动的退出码，可直接接入 CI。

## 使用

### 安装

要求 **Python ≥ 3.10**，且 `otool` 可用（随 Xcode Command Line Tools 提供）。

```bash
pip install -e .
```

### 运行

```bash
symboltool path/to/App.ipa --output report.json
# 或：
python -m symboltool path/to/App.ipa --output report.json
```

### 选项

| 选项 | 说明 |
|---|---|
| `--output PATH` / `-o PATH` | 报告 JSON 输出路径（默认 `report.json`） |
| `--work-dir PATH` | 解压临时目录（默认系统临时目录，退出时清理） |
| `--keep-unpack` | 保留解压产物用于排查 |
| `--fail-on {error,warn,never}` | 退出码策略（默认 `error`） |
| `-v` / `--verbose` | 详细日志 |

### 退出码

| 值 | 含义 |
|---|---|
| 0 | 无问题，或严重级未触达 `--fail-on` |
| 1 | 触达 WARN 阈值 |
| 2 | 触达 ERROR 阈值 |
| >2 | 工具自身错误 |

## 目录结构

```text
SymbolTool/
├── pyproject.toml     # 包定义（setuptools）
├── README.md
├── symboltool/        # 工具源码
│   ├── cli.py         # 命令行入口
│   ├── ipa.py         # IPA 安全解压（Zip Slip 防护）
│   ├── discover.py    # Mach-O 发现（framework / dylib / appex）
│   ├── macho_tools.py # otool 封装 & Mach-O magic bytes 识别
│   ├── otool_parser.py# otool -oV 输出文本解析
│   ├── parser.py      # 解析编排层
│   ├── analyzer.py    # 冲突分析（4 条规则）
│   ├── report.py      # JSON / 控制台报告生成
│   └── models.py      # 数据模型（dataclass）
└── tests/             # 单元测试（pytest）
```

## 检测规则

| 规则 | 严重程度 | 触发条件 |
|---|---|---|
| `E-CLASS-DUP` | ERROR | 同名 Class 在 ≥2 个二进制里定义，且方法集合不同 |
| `W-CLASS-DUP-SAME` | WARN | 同名 Class 在 ≥2 个二进制里定义，方法集合相同（同 SDK 被重复打包） |
| `E-CATEGORY-DUP` | ERROR | 同一 (Class, selector, kind) 被 ≥2 个 category 定义（跨 binary 或同 binary 内多 category） |
| `W-CATEGORY-OVERRIDE-CLASS` | WARN | Category 方法覆盖了不同二进制里宿主类的原生方法 |