AOT: Link multiple translation units into one binary

[PurHur]

Category

bootstrap | language (AOT link)

Problem

bin/compile.php / phpc build originally emitted one .o per entry file. Multi-file apps need:

public/index.php  → require bootstrap.php → src/Router.php

Status (May 2026)

Phase 1 shipped on master:

Capability	Issue	Status
Manifest includes[]	#452	✅
ProjectGraph BFS	#504	✅
Multi-.o link	#752	✅
003-MiniWebApp AOT link + execute	#764	✅
Deploy bundle	#609	✅

Phase 2 open — dynamic discovery: #1762 (PSR-4 autoload, non-literal requires). Parent umbrella #59 should narrow to phase-2 or close when static path is documented.

php-src reference

• N/A (AOT linker) — analogous to linking multiple .o from php-src build + php CLI embedding multiple compilation units
• Include graph: compare Zend OPcache preload / zend_compile_file per path

Repro — phase 1 (passes today)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
  php bin/compile.php --project examples/003-MiniWebApp -o /tmp/miniwebapp
  /tmp/miniwebapp 2>&1 | head -5
'

003-MiniWebApp with explicit includes[] in phpc.json links and executes (#764 ✅).

Repro — phase 2 gap (#1762)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
  php bin/compile.php --project test/fixtures/aot/projects/psr4_mini -o /tmp/psr4_mini
'

Expected: green link when autoload discovers src/*.php.
Actual: fixture missing / requires hand includes[].

Goal (phase 2)

phpc build --project discovers PHP files reachable from entry without hand-maintaining every path in phpc.json when uses PSR-4 or static string requires.

Scope (this repo)

Module	Path
Linker	lib/AOT/Linker.php — multi-.o symbol merge ✅
Graph	lib/AOT/ProjectGraph.php — BFS literal includes ✅; extend #1762
Manifest	lib/Web/ProjectManifest.php, phpc.json schema #1803
Compiler metadata	lib/Compiler.php — record literal include targets
Tests	test/fixtures/aot/cases/multi_file_include.phpt, test/fixtures/aot/projects/psr4_mini/

Discovery graph (phase 2)

• Walk require/include with compile-time literal paths (Language: include/require in JIT and AOT (multi-file applications) #54 AOT)
• phpc.json "autoload": { "psr-4": ... } — compile referenced classes (DevEx: PSR-4 autoload paths in phpc.json project manifest #155, AOT: Dynamic require/include discovery for project build (phase 2 of #154) #1762)
• Fail lint for dynamic require $path

Symbol table

• Track function/class symbols per unit; mangle by file id until Language: PHP namespaces (namespace, use, qualified names) #84 namespaces mature
• Link order: runtime stubs → dependencies → entry main

Done when

Phase 1 (met):

• phpc build --project examples/003-MiniWebApp links + executes (AOT: MiniWebApp native binary CLI execute emits empty stdout (post-link) #764)
• ./script/ci-local.sh --filter AotTest includes multi-file link cases

Phase 2 (this issue stays open until #1762 closes):

• phpc build --project test/fixtures/aot/projects/psr4_mini green without hand includes[]
• phpc lint --project reports dynamic require $var with file:line
• Document static vs dynamic policy in docs/capabilities.md / project build docs

Verification (local / Docker only)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./script/ci-local.sh --filter AotTest'
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./script/ci-local.sh --filter ProjectGraph'

Do not use raw docker run -v "$(pwd):/compiler" on Runforge — use ./script/docker-exec.sh.

Dependencies

• AOT: Project build mode (entry file + dependency graph) #59 — umbrella (static path done)
• AOT: Dynamic require/include discovery for project build (phase 2 of #154) #1762 — phase 2 tracker (claim this for graph work)
• Language: include/require in JIT and AOT (multi-file applications) #54, Language: require_once and include_once deduplication #120, DevEx: PSR-4 autoload paths in phpc.json project manifest #155, DevEx: phpc.json autoload phase 2 — static class discovery for AOT project build #1803 — includes + autoload
• Language: Magic constants __DIR__, __FILE__, __LINE__ for multi-file apps #85 __DIR__ for relative requires
• Self-host: Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492

Related

• lib/AOT/Linker.php, lib/AOT/ProjectGraph.php, lib/Web/ProjectManifest.php
• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 Phase 3 Web AOT

[PurHur]

De-dupe (batch 44): Multi-file / project AOT linking is tracked under #59 (phpc build --project, ProjectGraph.php). This issue remains the linker / multi-.o implementation slice — close together with #59 when examples/003-MiniWebApp native link is green (#568).

Canonical verification: ./script/ci-local.sh --filter AotTest (Docker, not GHA).

[PurHur]

De-duplication (batch 45)

Multi-file / multi-TU native link is tracked canonically in #59 (phpc build --project).

#154 remains the implementation slice (linker passes, symbol export for user classes). Close or link PRs to #59; north-star execute blocker is #568 (user-class object model), not a separate link issue.

Verify: docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev ./phpc build --project examples/003-MiniWebApp (expect failure trailer #568 until fixed).