<blog>

# 编译模式

TypePHP 通过 `-m / --mode` 支持三种产物形态，由 `Translator::setBuildMode()` 归一化。三种模式共享同一套 PHP→C++ 翻译，区别只在于**入口约定与链接目标**。

Sources: [src/Translator.php](src/Translator.php#L574-L589) · [docs/COMPILATION_MODES.md](docs/COMPILATION_MODES.md)

## 三种模式对比

| 模式 | 参数 | 产物 | 入口要求 | 典型用途 |
|---|---|---|---|---|
| 二进制 | `bin`（默认） | 独立可执行文件 | 必须定义 `main()` | CLI 工具、独立服务 |
| 共享库 | `lib` | `.so` / `.dll` / `.dylib` | 不需要 `main()` | 供其它程序调用的逻辑库 |
| 扩展 | `ext` | PHP 扩展 `.so` | 不需要 `main()` | 嵌入现有 PHP 应用（php-fpm 等） |

`bin` 是 `binary/cli` 的别名；`lib` 涵盖 `library/shared/dll/dylib/so`；`ext` 等价于 `extension`。未知值会报错退出。

Sources: [src/Translator.php](src/Translator.php#L574-L589)

## 二进制模式（embed）

`bin` 模式在 `genExtension()` 中嵌入 `cli_set_process_title` / `cli_get_process_title` 内置函数，并在 `RINIT` 阶段用 `php::eval` 直接执行 `main()`（带 `$argc/$argv` 或空参数两种签名）。

```mermaid
flowchart LR
    A["main()"] --> B["RINIT: php_app_init()"]
    B --> C["php::eval('main($argc,$argv)')"]
    C --> D["RSHUTDOWN: php_app_clean()"]
```

Sources: [src/Translator.php](src/Translator.php#L1043-L1066) · [src/Translator.php](src/Translator.php#L1055-L1059)

## 共享库模式

库模式下，编译器会：
- 对 `exported` 函数加上 `TYPEPHP_<NAME>_API` 导出宏；
- 生成 `<target>.stub.php` 导入桩，供其它 TypePHP 工程按库调用；
- 在 Linux 上自动给目标名加 `lib` 前缀。

Sources: [src/Translator.php](src/Translator.php#L652-L666) · [src/Translator.php#L1736-L1738) · [src/Translator.php](src/Translator.php#L633-L650)

## 扩展模式

`ext` 模式会跳过 `main()`，使用 `ZEND_GET_MODULE()` 注册 Zend 模块，并在 `RSHUTDOWN` 清空函数/类/属性表以支持重复加载。

Sources: [src/Translator.php](src/Translator.php#L1033-L1037) · [src/Translator.php](src/Translator.php#L1090-L1091)

## 相关阅读

- 命令行全量参数见 [编译期属性](compile-time-attributes) 与 `docs/COMPILER_CLI.md`。
- 产物如何被链接 → [构建流水线](build-pipeline)。

</blog>