From 646fb7d56db4b1826cb0fcdac821939d92bb4080 Mon Sep 17 00:00:00 2001 From: tianfenghan Date: Thu, 19 Mar 2026 15:42:42 +0800 Subject: [PATCH] =?UTF-8?q?docs(compiler):=20=E6=B7=BB=E5=8A=A0=20AOT=20?= =?UTF-8?q?=E7=BC=96=E8=AF=91=E5=99=A8=E5=91=BD=E4=BB=A4=E8=A1=8C=E5=B7=A5?= =?UTF-8?q?=E5=85=B7=E4=BD=BF=E7=94=A8=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增完整的命令行选项详解文档 - 包含优化级别、编译模式、输出文件名等所有参数说明 - 提供典型使用场景和性能优化技巧 - 添加故障排除和最佳实践章节 - 包含编译过程详解和高级主题说明 --- docs/COMPILER_CLI.md | 657 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 657 insertions(+) create mode 100644 docs/COMPILER_CLI.md diff --git a/docs/COMPILER_CLI.md b/docs/COMPILER_CLI.md new file mode 100644 index 00000000..de71c9b6 --- /dev/null +++ b/docs/COMPILER_CLI.md @@ -0,0 +1,657 @@ +# AOT 编译器命令行工具使用指南 + +## 📋 概述 + +PHP AOT 编译器是一个强大的命令行工具，可以将 PHP 源代码编译为原生可执行文件或 PHP 扩展。它支持多种编译选项、优化级别和构建模式。 + +--- + +## 🚀 快速开始 + +### 基本用法 + +```bash +# 编译单个 PHP 文件 +./bin/compiler.php examples/hello.php + +# 编译目录 +./bin/compiler.php examples/myapp/ + +# 带优化编译 +./bin/compiler.php examples/bench.php -O2 + +# 生成扩展 +./bin/compiler.php my_extension/ -m ext -o myext +``` + +--- + +## 📖 命令格式 + +``` +./bin/compiler.php [options] +``` + +### 参数说明 + +| 参数 | 说明 | 必需 | +|------|------|------| +| `` | 要编译的 PHP 文件或目录 | ✅ 是 | + +--- + +## ⚙️ 命令行选项详解 + +### 1. `-O ` - 优化级别 + +**别名**: `--optimize` +**默认值**: `0` +**取值范围**: `0-3` + +控制 GCC 编译器的优化级别，影响生成代码的性能和大小。 + +| 级别 | 说明 | 适用场景 | +|------|------|----------| +| `-O0` | 无优化，调试模式 | 开发调试 | +| `-O1` | 基础优化 | 一般用途 | +| `-O2` | 标准优化（推荐） | 生产环境 | +| `-O3` | 激进优化 | 性能关键应用 | + +**示例**: +```bash +# 无优化编译 +./bin/compiler.php app.php -O0 + +# 标准优化 +./bin/compiler.php app.php -O2 + +# 最大优化 +./bin/compiler.php app.php -O3 +``` + +--- + +### 2. `-m ` / `--mode ` - 编译模式 + +**默认值**: `bin` +**可选值**: `bin`, `ext` + +指定编译输出类型：可执行文件或 PHP 扩展。 + +#### 🔹 bin 模式（二进制） + +生成独立的可执行文件，无需 PHP 环境即可运行。 + +**特点**: +- ✅ 需要 `main()` 函数作为入口 +- ✅ 包含完整的运行时环境 +- ✅ 可直接在命令行执行 +- ❌ 不能作为 PHP 扩展加载 + +**示例**: +```bash +./bin/compiler.php myapp/ -m bin -o myapp +./myapp # 直接运行 +``` + +#### 🔸 ext 模式（扩展） + +生成 PHP 扩展（.so/.dll），需要在 PHP 环境中运行。 + +**特点**: +- ✅ 不需要 `main()` 函数 +- ✅ 可以作为模块加载到 PHP +- ✅ 支持与现有 PHP 代码集成 +- ❌ 需要 PHP 环境 + +**示例**: +```bash +./bin/compiler.php myext/ -m ext -o myext +# 在 php.ini 中添加 +extension=myext +``` + +--- + +### 3. `-o ` / `--output ` - 输出文件名 + +**别名**: `--output` +**默认值**: 输入文件的基本名 + +指定生成的可执行文件或扩展的名称。 + +**命名规则**: +- ✅ 只能包含字母、数字和下划线 +- ❌ 不能包含连字符（`-`）或星号（`*`） +- ❌ 不能是 C++ 保留关键字 +- ❌ 不能与现有目录同名 + +**示例**: +```bash +# 自定义输出名称 +./bin/compiler.php app.php -o my_application + +# 带连字符的名称会自动转换 +./bin/compiler.php my-app.php -o my_app # ✅ 正确 +./bin/compiler.php my-app.php -o my-app # ❌ 错误，会转换为 my_app +``` + +--- + +### 4. `-j ` / `--job ` - 并行编译任务数 + +**默认值**: `4` + +控制编译过程中并行处理的任务数量，影响编译速度。 + +**建议配置**: +- **单核 CPU**: `-j 1` +- **双核 CPU**: `-j 2` +- **四核 CPU**: `-j 4` (默认) +- **八核及以上**: `-j 8` 或更高 + +**示例**: +```bash +# 单线程编译（适合调试） +./bin/compiler.php large_project/ -j 1 + +# 多线程编译（适合生产） +./bin/compiler.php large_project/ -j 8 +``` + +--- + +### 5. `-v` / `--verbose` - 详细输出 + +**别名**: `--verbose` +**类型**: 开关（无参数） + +启用详细输出模式，显示编译过程的详细信息。 + +**输出内容**: +- ✅ 每个文件的处理状态 +- ✅ 跳过不支持语法的通知 +- ✅ 编译进度信息 +- ✅ 生成的中间文件路径 + +**示例**: +```bash +./bin/compiler.php app.php -v + +# 输出示例： +# prepare: /path/to/app.php +# generate stub file: /path/to/app.php +# convert: /path/to/app.php +# format: /path/to/build/app.cpp +# Starting parallel compilation with 4 jobs for 5 files +# Successfully compiled 5 files +``` + +--- + +### 6. `-f` / `--force` - 强制编译 + +**别名**: `--force` +**类型**: 开关 + +即使缓存存在也强制重新编译。 + +**使用场景**: +- 修改了底层 C++ 代码 +- 怀疑缓存有问题 +- 需要完全重新编译 + +**示例**: +```bash +# 强制重新编译 +./bin/compiler.php app.php -f + +# 结合优化使用 +./bin/compiler.php app.php -O2 -f +``` + +--- + +### 7. `-p` / `--profile` - 性能分析 + +**别名**: `--profile` +**类型**: 开关 + +启用性能分析功能，生成可用于性能分析的可执行文件。 + +**输出内容**: +- ✅ 函数执行时间统计 +- ✅ 内存使用情况 +- ✅ 调用次数统计 + +**示例**: +```bash +# 编译带性能分析的版本 +./bin/compiler.php benchmark.php -p -O2 + +# 运行后会生成性能报告 +./benchmark +cat benchmark.prof +``` + +--- + +### 8. `--no-literal-strings` - 禁用字符串优化 + +**类型**: 开关 + +禁用字面量字符串优化，所有字符串将在运行时动态创建。 + +**默认行为**: +- ✅ 字符串常量会被提取到全局数组 +- ✅ 减少重复字符串的内存占用 +- ✅ 提高字符串比较性能 + +**禁用后的影响**: +- ❌ 增加内存使用 +- ❌ 降低字符串操作性能 +- ✅ 可能减少编译时间 + +**示例**: +```bash +# 禁用字符串优化 +./bin/compiler.php app.php --no-literal-strings +``` + +--- + +### 9. `--debug-line` - 启用调试行 + +**默认值**: `0` + +在生成的 C++ 代码中包含源文件行号信息，用于调试。 + +**示例**: +```bash +# 启用调试行信息 +./bin/compiler.php app.php --debug-line 1 +``` + +--- + +### 10. `--debug-info` - 启用调试信息 + +**类型**: 开关 + +启用详细的调试信息输出。 + +**示例**: +```bash +# 启用调试信息 +./bin/compiler.php app.php --debug-info +``` + +--- + +### 11. `-h` / `--help` - 显示帮助 + +**类型**: 开关 + +显示帮助信息和所有可用选项。 + +**示例**: +```bash +./bin/compiler.php -h +``` + +**输出**: +``` +PHP AOT Compiler v1.0.0 + +USAGE: + ./bin/compiler.php [options] + +ARGUMENTS: + Input PHP file/directory to compile + +OPTIONS: + -O Optimization level (0-3, default: 0) + -p, --profile Enable performance profiling + -o, --output Output binary name (default: input basename) + -v, --verbose Verbose output + -h, --help Show this help message + -f, --force Force compile even if cache exists + -m, --mode Compilation mode, -m bin(binary) or -m ext(extension), default: bin + -j, --job Number of parallel compilation jobs (default: 4) + --no-literal-strings Disable literal strings optimization + +EXAMPLES: + ./bin/compiler.php examples/hello.php + ./bin/compiler.php examples/bench.php -O2 + ./bin/compiler.php examples/bench.php -O2 + ./bin/compiler.php examples/extension -O2 -o myapp -m ext + ./bin/compiler.php examples/app.php -O3 -o myapp -v +``` + +--- + +## 🎯 典型使用场景 + +### 场景一：开发环境调试 + +```bash +# 无优化，启用详细输出，单线程 +./bin/compiler.php src/app.php -O0 -v -j 1 +``` + +### 场景二：生产环境部署 + +```bash +# 标准优化，多线程编译 +./bin/compiler.php src/app.php -O2 -j 8 +``` + +### 场景三：性能关键应用 + +```bash +# 最大优化，启用性能分析 +./bin/compiler.php benchmark.php -O3 -p +``` + +### 场景四：构建 PHP 扩展 + +```bash +# 生成扩展模块 +./bin/compiler.php extension_src/ -m ext -o myext -O2 +``` + +### 场景五：大型项目 + +```bash +# 使用配置文件，多目录编译 +./bin/compiler.php project.yml -O2 -j 16 -v +``` + +--- + +## 📁 支持的输入类型 + +### 1. 单个 PHP 文件 + +```bash +./bin/compiler.php hello.php +``` + +### 2. 目录 + +```bash +./bin/compiler.php src/ +``` + +编译器会自动扫描目录下所有的 `.php` 文件。 + +### 3. YAML 配置文件 + +```bash +./bin/compiler.php project.yml +``` + +**project.yml 示例**: +```yaml +name: myapp +type: bin +sources: + - src/*.php + - lib/**/*.php + - main.php +``` + +--- + +## 🔧 编译过程详解 + +### 阶段一：预处理 (Prepare) + +``` +prepare: /path/to/file.php +``` + +- ✅ 解析 PHP 文件 +- ✅ 检查语法错误 +- ✅ 检测不支持的语法 +- ✅ 生成抽象语法树 (AST) + +### 阶段二：生成存根文件 (Generate Stub) + +``` +generate stub file: /path/to/file.php +``` + +- ✅ 生成 `.stub.php` 文件 +- ✅ 提取函数声明 +- ✅ 生成参数信息头文件 + +### 阶段三：转换为 C++ (Convert) + +``` +convert: /path/to/file.php +``` + +- ✅ 将 PHP AST 转换为 C++ 代码 +- ✅ 生成对应的 `.cpp` 文件 +- ✅ 处理类型映射 + +### 阶段四：格式化 (Format) + +``` +format: /path/to/build/file.cpp +cd /path && clang-format -i /path/to/build/file.cpp +``` + +- ✅ 使用 clang-format 格式化 C++ 代码 +- ✅ 确保代码风格一致 + +### 阶段五：并行编译 (Parallel Compilation) + +``` +Starting parallel compilation with 4 jobs for 5 files +Successfully compiled 5 files +``` + +- ✅ 使用多个进程并行编译 C++ 文件 +- ✅ 生成目标文件 (.o) + +### 阶段六：链接 (Link) + +``` +g++ ... -o app ... +``` + +- ✅ 链接所有目标文件 +- ✅ 链接 PHPX 库和 PHP 库 +- ✅ 生成最终可执行文件 + +--- + +## ⚡ 性能优化技巧 + +### 1. 选择合适的优化级别 + +```bash +# 开发阶段：快速编译 +-O0 + +# 测试阶段：平衡编译时间和性能 +-O1 + +# 生产阶段：最大化性能 +-O2 或 -O3 +``` + +### 2. 调整并行任务数 + +根据 CPU 核心数调整： +```bash +# 查看 CPU 核心数 +nproc + +# 设置为 CPU 核心数的 1.5 倍 +-j $(($(nproc) * 3 / 2)) +``` + +### 3. 使用缓存 + +编译器会自动缓存已编译的文件，下次编译时会跳过未更改的文件。 + +```bash +# 第一次编译（慢） +./bin/compiler.php app.php + +# 第二次编译（快，使用缓存） +./bin/compiler.php app.php + +# 强制重新编译 +./bin/compiler.php app.php -f +``` + +--- + +## 🐛 故障排除 + +### 问题一：编译失败 "No valid source file found" + +**原因**: 没有找到有效的 PHP 文件 + +**解决方法**: +```bash +# 检查文件路径是否正确 +ls -la your_file.php + +# 使用绝对路径 +./bin/compiler.php /absolute/path/to/file.php +``` + +### 问题二：类名冲突 + +**原因**: 输出名称与现有类名冲突 + +**解决方法**: +```bash +# 使用不同的输出名称 +./bin/compiler.php app.php -o myapp_binary +``` + +### 问题三：内存不足 + +**原因**: 并行任务数过多导致内存耗尽 + +**解决方法**: +```bash +# 减少并行任务数 +./bin/compiler.php large_project.php -j 2 +``` + +### 问题四：不支持的语法 + +**原因**: 使用了 AOT 编译器不支持的 PHP 语法 + +**输出示例**: +``` +unsupported syntax: Dynamic property creation is not supported +skip: /path/to/file.php +``` + +**解决方法**: +1. 查看 [UNSUPPORTED_SYNTAX.md](docs/UNSUPPORTED_SYNTAX.md) +2. 修改代码使用支持的语法 +3. 或将代码封装到函数中 + +--- + +## 📊 编译选项组合示例 + +### 示例组合 + +```bash +# 快速开发构建 +./bin/compiler.php app.php -O0 -j 1 + +# 标准生产构建 +./bin/compiler.php app.php -O2 -j 8 -v + +# 高性能构建 +./bin/compiler.php app.php -O3 -j 16 -p + +# 调试构建 +./bin/compiler.php app.php -O0 -v --debug-info + +# 扩展构建 +./bin/compiler.php ext/ -m ext -o myext -O2 -v +``` + +--- + +## 📝 最佳实践 + +### 1. 开发环境 + +```bash +# 使用脚本自动化 +#!/bin/bash +./bin/compiler.php src/app.php -O0 -v -j 1 +``` + +### 2. CI/CD 流水线 + +```bash +# 持续集成 +./bin/compiler.php tests/ -O2 -j $(nproc) -v +``` + +### 3. 生产部署 + +```bash +# 生产环境 +./bin/compiler.php release/app.php \ + -O2 \ + -j $(nproc) \ + -o app \ + -v \ + --force +``` + +### 4. 性能测试 + +```bash +# 基准测试 +./bin/compiler.php benchmark.php -O3 -p -o benchmark_optimized +``` + +--- + +## 🎓 高级主题 + +### 1. 自定义编译流程 + +可以通过修改 `src/config/compiler_options.php` 添加自定义选项。 + +### 2. 扩展编译器 + +实现自定义的 Preprocessor 或 Translator 来扩展编译器功能。 + +### 3. 性能调优 + +分析编译过程中的瓶颈： +```bash +time ./bin/compiler.php large_project.php -v +``` + +--- + +## 📚 相关资源 + +- **快速入门**: [QUICKSTART.md](QUICKSTART.md) +- **编译模式**: [COMPILATION_MODES.md](COMPILATION_MODES.md) +- **原生类型**: [NATIVE_TYPES.md](NATIVE_TYPES.md) +- **混合编程**: [MIXED_CPP_PHP.md](MIXED_CPP_PHP.md) +- **语法限制**: [UNSUPPORTED_SYNTAX.md](UNSUPPORTED_SYNTAX.md) + +--- + +**最后更新**: 2024 年 3 月 19 日 +**适用版本**: PHP AOT Compiler v1.0.0