compiler/docs/COMPILER_CLI.md

AOT 编译器命令行工具使用指南

📋 概述

PHP AOT 编译器是一个强大的命令行工具，可以将 PHP 源代码编译为原生可执行文件或 PHP 扩展。它支持多种编译选项、优化级别和构建模式。

---

🚀 快速开始

基本用法

# 编译单个 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 <file/dir> [options]

参数说明

参数	说明	必需
<file>	要编译的 PHP 文件或目录	✅ 是

---

⚙️ 命令行选项详解

1. -O <level> - 优化级别

别名: --optimize
默认值: 0
取值范围: 0-3

控制 GCC 编译器的优化级别，影响生成代码的性能和大小。

级别	说明	适用场景
-O0	无优化，调试模式	开发调试
-O1	基础优化	一般用途
-O2	标准优化（推荐）	生产环境
-O3	激进优化	性能关键应用

示例:

# 无优化编译
./bin/compiler.php app.php -O0

# 标准优化
./bin/compiler.php app.php -O2

# 最大优化
./bin/compiler.php app.php -O3

---

2. -m <mode> / --mode <mode> - 编译模式

默认值: bin
可选值: bin, ext

指定编译输出类型：可执行文件或 PHP 扩展。

🔹 bin 模式（二进制）

生成独立的可执行文件，无需 PHP 环境即可运行。

特点:

• ✅ 需要 main() 函数作为入口
• ✅ 包含完整的运行时环境
• ✅ 可直接在命令行执行
• ❌ 不能作为 PHP 扩展加载

示例:

./bin/compiler.php myapp/ -m bin -o myapp
./myapp  # 直接运行

🔸 ext 模式（扩展）

生成 PHP 扩展（.so/.dll），需要在 PHP 环境中运行。

特点:

• ✅ 不需要 main() 函数
• ✅ 可以作为模块加载到 PHP
• ✅ 支持与现有 PHP 代码集成
• ❌ 需要 PHP 环境

示例:

./bin/compiler.php myext/ -m ext -o myext
# 在 php.ini 中添加
extension=myext

---

3. -o <file> / --output <file> - 输出文件名

别名: --output
默认值: 输入文件的基本名

指定生成的可执行文件或扩展的名称。

命名规则:

• ✅ 只能包含字母、数字和下划线
• ❌ 不能包含连字符（-）或星号（*）
• ❌ 不能是 C++ 保留关键字
• ❌ 不能与现有目录同名

示例:

# 自定义输出名称
./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 <num> / --job <num> - 并行编译任务数

默认值: 4

控制编译过程中并行处理的任务数量，影响编译速度。

建议配置:

• 单核 CPU: -j 1
• 双核 CPU: -j 2
• 四核 CPU: -j 4 (默认)
• 八核及以上: -j 8 或更高

示例:

# 单线程编译（适合调试）
./bin/compiler.php large_project/ -j 1

# 多线程编译（适合生产）
./bin/compiler.php large_project/ -j 8

---

5. -v / --verbose - 详细输出

别名: --verbose
类型: 开关（无参数）

启用详细输出模式，显示编译过程的详细信息。

输出内容:

• ✅ 每个文件的处理状态
• ✅ 跳过不支持语法的通知
• ✅ 编译进度信息
• ✅ 生成的中间文件路径

示例:

./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++ 代码
• 怀疑缓存有问题
• 需要完全重新编译

示例:

# 强制重新编译
./bin/compiler.php app.php -f

# 结合优化使用
./bin/compiler.php app.php -O2 -f

---

7. -p / --profile - 性能分析

别名: --profile
类型: 开关

启用性能分析功能，生成可用于性能分析的可执行文件。

输出内容:

• ✅ 函数执行时间统计
• ✅ 内存使用情况
• ✅ 调用次数统计

示例:

# 编译带性能分析的版本
./bin/compiler.php benchmark.php -p -O2

# 运行后会生成性能报告
./benchmark
cat benchmark.prof

---

8. --no-literal-strings - 禁用字符串优化

类型: 开关

禁用字面量字符串优化，所有字符串将在运行时动态创建。

默认行为:

• ✅ 字符串常量会被提取到全局数组
• ✅ 减少重复字符串的内存占用
• ✅ 提高字符串比较性能

禁用后的影响:

• ❌ 增加内存使用
• ❌ 降低字符串操作性能
• ✅ 可能减少编译时间

示例:

# 禁用字符串优化
./bin/compiler.php app.php --no-literal-strings

---

9. --debug-line - 启用调试行

默认值: 0

