CLI

qtphp 是包提供的可执行文件，装完在 vendor/bin/qtphp。

用法:
  qtphp doctor            检查工具链
  qtphp new <name>        创建新项目
  qtphp build <path>      编译项目
  qtphp run <path> [app参数…]  运行项目，其后的参数原样透传给应用
  qtphp package <path>    打包项目
  qtphp test              运行测试
  qtphp lint              校验桥接契约

qtphp doctor

检查工具链，逐项打印实际路径：

=== TypePHP\Qt 工具链检查 ===

[OK] PHP 8.5.11
[OK] tpc: D:\git\php\tpc_v0.9.4_windows_x64\tpc.exe
[OK] PHP 运行时库: D:\git\php\tpc_v0.9.4_windows_x64
[OK] Qt: D:/tools/Qt/6.9.3/msvc2022_64
[OK] MSVC: ...\vcvars64.bat
[OK] PHPUnit: ...\vendor/bin/phpunit

[OK] 核心工具链就绪！

检查项按平台分派：

Linux 上额外检查 12 项构建/打包前置，缺哪个就打出可直接粘贴的命令：

[WARN] 缺少构建前置：bison re2c patchelf
       可运行：apt install -y bison re2c patchelf

只 WARN，不影响退出码 —— doctor 的 rc 只由 error 级项决定。

退出码：0 全部就绪，1 有 error 级问题。

qtphp new <name>

创建新项目。生成的文件：

<name>/
├── src/main.php            # 入口骨架（可编译可运行）
├── project.yml             # Windows 编译入口
├── project.macos.yml       # macOS 入口
├── project.linux.yml       # Linux 入口
├── Info.macos.plist        # 打包 .app 用
├── build.bat / run.bat / package.bat   # Windows 便捷脚本
├── assets/                 # 运行时资源
└── README.md

生成的骨架开箱即可编译运行 —— 你只需要替换界面和数据层。

<name> 必须是合法标识符（字母开头，只含字母数字下划线）。

qtphp build <path>

编译。入口 yml 按平台挑：

Windows 上编译成功后自动部署运行时 DLL 到 build/：

[OK] 已部署 11 个运行时文件到 build/

产物：build/<name>.exe（Windows）或 build/<name>（macOS/Linux）。

nano

qtphp build <path> --nano 走 nano 模式：php-nano 与 PHPX 的源码直接编进产物， 完全不链接任何 PHP 运行时。

qtphp build examples/hello --nano

Apple Silicon macOS 上用 examples/hello 实测（两种模式的产物都是 -O2，入口 yml 固化 optimize: 2； nano 数字为清 build/cache 后的干净首建口径）：

nano 产物的 otool -L 只有 Qt 三件套 + Foundation/AppKit/WebKit + brew libiconv

• libc++/libSystem —— 没有 libphp、没有 phpx。行为不变：--selftest（25 例）、 --difftest（20 例）全过，--shot 出图与 embed 基线逐字节相同；macOS 打包后 dist/Hello.app 为 64.1 MiB（embed 版 83.6 MiB）。

需要知道的：

• 不用额外的 yml。同一份入口 yml 直接可用：nano 下 tpc 会忽略 php-builder: 段 （nano 不链运行时，没有东西要现编）；C++ 标准也没问题 —— 入口 yml 固化了 cxx-std: c++17（nano 拒绝 c++20），qtphp build --nano 另外还会在命令行兜底覆盖成 c++17。
• build/ 目录两种模式共用：来回切换会重编受影响的编译单元并重链，不是 no-op。
• Windows 上 nano 会跳过运行时 DLL 部署 —— 产物不导入任何 php*.dll， 真出现了 tpc 自己的依赖审计会直接把构建判失败。
• nano 装的是 PHP 运行时的子集：nano 不支持的函数在编译期就被 tpc 拒绝，而不是留到运行时炸。
• 只有 Apple Silicon macOS 上过真机验证。 Windows/Linux 只是把选项原样透传给 tpc，未实测。

qtphp run <path> [应用参数…]

运行产物。第三个参数起原样透传：

qtphp run . --selftest
qtphp run . --shot out.png
qtphp run . --difftest

启动前做依赖自检：

退出码逐位传递（应用返回 7，qtphp run 也返回 7）。 三个验收开关同样走退出码：全过 0，有 FAIL 或 --shot 出图失败 1 （见 无头验收 → 退出码）。

qtphp package <path>

打包自包含产物并自检：

自检失败会 rc=1 并说明原因，不会假装成功。详见打包。

qtphp test

跑 PHPUnit。不需要 Qt，也不需要编译器 —— 全部走纯 PHP 的 FakeBridge 替身。

OK (112 tests, 183 assertions)

qtphp lint

校验桥接契约（stub ⇄ C++ 符号一致）：

[OK] 契约一致！

不一致时列出具体符号。改桥接后必跑。

环境变量