TypePHP 编译器
https://swoole.com/aot/
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
89 lines
4.5 KiB
89 lines
4.5 KiB
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Swoole-Compiler is an AOT (Ahead-of-Time) compiler that translates PHP source code to C++, then compiles it with GCC/Clang/MSVC into native binaries. It supports Linux (primary), macOS, and Windows.
|
|
|
|
**Prerequisites**: PHP 8.2+, GCC 9+ (C++17), CMake 3.24+. The `swoole/phpx` extension must be compiled (see README.md).
|
|
|
|
## Build & Test Commands
|
|
|
|
```bash
|
|
# Install PHP dependencies
|
|
composer install
|
|
|
|
# Compile a PHP project to a native binary
|
|
php bin/compiler.php <path-to-project-or-file>
|
|
|
|
# Run all PHPUnit tests
|
|
./vendor/bin/phpunit
|
|
|
|
# Run a single PHPUnit test class
|
|
./vendor/bin/phpunit phpunit/src/AstNodeTypeTest.php
|
|
|
|
# Run PHPT integration tests (all)
|
|
php run-tests.php tests/aot/
|
|
|
|
# Run a single PHPT test
|
|
php run-tests.php tests/aot/arrays.phpt
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Translation Pipeline
|
|
|
|
The compiler follows a 4-stage pipeline, orchestrated by `src/Php/Translator.php` (the main entry point):
|
|
|
|
1. **prepare()** — Scan PHP files, collect symbol declarations and dependencies, topological-sort for compilation order
|
|
2. **convert()** — Parse PHP AST via `nikic/php-parser`, translate each node to C++ source code
|
|
3. **compile()** — Invoke the platform C++ compiler (GCC/Clang/MSVC) on generated `.cc` files
|
|
4. **build()** — Link object files into a native binary executable
|
|
|
|
### Class Hierarchy
|
|
|
|
```
|
|
src/Core/Translator (abstract base — indent/output/mode helpers)
|
|
└─ src/Php/CompilerBase (core PHP→C++ translation logic)
|
|
├─ uses traits: AstNodeType, FuncCallOptimizer, ClosureGenerator,
|
|
│ PlaceHolderGenerator, PropertyPromotion, MagicMethodDetector
|
|
└─ src/Php/Preprocessor (scanning, symbol tables, dependency sort, YAML config)
|
|
└─ src/Php/Translator (full pipeline: prepare→convert→compile→build)
|
|
└─ src/Php/CompilerTest (test-only subclass, used by PHPUnit tests)
|
|
```
|
|
|
|
### Key Components
|
|
|
|
| Directory | Purpose |
|
|
|-----------|---------|
|
|
| `src/Php/Entity/` | Data classes: `ClassDef`, `FunctionDef`, `MethodDef`, `PropertyDef`, `ConstantDef`, `InterfaceDef` |
|
|
| `src/Php/Generator/` | Codegen helpers: `ClosureGenerator`, `PlaceHolderGenerator`, `PropertyPromotion`, `Utils` |
|
|
| `src/Php/Backend/` | Compiler abstraction: `CompilerBackend` (abstract) → `Gcc`, `Clang`, `Msvc`. Factory pattern via `CompilerFactory` |
|
|
| `src/Php/Platform/` | OS abstraction: `PlatformBase` → `Linux`, `Macos`, `Windows`. Factory via `PlatformFactory` |
|
|
| `src/Php/Context/` | `ScopeContext` and `FunctionContext` for variable scoping and type tracking |
|
|
| `src/Php/Exception/` | `SyntaxError`, `Unsupported`, `DynamicCall`, `PlaceHolder`, `Skip`, `Redo`, `TestError` |
|
|
| `src/Php/Parser/` | Special-purpose parsers like `StdContainerParser` (C++ std container foreach support) |
|
|
| `src/Php/Reflection.php` | Static helpers wrapping PHP reflection (internal class/function detection) |
|
|
| `src/Php/Symbol.php` | Maps PHP operations to `phpx` C++ API symbol names |
|
|
| `src/Php/FileScanner.php` | Recursive file discovery with extension filtering (supports `.php`, `.cpp`, `.c`, `.s`, `.m`, `.mm`) |
|
|
| `src/Php/ArgInfo.php` | Generates C function argument info structures for internal function registration |
|
|
| `src/Php/Extractor.php` | Extracts interfaces from PHP classes |
|
|
| `src/Php/Visitor.php` | Base `NodeVisitorAbstract` extension (skeleton for custom AST visitors) |
|
|
| `src/Python/Translator.php` | Python-to-C++ translator (separate from the PHP pipeline) |
|
|
|
|
### Configuration
|
|
|
|
- `project.yml` — per-project build config (name, build-mode, C++ standard, compiler flags, sources, resources/icon)
|
|
- Command-line arguments and YAML config are merged in `Preprocessor`, with CLI taking highest priority
|
|
|
|
### Generated Output
|
|
|
|
Generated `.cc` and `.o` files land in `build/` directory. The compiled binary is named from `project.yml`'s `name` field (default: `app`).
|
|
|
|
### Test Infrastructure
|
|
|
|
- **PHPUnit tests** (`phpunit/src/`) — unit/integration tests for compiler internals. Bootstrap at `phpunit/bootstrap.php` defines a `BaseTest` class with an `exec()` helper that runs the compiler and expects a `TestError` exception containing a given string
|
|
- **PHPT tests** (`tests/aot/`) — end-to-end tests using the standard PHPT format (`run-tests.php`). Each `.phpt` contains PHP source and expected output sections
|
|
|
|
When writing new compiler tests, use `CompilerTest::create(ROOT_PATH)` (in `src/Php/CompilerTest.php`) which sets `forTest = true` to enable test-specific behavior without writing files to disk.
|
|
|