compiler/docs/en/AOT_BUILD_SPEED_RESEARCH.md

AOT Compilation Speed Optimization Research Notes

This document records the current assessment of Swoole-Compiler AOT compilation speed, bottleneck analysis, and future research directions. It is not yet tied to any specific PR.

Goal

Reduce the following two categories of time cost:

1. Cold-start full build: ./bin/tpc.php project.yml
2. Hot-start incremental build: recompiling after changing only a few PHP files

The focus is on large projects and compiler self-hosting scenarios.

Current Pipeline

The main flow is in src/Php/Translator.php:

1. prepare(): scan files, parse AST, collect symbols, sort dependencies
2. convert(): generate the corresponding .cc for each PHP file
3. genStubFile(): generate the arginfo / class register header file
4. genFunctionDeclarations() / genDataDeclarations(): generate the build-time internal declaration header
5. genExtension(): generate a single extension-<target>.cc
6. compile(): compile all .cc/.c/... into .o
7. build(): link into the final executable or extension

Main Bottleneck Assessment

1. Common Header Churn Causing Full Recompilation

Currently all translation units include:

• php_<target>_func_decl.h
• php_<target>_data_decl.h

As soon as any function declaration, default-argument helper, or global symbol declaration changes, a large number of .cc files get recompiled.

This is one of the key reasons for the poor incremental build performance of large projects.

2. The extension-<target>.cc Single File Is Too Large

The extension main file carries:

• class entry registration
• the function table
• literal strings
• module initialization
• static property initialization
• constant initialization

The larger the project, the larger this single TU becomes, making it easy to become a compilation tail bottleneck; even if other files can be compiled in parallel, they all stall on this one large file.

3. Missing a General Incremental Cache

Currently only phpx/src/misc has an object cache:

• hasMiscObjectFileCache()

The .cc, common headers, arginfo headers, and extension file generated for the user's own project are still essentially fully regenerated and fully recompiled.

4. clang-format Overhead Is Fixed and Serial

formatCppCode() runs once for each generated file:

clang-format -i <file>

This introduces:

• extra process startup overhead
• a large amount of disk I/O
• serial formatting waits

It is especially noticeable for large projects.

5. arginfo / stub Are Regenerated Every Time

generateStubFile() currently runs every time; even if the input PHP files have not changed, it regenerates the header files, further amplifying the header churn problem.

6. Only the Compilation Stage Is Parallel; the Front Stages Are Mostly Serial

Currently compileWithPcntl() only parallelizes .cc -> .o:

• prepare
• convert
• stub generation
• format

These stages are still mostly serial.

Highest-priority Optimization Directions

P0: Do Not Rewrite Files When Content Is Unchanged

This is the most worthwhile foundational change to prioritize.

Idea

For all generated files:

• .cc
• arginfo .h
• php_<target>_func_decl.h
• php_<target>_data_decl.h
• extension-<target>.cc

Compare the content before writing to disk:

• Same content: do not write the file
• Different content: write it

Value

Avoid triggering downstream full recompilation merely because of an mtime change.

---

P0: General object cache / incremental compilation

Extend the current caching approach that only targets phpx/src/misc to user-generated code.

Suggested Cache Conditions

For each target .o:

1. .o exists
2. .o is newer than its corresponding source file
3. .o is newer than the headers it depends on
4. The compile option signature has not changed (optimization level, debug, sanitize, cxxflags, PHP/ZTS, etc.)

When satisfied, skip compilation directly.

Supporting Requirements

A clear "build signature" mechanism is needed, for example:

• compiler backend
• cpp compiler path
• C++ standard
• optimize/debug/sanitize
• build mode
• PHP/ZTS information

---

P0: Disable clang-format by Default

It is recommended to make formatting an explicit capability rather than part of the default compilation path.

Recommendation

• Disable by default
• Add a --format or debug/dev mode to enable it
• Or format only changed files

Value

This is a low-risk optimization with immediate effect.

---

P1: Split the Common Declaration Header

Current Problem

