compiler/docs/COMPILER_CLI.md

TypePHP 编译器命令行

本文档与 src/Translator.php::showUsage() 保持同步。使用：

bin/compiler.php <file|dir|project.yml> [options] [-- program-args...]

常用示例

# 编译单文件
bin/compiler.php app.php

# 优化并运行，`--` 后参数传给生成的程序
bin/compiler.php app.php -O2 -r -- --flag value

# 编译项目配置
bin/compiler.php project.yml -O2 -j 8

# 生成 PHP 扩展
bin/compiler.php extension/ -m ext -o my_extension

# 只生成 C++，不编译和链接
bin/compiler.php app.php --dry --build-dir /tmp/typephp-build

构建选项

选项	说明
-O <0-3>	优化级别，默认 0。
-d, --debug	调试构建；关闭优化、增加调试符号和 TypePHP 源码跟踪。
-o, --output <file>	输出文件名。
-m, `--mode <bin	lib
-r, --run	构建成功后运行。
-j, --job <num>	并行编译任务数，默认 4。
-f, --force	忽略 phpx misc 对象缓存，强制重新编译。
--build-dir <dir>	生成的 C++ 和中间产物目录。
--dry	只生成 C++，跳过编译与链接。
--format	对生成代码运行 clang-format。
--no-progress	不显示进度条，逐文件输出进度。
--no-color	禁用彩色输出。

-v / --version 只显示版本，不是 verbose 选项。

目标和工具链

选项	说明
`--php-version <8.2	8.3
--cxx-std <ver>	C++ 标准，例如 c++17、c++20。
--march <arch>	目标指令集，例如 native、x86-64-v3。
--target-platform <triple>	交叉编译目标 triple。
--lto	启用 Link Time Optimization。
--sanitize <type>	启用 sanitizer，例如 address、undefined。
--no-console	Windows GUI 模式隐藏控制台窗口。
--profile	Linux 上启用 gperftools profiler，并强制重编译相关对象。

--php-version 控制解析器接受的源码语法，也用于 project.yml 中依据 PHP_VERSION / PHP_VERSION_ID 选择源文件。它不负责选择链接的 PHP 安装目录。

C++ 编译和链接参数

这些参数均可重复：

-I /opt/library/include
-D FEATURE_ENABLED=1
-L /opt/library/lib
-l curl

对应长选项：

• --include-path
• --define
• --link-path
• --link-lib

项目配置优先级

传入 project.yml 时，命令行参数优先于 YAML 中的同名配置。项目文件格式参见用户文档及代码中的项目配置解析器。

查看权威帮助

命令行实现可能继续演进，发布版本的实际参数以以下命令为准：

bin/compiler.php --help

兼容性边界参见 INCOMPATIBLE_PHP_FEATURES.md，构建模式参见 COMPILATION_MODES.md。