AOT: Debug symbols and source map for compiled binaries (-y flag)

[PurHur]

Problem

bin/compile.php -y emits .bc / .s beside the binary for debugging, but multi-file phpc build --project and deployed CGI binaries still lack practical PHP source line → native PC mapping when scripts segfault or print wrong output (#764).

Operators debugging empty stdout or native crashes need gdb/lldb without manually correlating LLVM IR.

Goal

Improve debuggability for AOT web binaries:

1. Optional DWARF or line tables: PHP file:line → native address
2. Document debugging workflow for examples/003-MiniWebApp/.phpc/bin/app
3. Optional: per-module CFG dump in project build output dir

Implementation hints

Piece	Files	Notes
AOT emit	lib/AOT/Linker.php, LLVM IR builder	-g / DIBuilder line info from compile unit paths
CLI	bin/compile.php, lib/Cli/PhpcBuild.php	-y already dumps IR; extend --debug-symbols flag
Project build	lib/Cli/PhpcBuild.php --project	Emit build/debug/ with .s per unit when env set
Docs	docs/deploy-web-aot.md, #445	gdb ./app, bt, map to Router.php:line

Suggested workflow (acceptance demo)

phpc build --project examples/003-MiniWebApp -y
gdb -batch -ex run -ex bt --args env QUERY_STRING=route=home ./examples/003-MiniWebApp/.phpc/bin/app
# backtrace shows PHP file:line when DWARF present

Acceptance criteria

• At least one fixture binary built with debug symbols shows PHP filename in gdb backtrace
• README or deploy doc section links from DevEx: phpc build --project hints when linked binary prints 0 stdout bytes #792 post-build hints
• No requirement for GitHub Actions — verify in php-compiler:22.04-dev

Dependencies

• AOT: Project build mode (entry file + dependency graph) #59 ✅ project build mode
• AOT: Link multiple translation units into one binary #154 — multi-TU may need per-unit debug info merge
• AOT: MiniWebApp native binary CLI execute emits empty stdout (post-link) #764 — execute debugging motivation (orthogonal to fix)

Priority

Medium — production deploy + #764 triage.

Related

• DevEx: phpc build --project --list-units for AOT debug (#764) #847 --list-units (compile graph, not DWARF)
• DevEx: phpc build --project hints when linked binary prints 0 stdout bytes #792 — post-build execute probe messaging

Verification

make docker-build-22
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev \
  ./phpc build -y -o /tmp/dbg examples/000-HelloWorld/example.php

Links

• ROADMAP 🗺️ ROADMAP: Compile a small PHP web application (living document) #78 Phase 3 Web AOT