Complex default-argument helpers also enter the common func_decl.h, widening the impact of header changes.

Optional Directions

1. Split declaration headers by source file
2. Move helpers from the common header to local headers / local .cc
3. Only truly cross-TU declarations go into the common header

Goal

Reduce "one change, full project recompilation".

---

P1: Split extension-<target>.cc

Splittable Modules

1. extension-main.cc
2. extension-class-register-*.cc
3. extension-function-table.cc
4. extension-const-init.cc
5. extension-static-init.cc

Value

• Reduce the size of a single TU
• Enhance parallel compilation benefits
• Reduce the tail wait for large projects

---

P1: arginfo / stub caching

Direction

Introduce input-content-based caching for generateStubFile():

• Source PHP content hash
• gen_stub version signature
• PHP version signature

Do not overwrite output header files when the content is unchanged.

Value

Reduce header churn, with a clear effect when combined with incremental builds.

---

P2: Parallelizing prepare / convert / stub generation

Currently only the compile stage is parallelized. Later the following can be explored:

1. Layering by dependency topology after file scanning
2. Parallel convert for files in the same layer
3. Parallel stub generation for files in the same layer

Risk Points

• There is a lot of shared state (literalStrings, classMap, funcMap, propMap, symbol tables, etc.)
• It is necessary to first sort out which state can be sharded and which must be merged

Therefore this direction has large benefits but also higher implementation complexity.

---

P2: Symbol-dependency-driven minimal recompilation

An ideal incremental build should not be based only on file timestamps, but on:

• which symbols have changed
• which files depend on those symbols

Goal

When modifying one PHP file, rebuild only:

1. the file itself
2. files that depend on its exported symbols
3. the necessary extension / declaration modules

This would significantly improve hot build speed for large projects.

---

P2: Toolchain-level optimization

Compilation caches

• ccache
• sccache

Faster linkers

• mold
• lld

Precompiled headers

Try PCH for stable large headers, for example:

• phpx.h
• phpx_helper.h
• phpx_std.h

These optimizations are relatively cheap to implement and can be advanced together with the compiler option layer.

Special Constraints on Literal Arrays

Literal arrays are different from literal strings:

• Literal strings can leverage permanent strings to bypass the Zend request lifecycle
• Literal arrays must exist from module_init() to module_clean(), i.e. between PHP's RINIT/RSHUTDOWN

Therefore all future "array initialization caching" research must obey:

1. PHP arrays must not be persisted into process-level permanent objects
2. Only the "initialization plan" or "generated code template" can be cached
3. Real array objects must be constructed within the request lifecycle

The already-introduced ArrayInitPlan belongs to this kind of safe abstraction:

• It only saves expr/init/clean
• It does not save array object instances that cross requests

Suggested Landing Order

Phase One (Fastest Effect)

1. Do not write files when content is unchanged
2. General .o cache
3. Disable clang-format by default
4. arginfo/stub content cache

Phase Two (Structural Benefits)

5. Split the common header
6. Split extension-<target>.cc
7. Narrow the visibility of default-argument helpers

Phase Three (Long-term Optimization)

8. prepare/convert parallelization
9. Symbol-dependency-driven minimal recompilation
10. PCH / ccache / mold / sccache

Suggested Code Locations to Research First

• src/Php/Translator.php
  • formatCppCode()
  • compile()
  • compileSourceFile()
  • compileWithPcntl()
  • genFunctionDeclarations()
  • genDataDeclarations()
  • genExtension()
  • genStubFile()
• src/Php/Backend/*
  • Compile/link command construction, convenient for integrating ccache / mold / lld

A Realistic Assessment

For large projects, slow AOT compilation is usually not simply "g++ is slow", but the superposition of the following:

1. Full regeneration
2. Header churn causing full recompilation
3. A single oversized extension TU
4. Per-file formatting
5. Lack of a real incremental cache

Therefore the most effective direction is not to first tune compilation flags, but to prioritize:

• incrementality
• splitting
• reducing the common dependency surface