Milestone: Self-host — compile php-compiler with php-compiler (bootstrap)

[PurHur]

Category

bootstrap

Problem

The compiler runs on Zend PHP today; compile times dominate JIT benchmarks. M5 self-host (#1492) requires a native binary from this repo's lib/ + ext/ that compiles PHP—including the next compiler revision—without Zend in the loop.

This milestone tracks phased bootstrap work; individual gaps are filed as implementation-ready language/stdlib/bootstrap issues.

php-src reference

N/A (product milestone). Behavior targets remain Zend/php-src for language + stdlib parity on the bootstrap subset.

Repro / gates (today)

composer install && ./script/apply-patches.sh
php script/bootstrap-inventory.php --check
./script/docker-exec.sh -- bash -lc 'make bootstrap-selfhost-helloworld'
./script/docker-exec.sh -- bash -lc 'make bootstrap-selfhost-link'
./script/bootstrap-loop-probe.sh --dry-run

Inventory SSOT: docs/bootstrap-inventory.md, docs/bootstrap-selfhost.md, docs/self-host-target.md.

Scope (phased)

Phase	Goal	Tracking
A — Inventory	Enumerate bin/vm.php path; CFG gap warnings	#765, #2254, script/bootstrap-inventory.php
B — Subset compile	compile.php -l on bootstrap file list	#1768, #2442
C — Native run	AOT binary runs hello + compiler slice	#2075, #2522

Non-goals (initial): full vendor/ self-host; LLVM pipeline self-hosted without plan.

Done when

• Phase A: bootstrap-inventory.php --check green; triage script ranks top CFG gaps (Tooling: bootstrap-inventory-triage.php — top CFG gaps across 611 files #2254)
• Phase B: bootstrap profile compiles inventory spine without Zend eval on hot path
• Phase C: make bootstrap-selfhost-helloworld + link probe green in Docker; documented gap list tied to open parity issues
• Progress linked from Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492 each parity filing run

Links

• Epic Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492 · ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 · M3 emit Self-host M3: compile-driver real lowering symbol batch tracker #1768 · M4 Self-host M4: Native gen-2 AOT emit without Zend fallback (post-#1498) #2075

[PurHur]

Phase A complete via merged PR #238.

• script/bootstrap-inventory.php scans the bin/vm.php path (lib/, ext/, src/, entry shims) and flags constructs that block bootstrap AOT compile.
• docs/bootstrap-inventory.md is generated and checked in CI (script/bootstrap-inventory.php --check).
• Summary: 188 PHP files, 10 source blockers (try/catch, yield, etc.), 501 warnings (mostly class-method counts).

Remaining for this milestone: Phase B (bootstrap profile + compile.php -l gate) and Phase C (native binary runs HelloWorld).

[PurHur]

Phase B complete via merged PR #384.

• script/bootstrap-profile.php → docs/bootstrap-profile.json (unsupported constructs, 2 excluded blocker files, 237 eligible vm.php-path files, AOT lint targets).
• script/bootstrap-aot-lint.php runs bin/compile.php -l on lint targets when LLVM 9 is present; wired into script/ci-local.sh.
• Initial lint targets: examples/000-HelloWorld/example.php, test/bootstrap-aot/echo_hello.php.

Remaining: Phase C — native bootstrap binary runs HelloWorld and expands the lint target list toward a lib/Compiler.php subset.

[PurHur]

Self-host gate verification (2026-05-23)

Verified on 0bf9a59c (merge PR #920 / #913 self-host link progress env) after the link/probe env alignment.

Docker (php-compiler:22.04-dev, bind-mount):

make bootstrap-selfhost-probe          → exit 0 (linked build/selfhost)
./script/bootstrap-selfhost-link.sh      → exit 0, stdout: compiler_minimal bundle OK

Host (PHP 8.x + repo .llvm/):

make bootstrap-selfhost-probe          → exit 0
./script/bootstrap-selfhost-link.sh      → exit 0, stdout: compiler_minimal bundle OK

Shared mechanism: both scripts export PHP_COMPILER_JIT_PROGRESS_FILE; lib/JIT::shouldUseSelfHostJitStubs() gates Web/Compiler hot-path stubs on that env var. Probe-only progress logging and link gate now use the same stub path (#913).

README Achieved (minimal subset) claim for ./script/bootstrap-selfhost-link.sh is accurate on this commit. Full lib/ native self-host remains open.