在生成的 C++ 代码中包含源文件行号信息，用于调试。

示例:

# 启用调试行信息
./bin/compiler.php app.php --debug-line 1

---

10. --debug-info - 启用调试信息

类型: 开关

启用详细的调试信息输出。

示例:

# 启用调试信息
./bin/compiler.php app.php --debug-info

---

11. -h / --help - 显示帮助

类型: 开关

显示帮助信息和所有可用选项。

示例:

./bin/compiler.php -h

输出:

PHP AOT Compiler v1.0.0

USAGE:
    ./bin/compiler.php <file/dir> [options]

ARGUMENTS:
    <file>    Input PHP file/directory to compile

OPTIONS:
    -O <level>           Optimization level (0-3, default: 0)
    -p, --profile        Enable performance profiling
    -o, --output <file>  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 <mode>    Compilation mode, -m bin(binary) or -m ext(extension), default: bin
    -j, --job <num>      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

---

🎯 典型使用场景

场景一：开发环境调试

# 无优化，启用详细输出，单线程
./bin/compiler.php src/app.php -O0 -v -j 1

场景二：生产环境部署

# 标准优化，多线程编译
./bin/compiler.php src/app.php -O2 -j 8

场景三：性能关键应用

# 最大优化，启用性能分析
./bin/compiler.php benchmark.php -O3 -p

场景四：构建 PHP 扩展

# 生成扩展模块
./bin/compiler.php extension_src/ -m ext -o myext -O2

场景五：大型项目

# 使用配置文件，多目录编译
./bin/compiler.php project.yml -O2 -j 16 -v

---

📁 支持的输入类型

1. 单个 PHP 文件

./bin/compiler.php hello.php

2. 目录

./bin/compiler.php src/

编译器会自动扫描目录下所有的 .php 文件。

3. YAML 配置文件

./bin/compiler.php project.yml

project.yml 示例:

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. 选择合适的优化级别

# 开发阶段：快速编译
-O0

# 测试阶段：平衡编译时间和性能
-O1

# 生产阶段：最大化性能
-O2 或 -O3

2. 调整并行任务数

根据 CPU 核心数调整：

# 查看 CPU 核心数
nproc

# 设置为 CPU 核心数的 1.5 倍
-j $(($(nproc) * 3 / 2))

3. 使用缓存

编译器会自动缓存已编译的文件，下次编译时会跳过未更改的文件。

# 第一次编译（慢）
./bin/compiler.php app.php

# 第二次编译（快，使用缓存）
./bin/compiler.php app.php

# 强制重新编译
./bin/compiler.php app.php -f

---

🐛 故障排除

问题一：编译失败 "No valid source file found"

原因: 没有找到有效的 PHP 文件

解决方法:

# 检查文件路径是否正确
ls -la your_file.php

# 使用绝对路径
./bin/compiler.php /absolute/path/to/file.php

问题二：类名冲突

原因: 输出名称与现有类名冲突

解决方法:

# 使用不同的输出名称
./bin/compiler.php app.php -o myapp_binary

问题三：内存不足

原因: 并行任务数过多导致内存耗尽

解决方法:

# 减少并行任务数
./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
2. 修改代码使用支持的语法
3. 或将代码封装到函数中

---

📊 编译选项组合示例

示例组合

# 快速开发构建
./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. 开发环境

# 使用脚本自动化
#!/bin/bash
./bin/compiler.php src/app.php -O0 -v -j 1

2. CI/CD 流水线

# 持续集成
./bin/compiler.php tests/ -O2 -j $(nproc) -v

3. 生产部署

# 生产环境
./bin/compiler.php release/app.php \
    -O2 \
    -j $(nproc) \
    -o app \
    -v \
    --force

4. 性能测试

# 基准测试
./bin/compiler.php benchmark.php -O3 -p -o benchmark_optimized

---

🎓 高级主题

1. 自定义编译流程

可以通过修改 src/config/compiler_options.php 添加自定义选项。

2. 扩展编译器

实现自定义的 Preprocessor 或 Translator 来扩展编译器功能。

3. 性能调优

分析编译过程中的瓶颈：

time ./bin/compiler.php large_project.php -v

---

📚 相关资源

• 快速入门: QUICKSTART.md
• 编译模式: COMPILATION_MODES.md
• 原生类型: NATIVE_TYPES.md
• 混合编程: MIXED_CPP_PHP.md
• 语法限制: UNSUPPORTED_SYNTAX.md

---

最后更新: 2024 年 3 月 19 日
适用版本: PHP AOT Compiler v1.0.0