4.0 KiB
TypePHP 编译器命令行
Bash 自动补全
TypePHP 提供与当前编译器参数同步的 Bash completion。当前终端临时启用：
source <(./tpc --generate-completion=bash)
从源码仓库开发时也可以直接执行 source completions/tpc.bash。
安装到当前用户并在后续 Bash 会话自动加载：
mkdir -p "$HOME/.local/share/bash-completion/completions"
./tpc --generate-completion=bash \
> "$HOME/.local/share/bash-completion/completions/tpc"
如果系统没有自动扫描用户 completion 目录，可在 ~/.bashrc 中加载：
source "$HOME/.local/share/bash-completion/completions/tpc"
系统级安装可将生成结果写入 /usr/share/bash-completion/completions/tpc。该操作通常
需要 root 权限。
补全支持编译选项、WASM profile、构建模式、PHP/C++ 版本、sanitizer、输入源码、
项目 YAML、Python 源文件以及目录参数。-- 之后是被编译程序自身的参数，补全器
不会再把它们解释为 tpc 参数。
发布包携带预生成的 completions/tpc.bash。此文件由同一个生成器产生，并有单元
测试保证它与 ./tpc --generate-completion=bash 的输出一致。
本文档与 src/Translator.php::showUsage() 保持同步。使用：
bin/tpc.php <file|dir|project.yml> [options] [-- program-args...]
常用示例
# 编译单文件
bin/tpc.php app.php
# 优化并运行，`--` 后参数传给生成的程序
bin/tpc.php app.php -O2 -r -- --flag value
# 编译项目配置
bin/tpc.php project.yml -O2 -j 8
# 生成 PHP 扩展
bin/tpc.php extension/ -m ext -o my_extension
# 只生成 C++，不编译和链接
bin/tpc.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/tpc.php --help
兼容性边界参见 INCOMPATIBLE_PHP_FEATURES.md，构建模式参见 COMPILATION_MODES.md。