<blog>

# 增量编译缓存

TypePHP 的二次编译速度，很大程度上取决于**对象文件缓存是否命中**。编译器对两类源文件做内容指纹缓存：phpx 的 `misc` 源，以及编译器自己生成的 `.cc` 单元。

Sources: [src/Translator.php](src/Translator.php#L1116-L1292)

## 两类缓存

| 方法 | 适用对象 | 缓存键组成 |
|---|---|---|
| `hasMiscObjectFileCache()` | `phpx/src/misc/*.cc` | 编译命令 + PHP ABI（`PHP_VERSION_ID` / `ZEND_MODULE_API_NO` / `PHP_ZTS` / `PHP_INT_SIZE` 等）+ phpx 头文件 mtime |
| `hasGeneratedObjectFileCache()` | 构建目录下的生成 `.cc` | 编译命令 + PHP ABI + **所有生成头文件内容指纹**（`func_decl.h` / `data_decl.h` / 各 `_arginfo.h`） |

Sources: [src/Translator.php](src/Translator.php#L1116-L1160) · [src/Translator.php](src/Translator.php#L1207-L1240)

## 缓存键构造

```php
hash('sha256',
    buildCompileFileCommand(source, object)   // 可复现的编译命令行
    . "\0" . serialize($abi)                    // PHP ABI 快照
    [. "\0" . header . "\0" . hash_file(header)] // 仅生成单元：逐头文件内容
)
```

键写入 `<object>.typephp-cache` 元数据文件（`getMiscObjectCacheMetadataFile()`）。每次 `compileFile()` 先比较元数据文件中的键，再比较 `.o` 与源/头的 mtime——**任一不满足即失效并重编译**。

Sources: [src/Translator.php](src/Translator.php#L1162-L1187) · [src/Translator.php](src/Translator.php#L1272-L1292)

## 设计要点

- **`extension-<target>.cc` 故意不进共享头依赖**：它的内容随任意类变化而改变，若纳入指纹会让每个 `.cc` 都失效，破坏增量构建。它自身作为生成单元拥有独立缓存项。
- **`--force` / `--profile` 强制失效**：这两类参数会跳过全部缓存，确保 misc 文件也被重编（profiler 需 `PPROF_ON` 宏生效）。
- **头文件依赖集排序后参与哈希**，避免路径顺序差异导致误失效。

Sources: [src/Translator.php](src/Translator.php#L1242-L1271) · [src/Translator.php](src/Translator.php#L1218-L1226)

## 相关阅读

- 缓存何时被查询 → [构建流水线](build-pipeline)
- 编译命令从何而来 → [编译器后端](backend)
- 整体性能分析 → [构建速度与性能](build-speed)

</blog>