From eeca2e598b2cc8f64e85c35fefa24eae57c2012b Mon Sep 17 00:00:00 2001 From: tianfenghan Date: Sat, 11 Jul 2026 14:45:02 +0800 Subject: [PATCH] docs: update documentation references and compiler CLI guide - Replace UNSUPPORTED_SYNTAX.md with INCOMPATIBLE_PHP_FEATURES.md in CLASS_INHERITANCE.md - Update COMPILATION_MODES.md with correct command example using ldd instead of static compilation - Replace syntax support documentation links with compatibility-focused documents in COMPILATION_MODES.md - Rewrite COMPILER_CLI.md with concise --- docs/CLASS_INHERITANCE.md | 2 +- docs/COMPILATION_MODES.md | 10 +- docs/COMPILER_CLI.md | 1020 ++------------------ docs/HIGH_PRECISION_TYPES.md | 8 +- docs/INCOMPATIBLE_PHP_FEATURES.md | 7 +- docs/MIXED_CPP_PHP.md | 6 +- docs/NATIVE_TYPES.md | 2 +- docs/PHP_INCOMPATIBILITY_CLASSIFICATION.md | 24 +- docs/QUICKSTART.md | 14 +- docs/README.md | 246 +---- docs/UNIVERSAL_METHODS.md | 2 +- 11 files changed, 116 insertions(+), 1225 deletions(-) diff --git a/docs/CLASS_INHERITANCE.md b/docs/CLASS_INHERITANCE.md index 2de6368f..8fadcb7c 100644 --- a/docs/CLASS_INHERITANCE.md +++ b/docs/CLASS_INHERITANCE.md @@ -540,7 +540,7 @@ class EnhancedStorage { ## 📚 相关资源 - **类型系统**: [NATIVE_TYPES.md](NATIVE_TYPES.md) -- **语法限制**: [UNSUPPORTED_SYNTAX.md](UNSUPPORTED_SYNTAX.md) +- **兼容性限制**: [INCOMPATIBLE_PHP_FEATURES.md](INCOMPATIBLE_PHP_FEATURES.md) - **编译模式**: [COMPILATION_MODES.md](COMPILATION_MODES.md) - **快速入门**: [QUICKSTART.md](QUICKSTART.md) diff --git a/docs/COMPILATION_MODES.md b/docs/COMPILATION_MODES.md index 1217f5cb..8dfdb149 100644 --- a/docs/COMPILATION_MODES.md +++ b/docs/COMPILATION_MODES.md @@ -456,8 +456,8 @@ error while loading shared libraries # 设置库路径 export LD_LIBRARY_PATH=/path/to/libs:$LD_LIBRARY_PATH -# 或静态编译 -php bin/compiler.php src/ -o app --static +# 检查实际链接路径和依赖 +ldd ./app ``` --- @@ -465,9 +465,9 @@ php bin/compiler.php src/ -o app --static ## 📚 相关文档 - [快速入门指南](QUICKSTART.md) - 开始使用 AOT 编译器 -- [语法支持规范](UNSUPPORTED_SYNTAX.md) - 了解支持的语法 -- [性能优化指南](PERFORMANCE.md) - 提升编译和运行性能 -- [故障排除](TROUBLESHOOTING.md) - 解决常见问题 +- [兼容性清单](INCOMPATIBLE_PHP_FEATURES.md) - 了解当前限制 +- [构建速度研究](AOT_BUILD_SPEED_RESEARCH.md) - 优化编译流程 +- [兼容性分类](PHP_INCOMPATIBILITY_CLASSIFICATION.md) - 判断限制的性质和处理方向 --- diff --git a/docs/COMPILER_CLI.md b/docs/COMPILER_CLI.md index cfef0cb5..614e6e5b 100644 --- a/docs/COMPILER_CLI.md +++ b/docs/COMPILER_CLI.md @@ -1,990 +1,92 @@ -# AOT 编译器命令行工具使用指南 +# TypePHP 编译器命令行 -## 📋 概述 - -PHP AOT 编译器是一个强大的命令行工具，可以将 PHP 源代码编译为原生可执行文件或 PHP 扩展。它支持多种编译选项、优化级别和构建模式。 - ---- - -## 🚀 快速开始 - -### 基本用法 - -```bash -# 编译单个 PHP 文件 -./bin/compiler.php examples/hello.php - -# 编译目录 -./bin/compiler.php examples/myapp/ - -# 带优化编译 -./bin/compiler.php examples/bench.php -O2 - -# 生成扩展 -./bin/compiler.php my_extension/ -m ext -o myext -``` - ---- - -## 📖 命令格式 - -``` -./bin/compiler.php [options] -``` - -### 参数说明 - -| 参数 | 说明 | 必需 | -|------|------|------| -| `` | 要编译的 PHP 文件或目录 | ✅ 是 | - ---- - -## ⚙️ 命令行选项详解 - -### 1. `-O ` - 优化级别 - -**别名**: `--optimize` -**默认值**: `0` -**取值范围**: `0-3` - -控制 GCC 编译器的优化级别，影响生成代码的性能和大小。 - -| 级别 | 说明 | 适用场景 | -|------|------|----------| -| `-O0` | 无优化，调试模式 | 开发调试 | -| `-O1` | 基础优化 | 一般用途 | -| `-O2` | 标准优化（推荐） | 生产环境 | -| `-O3` | 激进优化 | 性能关键应用 | - -**示例**: -```bash -# 无优化编译 -./bin/compiler.php app.php -O0 - -# 标准优化 -./bin/compiler.php app.php -O2 - -# 最大优化 -./bin/compiler.php app.php -O3 -``` - ---- - -### 2. `-m ` / `--mode ` - 编译模式 - -**默认值**: `bin` -**可选值**: `bin`, `ext` - -指定编译输出类型：可执行文件或 PHP 扩展。 - -#### 🔹 bin 模式（二进制） - -生成独立的可执行文件，无需 PHP 环境即可运行。 - -**特点**: -- ✅ 需要 `main()` 函数作为入口 -- ✅ 包含完整的运行时环境 -- ✅ 可直接在命令行执行 -- ❌ 不能作为 PHP 扩展加载 - -**示例**: -```bash -./bin/compiler.php myapp/ -m bin -o myapp -./myapp # 直接运行 -``` - -#### 🔸 ext 模式（扩展） - -生成 PHP 扩展（.so/.dll），需要在 PHP 环境中运行。 - -**特点**: -- ✅ 不需要 `main()` 函数 -- ✅ 可以作为模块加载到 PHP -- ✅ 支持与现有 PHP 代码集成 -- ❌ 需要 PHP 环境 - -**示例**: -```bash -./bin/compiler.php myext/ -m ext -o myext -# 在 php.ini 中添加 -extension=myext -``` - ---- - -### 3. `-o ` / `--output ` - 输出文件名 - -**别名**: `--output` -**默认值**: 输入文件的基本名 - -指定生成的可执行文件或扩展的名称。 - -**命名规则**: -- ✅ 只能包含字母、数字和下划线 -- ❌ 不能包含连字符（`-`）或星号（`*`） -- ❌ 不能是 C++ 保留关键字 -- ❌ 不能与现有目录同名 - -**示例**: -```bash -# 自定义输出名称 -./bin/compiler.php app.php -o my_application - -# 带连字符的名称会自动转换 -./bin/compiler.php my-app.php -o my_app # ✅ 正确 -./bin/compiler.php my-app.php -o my-app # ❌ 错误，会转换为 my_app -``` - ---- - -### 4. `-j ` / `--job ` - 并行编译任务数 - -**默认值**: `4` - -控制编译过程中并行处理的任务数量，影响编译速度。 - -**建议配置**: -- **单核 CPU**: `-j 1` -- **双核 CPU**: `-j 2` -- **四核 CPU**: `-j 4` (默认) -- **八核及以上**: `-j 8` 或更高 - -**示例**: -```bash -# 单线程编译（适合调试） -./bin/compiler.php large_project/ -j 1 - -# 多线程编译（适合生产） -./bin/compiler.php large_project/ -j 8 -``` - ---- - -### 5. `-v` / `--verbose` - 详细输出 - -**别名**: `--verbose` -**类型**: 开关（无参数） - -启用详细输出模式，显示编译过程的详细信息。 - -**输出内容**: -- ✅ 每个文件的处理状态 -- ✅ 跳过不支持语法的通知 -- ✅ 编译进度信息 -- ✅ 生成的中间文件路径 - -**示例**: -```bash -./bin/compiler.php app.php -v - -# 输出示例： -# prepare: /path/to/app.php -# generate stub file: /path/to/app.php -# convert: /path/to/app.php -# format: /path/to/build/app.cpp -# Starting parallel compilation with 4 jobs for 5 files -# Successfully compiled 5 files -``` - ---- - -### 6. `-f` / `--force` - 强制编译 - -**别名**: `--force` -**类型**: 开关 - -即使缓存存在也强制重新编译。 - -**使用场景**: -- 修改了底层 C++ 代码 -- 怀疑缓存有问题 -- 需要完全重新编译 - -**示例**: -```bash -# 强制重新编译 -./bin/compiler.php app.php -f - -# 结合优化使用 -./bin/compiler.php app.php -O2 -f -``` - ---- - -### 7. `-p` / `--profile` - 性能分析 - -**别名**: `--profile` -**类型**: 开关 - -启用性能分析功能，生成可用于性能分析的可执行文件。 - -**输出内容**: -- ✅ 函数执行时间统计 -- ✅ 内存使用情况 -- ✅ 调用次数统计 - -**示例**: -```bash -# 编译带性能分析的版本 -./bin/compiler.php benchmark.php -p -O2 - -# 运行后会生成性能报告 -./benchmark -cat benchmark.prof -``` - ---- - -### 8. `--no-literal-strings` - 禁用字符串优化 - -**类型**: 开关 - -禁用字面量字符串优化，所有字符串将在运行时动态创建。 - -**默认行为**: -- ✅ 字符串常量会被提取到全局数组 -- ✅ 减少重复字符串的内存占用 -- ✅ 提高字符串比较性能 - -**禁用后的影响**: -- ❌ 增加内存使用 -- ❌ 降低字符串操作性能 -- ✅ 可能减少编译时间 - -**示例**: -```bash -# 禁用字符串优化 -./bin/compiler.php app.php --no-literal-strings -``` - ---- - -### 9. `--php-version ` - 限制 PHP 语言版本 - -**默认值**: `8.5` - -指定编译器接受的 PHP 语法版本。可选值为 `8.2`、`8.3`、`8.4` 和 `8.5`。选择较低版本时，较新版本的语法会在编译阶段直接报错。 - -该选项也会影响 `project.yml` 的 `PHP_VERSION` 与 `PHP_VERSION_ID` 源文件条件。命令行参数优先于 YAML 配置。 - -```bash -# 按 PHP 8.4 语法编译；PHP 8.5 的 Pipe Operator 将被拒绝 -./bin/compiler.php app.php --php-version 8.4 -``` - -也可以在 `project.yml` 中设置： - -```yaml -php-version: '8.4' -sources: - - main.php -``` - ---- - -### 10. `--debug-line` - 启用调试行 - -**默认值**: `0` - -在生成的 C++ 代码中包含源文件行号信息，用于调试。 - -**示例**: -```bash -# 启用调试行信息 -./bin/compiler.php app.php --debug-line 1 -``` - ---- - -### 10. `--debug` - 启用调试模式 - -**类型**: 开关 - -启用详细的调试信息输出。 - -**示例**: -```bash -# 启用调试信息 -./bin/compiler.php app.php --debug -``` - ---- - -### 11. `-h` / `--help` - 显示帮助 - -**类型**: 开关 - -显示帮助信息和所有可用选项。 - -**示例**: -```bash -./bin/compiler.php -h -``` - -**输出**: -``` -PHP AOT Compiler v1.0.0 - -USAGE: - ./bin/compiler.php [options] - -ARGUMENTS: - Input PHP file/directory to compile - -OPTIONS: - -O Optimization level (0-3, default: 0) - -p, --profile Enable performance profiling - -o, --output Output binary name (default: input basename) - -v, --verbose Verbose output - -h, --help Show this help message - -f, --force Force compile even if cache exists - -m, --mode Compilation mode, -m bin(binary) or -m ext(extension), default: bin - -j, --job Number of parallel compilation jobs (default: 4) - --no-literal-strings Disable literal strings optimization - -I, --include-path Add an additional C++ include directory (repeatable) - -D, --define Define a preprocessor macro (repeatable, e.g. -D FOO=bar) - --dry Dry run: only generate C++ code, skip compilation and linking - --lto Enable Link Time Optimization (-flto) - --format Enable clang-format code formatting (disabled by default) - --cxx-std C++ standard version (c++17, c++20, etc., default: c++17) - --march Target CPU instruction set (e.g. native, x86-64-v3, armv8-a) - -l, --link-lib Link against a library (repeatable, e.g. -lcurl) - -L, --link-path Add a library search path (repeatable, e.g. -L/usr/local/lib) - --build-dir Specify build directory for generated C++ code - -EXAMPLES: - ./bin/compiler.php examples/hello.php - ./bin/compiler.php examples/bench.php -O2 - ./bin/compiler.php examples/bench.php -O2 - ./bin/compiler.php examples/extension -O2 -o myapp -m ext - ./bin/compiler.php examples/app.php -O3 -o myapp -v -``` - ---- - -## 🎯 典型使用场景 - -### 场景一：开发环境调试 - -```bash -# 无优化，启用详细输出，单线程 -./bin/compiler.php src/app.php -O0 -v -j 1 -``` - -### 场景二：生产环境部署 - -```bash -# 标准优化，多线程编译 -./bin/compiler.php src/app.php -O2 -j 8 -``` - -### 场景三：性能关键应用 - -```bash -# 最大优化，启用性能分析 -./bin/compiler.php benchmark.php -O3 -p -``` - -### 场景四：构建 PHP 扩展 - -```bash -# 生成扩展模块 -./bin/compiler.php extension_src/ -m ext -o myext -O2 -``` - -### 场景五：大型项目 +本文档与 `src/Translator.php::showUsage()` 保持同步。使用： ```bash -# 使用配置文件，多目录编译 -./bin/compiler.php project.yml -O2 -j 16 -v +bin/compiler.php [options] [-- program-args...] ``` -### 场景六：使用外部 C++ 库 +## 常用示例 ```bash -# 添加自定义头文件路径和预处理器宏 -./bin/compiler.php app.php -I /opt/mylib/include -I ../shared/include -D MY_DEBUG=1 -O2 -``` - ---- - -### 12. `-I ` / `--include-path ` - 添加头文件搜索路径 +# 编译单文件 +bin/compiler.php app.php -**别名**: `--include-path` -**类型**: 可重复参数 +# 优化并运行，`--` 后参数传给生成的程序 +bin/compiler.php app.php -O2 -r -- --flag value -添加额外的 C++ 头文件（`.h` / `.hpp`）搜索目录。编译器的 include 路径由两部分组成： -1. 系统默认路径（PHP 头文件、PHPX 头文件等） -2. 用户通过 `-I` 指定的自定义路径 +# 编译项目配置 +bin/compiler.php project.yml -O2 -j 8 -**适用场景**: -- ✅ 引用外部 C/C++ 库的头文件 -- ✅ 项目有自定义的 C++ 扩展代码 -- ✅ 多个项目共享的头文件目录 +# 生成 PHP 扩展 +bin/compiler.php extension/ -m ext -o my_extension -**可重复使用**: 可以多次指定 `-I` 添加多个目录： -```bash -./bin/compiler.php app.php \ - -I /opt/openssl/include \ - -I /opt/mylib/include \ - -I ../shared/headers +# 只生成 C++，不编译和链接 +bin/compiler.php app.php --dry --build-dir /tmp/typephp-build ``` -**与 C++ 编译器等价**: `-I ` 直接传递给 GCC/Clang/MSVC 的 `-I` 选项。 - ---- - -### 13. `-D ` / `--define ` - 定义预处理器宏 - -**别名**: `--define` -**类型**: 可重复参数 - -定义 C++ 预处理器宏，等价于在 C++ 代码中使用 `#define`。使用 `name=value` 格式。 - -**适用场景**: -- ✅ 条件编译（`#ifdef MY_FEATURE` / `#ifndef MY_FEATURE`） -- ✅ 功能开关（`-D ENABLE_LOGGING=1`） -- ✅ 调试标志（`-D DEBUG_LEVEL=3`） -- ✅ 版本号定义（`-D APP_VERSION=\"2.0\"`） - -**格式说明**: -| 格式 | 等价 C++ 代码 | 说明 | -|------|--------------|------| -| `-D FOO` | `#define FOO` | 无值宏（值为空） | -| `-D FOO=1` | `#define FOO 1` | 整数值宏 | -| `-D FOO=bar` | `#define FOO bar` | 字符串值宏 | -| `-D FOO=\"bar\"` | `#define FOO "bar"` | 引号字符串宏 | - -**可重复使用**: 可以多次指定 `-D` 定义多个宏： -```bash -./bin/compiler.php app.php \ - -D MY_DEBUG=1 \ - -D LOG_LEVEL=3 \ - -D APP_NAME=\\"MyApp\" -``` - -**与 C++ 编译器等价**: -| 编译器 | 产生的编译标志 | -|--------|-------------| -| GCC / Clang | `-D` | -| MSVC | `/D` | - -**示例: 条件编译控制功能开关**: -```bash -# 启用调试日志 -./bin/compiler.php app.php -D ENABLE_LOGGING=1 -O2 - -# 生产环境（关闭调试） -./bin/compiler.php app.php -O2 -``` - ---- - -### 14. `--lto` - 链接时优化 - -**类型**: 开关（无参数） - -启用链接时优化（Link Time Optimization, LTO），允许编译器在链接阶段跨编译单元进行优化，可显著提升运行时性能和减小二进制体积。 - -**编译器适配**: -| 编译器 | 编译阶段标志 | 链接阶段标志 | -|--------|-----------|-----------| -| GCC | `-flto` | `-flto` | -| Clang | `-flto` | `-flto` | -| MSVC | `/GL` | `/LTCG` | - -**适用场景**: -- ✅ 生产环境部署（配合 `-O2` 或 `-O3`） -- ✅ 对性能有极致要求的应用 -- ✅ 需要减小二进制体积的场景 -- ⚠️ 会增加链接时间 - -**示例**: -```bash -# 启用 LTO 的生产环境编译 -./bin/compiler.php app.php -O2 --lto - -# 与自定义 include 和 define 组合使用 -./bin/compiler.php app.php -O3 --lto -I /opt/lib/include -D NDEBUG=1 -``` - ---- - -### 15. `--format` - 代码格式化 - -**类型**: 开关（无参数） -**默认**: 关闭 - -启用 `clang-format` 对生成的 C++ 代码进行自动格式化。由于格式化会增加编译时间，默认关闭。需要系统中安装了 `clang-format` 才能生效。 +## 构建选项 -**适用场景**: -- ✅ 需要审查生成的 C++ 代码 -- ✅ 团队开发需要统一的代码风格 -- ⚠️ 会增加编译时间 - -**示例**: -```bash -# 编译时启用代码格式化 -./bin/compiler.php app.php --format - -# 结合优化使用 -./bin/compiler.php app.php -O2 --format -``` - -如果系统未安装 `clang-format`，使用 `--format` 时会显示警告并跳过格式化。 - ---- - -### 16. `-l ` / `--link-lib ` - 链接库 - -**别名**: `--link-lib` -**类型**: 可重复参数 - -指定要链接的库，等价于 GCC/Clang 的 `-l` 选项。实际产生的标志为 `-l`。 - -**适用场景**: -- ✅ 链接第三方 C/C++ 库（如 `-lcurl`、`-lssl`） -- ✅ 链接自定义编译的静态库/动态库 -- ✅ 多库依赖的项目 - -**可重复使用**: 可以多次指定 `-l` 链接多个库： -```bash -./bin/compiler.php app.php \ - -lcurl \ - -lssl \ - -lcrypto - -# 等价的长格式 -./bin/compiler.php app.php --link-lib curl --link-lib ssl --link-lib crypto -``` - -**与 GCC/Clang 等价**: `-l` 直接传递给链接器的 `-l` 选项，链接 `lib.so` 或 `lib.a`。 - ---- - -### 17. `-L ` / `--link-path ` - 库搜索路径 - -**别名**: `--link-path` -**类型**: 可重复参数 - -添加库文件搜索路径，等价于 GCC/Clang 的 `-L` 选项。实际产生的标志为 `-L`。 - -**适用场景**: -- ✅ 链接非标准路径下的库文件 -- ✅ 使用自定义编译的本地库 -- ✅ 链接项目内部的私有库 - -**可重复使用**: 可以多次指定 `-L` 添加多个搜索路径： -```bash -./bin/compiler.php app.php \ - -L/usr/local/lib \ - -L/opt/custom/lib \ - -lmycustom - -# 等价的长格式 -./bin/compiler.php app.php --link-path /usr/local/lib --link-path /opt/custom/lib --link-lib mycustom -``` - -**与 GCC/Clang 等价**: `-L` 直接传递给链接器的 `-L` 选项。 - ---- - -### 18. `--march ` - 目标 CPU 指令集 - -**类型**: 单值参数 - -指定编译器生成针对特定 CPU 架构优化的代码。等价于 GCC/Clang 的 `-march=` 选项。 - -**常用值**: -| 值 | 说明 | +| 选项 | 说明 | |---|---| -| `native` | 自动检测并优化当前 CPU 支持的指令集 | -| `x86-64-v3` | x86-64 微架构级别 3 (AVX, AVX2, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE, XSAVE) | -| `x86-64-v4` | x86-64 微架构级别 4 (AVX512F, AVX512BW, AVX512CD, AVX512DQ, AVX512VL) | -| `armv8-a` | ARMv8-A 基础架构 | -| `armv8.1-a` | ARMv8.1-A | -| `armv8.2-a` | ARMv8.2-A | -| `armv9-a` | ARMv9-A | - -> **⚠️ 注意**: `--march` 仅适用于 GCC/Clang 编译器。MSVC 不支持此选项，请使用 `--cxx-flags /arch:AVX2` 等方式。 - -**示例**: -```bash -# 优化当前机器运行的 CPU -./bin/compiler.php app.php --march=native -O2 - -# 特定目标架构 -./bin/compiler.php app.php --march=x86-64-v3 -O2 - -# ARM 平台 -./bin/compiler.php app.php --march=armv8-a -O2 -``` - -**与 GCC/Clang 等价**: `--march=` 直接传递给编译器的 `-march=` 选项。 - ---- - -## 🔧 编译器选择 - -### 默认编译器 - -编译器会根据操作系统自动选择合适的 C++ 编译器： - -| 平台 | 默认编译器 | 说明 | -|------|----------|------| -| **macOS** | `clang++` | 系统自带，性能优秀 | -| **Linux** | `g++` | GNU 编译器集合 | -| **Windows** | `cl` (MSVC) | Microsoft Visual C++ | - -### 通过环境变量切换编译器 - -你可以通过设置环境变量来覆盖默认的编译器选择。 - -#### 方法一：PHPX_CC（推荐） - -```bash -# macOS 使用 GCC（如果已安装） -export PHPX_CC=g++ -php bin/compiler.php examples/hello.php - -# Linux 使用 Clang -export PHPX_CC=clang++ -php bin/compiler.php examples/hello.php - -# Windows 使用 Clang -set PHPX_CC=clang++ -php bin\compiler.php examples\hello.php -``` - -#### 方法二：CXX（标准环境变量） - -```bash -# 使用标准的 CXX 环境变量 -export CXX=clang++ -php bin/compiler.php examples/hello.php -``` - -**优先级**：`PHPX_CC` > `CXX` > 平台默认 - -### 通过配置文件指定编译器 - -在项目 YAML 配置文件中，可以使用 `cpp-compiler` 选项指定编译器： - -```yaml -name: myapp -type: bin -cpp-compiler: clang++ # 或 g++, cl -sources: - - src/*.php -``` - -支持的编译器名称： -- `clang++` / `clang` - LLVM Clang 编译器 -- `g++` / `gcc` - GNU GCC 编译器 -- `cl` / `msvc` - Microsoft Visual C++（仅 Windows） - -### 检查当前使用的编译器 - -编译时会显示使用的编译器信息： - -```bash -$ php bin/compiler.php examples/hello.php -Initialized new architecture: macOS + Clang -prepare: examples/hello.php -prepare completed: 1 source files in total -... -``` - ---- - -## 📁 支持的输入类型 - -### 1. 单个 PHP 文件 - -```bash -./bin/compiler.php hello.php -``` - -### 2. 目录 - -```bash -./bin/compiler.php src/ -``` - -编译器会自动扫描目录下所有的 `.php` 文件。 - -### 3. YAML 配置文件 - -```bash -./bin/compiler.php project.yml -``` - -**project.yml 示例**: -```yaml -name: myapp -type: bin -sources: - - src/*.php - - lib/**/*.php - - main.php -``` - ---- - -## 🔧 编译过程详解 - -### 阶段一：预处理 (Prepare) - -``` -prepare: /path/to/file.php -``` - -- ✅ 解析 PHP 文件 -- ✅ 检查语法错误 -- ✅ 检测不支持的语法 -- ✅ 生成抽象语法树 (AST) - -### 阶段二：生成存根文件 (Generate Stub) - -``` -generate stub file: /path/to/file.php -``` - -- ✅ 生成 `.stub.php` 文件 -- ✅ 提取函数声明 -- ✅ 生成参数信息头文件 - -### 阶段三：转换为 C++ (Convert) - -``` -convert: /path/to/file.php -``` - -- ✅ 将 PHP AST 转换为 C++ 代码 -- ✅ 生成对应的 `.cpp` 文件 -- ✅ 处理类型映射 - -### 阶段四：格式化 (Format)（需 `--format` 开启） - -``` -format: /path/to/build/file.cpp -cd /path && clang-format -i /path/to/build/file.cpp -``` - -- 🔘 需 `--format` 参数显式开启 -- ✅ 使用 clang-format 格式化 C++ 代码 -- ✅ 确保代码风格一致 - -### 阶段五：并行编译 (Parallel Compilation) - -``` -Starting parallel compilation with 4 jobs for 5 files -Successfully compiled 5 files -``` - -- ✅ 使用多个进程并行编译 C++ 文件 -- ✅ 生成目标文件 (.o) - -### 阶段六：链接 (Link) - -``` -g++ ... -o app ... -``` - -- ✅ 链接所有目标文件 -- ✅ 链接 PHPX 库和 PHP 库 -- ✅ 生成最终可执行文件 - ---- - -## ⚡ 性能优化技巧 - -### 1. 选择合适的优化级别 - -```bash -# 开发阶段：快速编译 --O0 - -# 测试阶段：平衡编译时间和性能 --O1 - -# 生产阶段：最大化性能 --O2 或 -O3 -``` - -### 2. 调整并行任务数 - -根据 CPU 核心数调整： -```bash -# 查看 CPU 核心数 -nproc - -# 设置为 CPU 核心数的 1.5 倍 --j $(($(nproc) * 3 / 2)) -``` - -### 3. 使用缓存 - -编译器会自动缓存已编译的文件，下次编译时会跳过未更改的文件。 - -```bash -# 第一次编译（慢） -./bin/compiler.php app.php - -# 第二次编译（快，使用缓存） -./bin/compiler.php app.php - -# 强制重新编译 -./bin/compiler.php app.php -f -``` - ---- - -## 🐛 故障排除 - -### 问题一：编译失败 "No valid source file found" - -**原因**: 没有找到有效的 PHP 文件 - -**解决方法**: -```bash -# 检查文件路径是否正确 -ls -la your_file.php - -# 使用绝对路径 -./bin/compiler.php /absolute/path/to/file.php -``` - -### 问题二：类名冲突 - -**原因**: 输出名称与现有类名冲突 - -**解决方法**: -```bash -# 使用不同的输出名称 -./bin/compiler.php app.php -o myapp_binary -``` - -### 问题三：内存不足 - -**原因**: 并行任务数过多导致内存耗尽 - -**解决方法**: -```bash -# 减少并行任务数 -./bin/compiler.php large_project.php -j 2 -``` - -### 问题四：不支持的语法 - -**原因**: 使用了 AOT 编译器不支持的 PHP 语法 - -**输出示例**: -``` -unsupported syntax: Dynamic property creation is not supported -skip: /path/to/file.php -``` - -**解决方法**: -1. 查看 [UNSUPPORTED_SYNTAX.md](docs/UNSUPPORTED_SYNTAX.md) -2. 修改代码使用支持的语法 -3. 或将代码封装到函数中 - ---- - -## 📊 编译选项组合示例 - -### 示例组合 - -```bash -# 快速开发构建 -./bin/compiler.php app.php -O0 -j 1 - -# 标准生产构建 -./bin/compiler.php app.php -O2 -j 8 -v - -# 高性能构建 -./bin/compiler.php app.php -O3 -j 16 -p - -# 外部库集成构建 -./bin/compiler.php app.php -I /opt/mylib/include -D ENABLE_FEATURE=1 -O2 - -# 调试构建 -./bin/compiler.php app.php -O0 -v --debug - -# 扩展构建 -./bin/compiler.php ext/ -m ext -o myext -O2 -v -``` - ---- - -## 📝 最佳实践 - -### 1. 开发环境 - -```bash -# 使用脚本自动化 -#!/bin/bash -./bin/compiler.php src/app.php -O0 -v -j 1 -``` - -### 2. CI/CD 流水线 - -```bash -# 持续集成 -./bin/compiler.php tests/ -O2 -j $(nproc) -v -``` +| `-O <0-3>` | 优化级别，默认 `0`。 | +| `-d`, `--debug` | 调试构建；关闭优化、增加调试符号和 TypePHP 源码跟踪。 | +| `-o`, `--output ` | 输出文件名。 | +| `-m`, `--mode ` | 构建模式，默认 `bin`。 | +| `-r`, `--run` | 构建成功后运行。 | +| `-j`, `--job ` | 并行编译任务数，默认 `4`。 | +| `-f`, `--force` | 忽略 phpx misc 对象缓存，强制重新编译。 | +| `--build-dir ` | 生成的 C++ 和中间产物目录。 | +| `--dry` | 只生成 C++，跳过编译与链接。 | +| `--format` | 对生成代码运行 clang-format。 | +| `--no-progress` | 不显示进度条，逐文件输出进度。 | +| `--no-color` | 禁用彩色输出。 | + +`-v` / `--version` 只显示版本，不是 verbose 选项。 + +## 目标和工具链 + +| 选项 | 说明 | +|---|---| +| `--php-version <8.2|8.3|8.4|8.5>` | 限制接受的 PHP 语法版本，默认 `8.5`。 | +| `--cxx-std ` | C++ 标准，例如 `c++17`、`c++20`。 | +| `--march ` | 目标指令集，例如 `native`、`x86-64-v3`。 | +| `--target-platform ` | 交叉编译目标 triple。 | +| `--lto` | 启用 Link Time Optimization。 | +| `--sanitize ` | 启用 sanitizer，例如 `address`、`undefined`。 | +| `--no-console` | Windows GUI 模式隐藏控制台窗口。 | +| `--profile` | Linux 上启用 gperftools profiler，并强制重编译相关对象。 | -### 3. 生产部署 +`--php-version` 控制解析器接受的源码语法，也用于 `project.yml` 中依据 `PHP_VERSION` / `PHP_VERSION_ID` 选择源文件。它不负责选择链接的 PHP 安装目录。 -```bash -# 生产环境 -./bin/compiler.php release/app.php \ - -O2 \ - -j $(nproc) \ - -o app \ - -v \ - --force -``` +## C++ 编译和链接参数 -### 4. 性能测试 +这些参数均可重复： ```bash -# 基准测试 -./bin/compiler.php benchmark.php -O3 -p -o benchmark_optimized +-I /opt/library/include +-D FEATURE_ENABLED=1 +-L /opt/library/lib +-l curl ``` ---- +对应长选项： -## 🎓 高级主题 +- `--include-path` +- `--define` +- `--link-path` +- `--link-lib` -### 1. 自定义编译流程 +## 项目配置优先级 -可以通过修改 `src/config/compiler_options.php` 添加自定义选项。 +传入 `project.yml` 时，命令行参数优先于 YAML 中的同名配置。项目文件格式参见用户文档及代码中的项目配置解析器。 -### 2. 扩展编译器 +## 查看权威帮助 -实现自定义的 Preprocessor 或 Translator 来扩展编译器功能。 +命令行实现可能继续演进，发布版本的实际参数以以下命令为准： -### 3. 性能调优 - -分析编译过程中的瓶颈： ```bash -time ./bin/compiler.php large_project.php -v +bin/compiler.php --help ``` ---- - -## 📚 相关资源 - -- **快速入门**: [QUICKSTART.md](QUICKSTART.md) -- **编译模式**: [COMPILATION_MODES.md](COMPILATION_MODES.md) -- **原生类型**: [NATIVE_TYPES.md](NATIVE_TYPES.md) -- **混合编程**: [MIXED_CPP_PHP.md](MIXED_CPP_PHP.md) -- **语法限制**: [UNSUPPORTED_SYNTAX.md](UNSUPPORTED_SYNTAX.md) - ---- - -**最后更新**: 2024 年 3 月 19 日 -**适用版本**: PHP AOT Compiler v1.0.0 +兼容性边界参见 [INCOMPATIBLE_PHP_FEATURES.md](INCOMPATIBLE_PHP_FEATURES.md)，构建模式参见 [COMPILATION_MODES.md](COMPILATION_MODES.md)。 diff --git a/docs/HIGH_PRECISION_TYPES.md b/docs/HIGH_PRECISION_TYPES.md index c6d6e05b..68446963 100644 --- a/docs/HIGH_PRECISION_TYPES.md +++ b/docs/HIGH_PRECISION_TYPES.md @@ -748,8 +748,8 @@ pi × 2: 6.2831800000000000 - **类型系统规范**：[`docs/NATIVE_TYPES.md`](NATIVE_TYPES.md) — 完整的类型提升规则、声明语法、C++ API 参考 - **BigInt PHPT 测试**：[`tests/aot/bigint/`](../tests/aot/bigint/) — BigInt 各项功能的集成测试 - **Decimal PHPT 测试**：[`tests/aot/decimal/`](../tests/aot/decimal/) — Decimal 各项功能的集成测试 -- **BigFloat 集成测试**：[`tests/aot/bigfloat_operators.phpt`](../tests/aot/bigfloat_operators.phpt) — BigFloat 运算符测试 +- **BigFloat 集成测试**：[`tests/aot/bignumber/bigfloat_operators.phpt`](../tests/aot/bignumber/bigfloat_operators.phpt) — BigFloat 运算符测试 - **C++ 运行时头文件**： - - [`phpx/include/phpx_big_int.h`](../phpx/include/phpx_big_int.h) — BigInt C++ API - - [`phpx/include/phpx_decimal.h`](../phpx/include/phpx_decimal.h) — Decimal C++ API - - [`phpx/include/phpx_big_float.h`](../phpx/include/phpx_big_float.h) — BigFloat C++ API + - [`phpx/include/phpx_big_int.h`](../../phpx/include/phpx_big_int.h) — BigInt C++ API + - [`phpx/include/phpx_decimal.h`](../../phpx/include/phpx_decimal.h) — Decimal C++ API + - [`phpx/include/phpx_big_float.h`](../../phpx/include/phpx_big_float.h) — BigFloat C++ API diff --git a/docs/INCOMPATIBLE_PHP_FEATURES.md b/docs/INCOMPATIBLE_PHP_FEATURES.md index 12839154..cf4ff0ad 100644 --- a/docs/INCOMPATIBLE_PHP_FEATURES.md +++ b/docs/INCOMPATIBLE_PHP_FEATURES.md @@ -15,14 +15,14 @@ - 不支持可变变量 `$$var`。 - PHP 8.4 property hooks 会降级为 AOT getter/setter；直接属性读写和动态对象读写均受支持。当前不支持对 hook 属性取引用。 -- 支持 `private(set)` 与 `protected(set)` 非对称属性可见性；在 PHP 8.2/8.3 后端通过自定义属性写 handler 执行同等作用域检查。 +- 支持 `private(set)` 与 `protected(set)` 非对称属性可见性；在 PHP 8.2～8.4 后端通过自定义属性写 handler 执行同等作用域检查。 - 不支持闭包或箭头函数按引用返回。 - `__construct()` 不允许返回值。 - 参数默认值不允许出现在必填参数之前（`PHP`允许，但会直接丢弃此默认参数）。 - 不支持引用可变参数 `&...$args`。 - 联合类型、交叉类型、`nullable` 类型仍以 `mixed/any` 作为 C++ 表示，但静态阶段会利用已知表达式类型提前拒绝确定不兼容的参数、返回值和属性赋值；动态值仍保留运行时 type check。 - 局部变量类型一旦被静态推断为具体 native 类型，不支持在同一作用域内重新赋值为不兼容类型。 -- attribute 参数不支持数组值和 `new` 表达式。 +- attribute 参数不支持非空数组值和 `new` 表达式。 ## declare @@ -33,6 +33,7 @@ ## 调用与引用 +- TypePHP 使用严格参数数量规则：非 variadic 函数不接受声明范围之外的额外参数；`func_get_args()` 不会隐式放宽签名。 - 闭包和箭头函数不支持引用参数。 - 引用赋值不支持从复杂静态属性表达式建立引用。 - 动态调用、闭包调用等编译期无法确定参数签名的调用，不能自动转换引用参数；需要显式使用 `refval()` 或等价关键词方法 `toRef()`。 @@ -41,6 +42,8 @@ ## 对象模型 +- `toInt()`、`toString()`、`toArray()` 等保留关键词方法先于普通对象方法解析；需要参数的同名业务方法不按普通对象方法语义调用。 +- 固定值类型属性未显式初始化时使用类型零值，不保留 ZendPHP 的完整 uninitialized 状态；因此 `??` 等依赖 uninitialized 状态的表达式可能不同。 - 禁止子类用同名 `private` 属性隐藏父类私有属性；`public` / `protected` 同名声明视为同一个继承 property slot，仍须满足类型、可见性和 `readonly` 兼容性要求。 - 为避免 typed property 写入路径引入额外动态检查，native typed property 在右值类型不确定或与属性类型不一致时会退化为 `setProperty()`；部分标量赋值可能遵循 Zend 弱类型转换，而不是 AOT 默认 strict 语义。 - constructor property promotion 的运行时属性可用，但 `ReflectionProperty::isPromoted()` 目前不返回标准 PHP 结果。 diff --git a/docs/MIXED_CPP_PHP.md b/docs/MIXED_CPP_PHP.md index b7185f72..6d59399d 100644 --- a/docs/MIXED_CPP_PHP.md +++ b/docs/MIXED_CPP_PHP.md @@ -911,10 +911,10 @@ function get_adult_users() { ```bash # 保留中间文件 -php bin/compiler.php project -o app --keep-all +php bin/compiler.php project --dry --build-dir /tmp/typephp-build # 查看生成的 C++ 代码 -cat build/app.cpp +find /tmp/typephp-build -name '*.cc' -o -name '*.cpp' ``` ### 2. 类型检查 @@ -1007,7 +1007,7 @@ php::Int php_calculator_add(php::Object calc, php::Int a, php::Int b) { - **示例项目**: `examples/prime/` - **PHPX 框架文档**: [链接] - **C++ 类型系统**: 参见 [NATIVE_TYPES.md](NATIVE_TYPES.md) -- **AOT 编译器架构**: 参见 [ARCHITECTURE.md](ARCHITECTURE.md) +- **AOT 编译器架构**: 参见 [后端中立 IR](BACKEND_NEUTRAL_IR.md) 和 [核心重构计划](REFACTORING_PLAN.md) --- diff --git a/docs/NATIVE_TYPES.md b/docs/NATIVE_TYPES.md index b059b228..7b156ed5 100644 --- a/docs/NATIVE_TYPES.md +++ b/docs/NATIVE_TYPES.md @@ -41,7 +41,7 @@ $user->profile = null; // ✅ 对象属性可显式设置为 null 在 PHP 中，`unset($obj->prop)` 可以让对象属性脱离当前值状态，后续表现为未初始化或空值状态；对固定值类型属性赋值 `null` 也会把值状态改成空值。从 AOT 的类型系统角度看，这等价于把属性从声明的 `int`、`float`、`bool`、`string`、`array` 改变为 `null`/未初始化状态。AOT 编译器不允许这些固定值类型属性改变类型，因此属性永远是声明时的类型。 -具体类对象属性使用更严格的对象类型规则：`public MyClass $object` 可以被 `unset()` 或设置为 `null`；但再次赋值对象时，运行时对象类型必须是 `MyClass` 本身。与 PHP 不同，AOT 不允许把子类对象赋给基类属性。 +具体类对象属性使用静态对象类型规则：非空赋值必须满足 `is-a` 关系，因此允许把子类对象赋给基类属性，不允许把无继承关系的对象或基类对象赋给子类属性。非 nullable 属性可以 `unset()`，但不能赋值为 `null`。 正确做法： diff --git a/docs/PHP_INCOMPATIBILITY_CLASSIFICATION.md b/docs/PHP_INCOMPATIBILITY_CLASSIFICATION.md index 9e78044c..5174ee61 100644 --- a/docs/PHP_INCOMPATIBILITY_CLASSIFICATION.md +++ b/docs/PHP_INCOMPATIBILITY_CLASSIFICATION.md @@ -72,6 +72,9 @@ These items should be documented with the exact boundary. | Reassigning a statically inferred native local to an incompatible type | Intentional Rule | This is the cost of native type optimization. Use dynamic zval variables when PHP-style type changes are required. | | Native `std::int` overflow and integer division behavior | Intentional Rule | Native numeric types trade PHP compatibility for performance and C++ storage. | | `__CLASS__` outside class context and `__TRAIT__` outside trait context | Intentional Rule | PHP returns an empty string for legacy compatibility. TypePHP rejects this as a clearer rule. | +| Strict function argument counts | Intentional Rule | Non-variadic functions reject extra arguments. `func_get_args()` does not implicitly make a function variadic. | +| Reserved keyword methods such as `toArray()` | Intentional Rule | Conversion keywords are resolved before ordinary object methods to keep conversion lowering static and predictable. | +| Zero-initialized fixed typed property slots | Intentional Rule / Partial | Native fixed-layout slots use their type's zero value instead of preserving every Zend uninitialized-property transition. | ## Implementable but Currently Unsupported @@ -109,27 +112,6 @@ These items should be documented with the exact boundary. | Native typed properties | Partial / Intentional Rule | Fast native paths may not preserve every PHP dynamic state transition. Unknown or incompatible values can fall back to `setProperty()`. | | Reflection metadata | Partial | Runtime declarations exist, but some AOT-specific metadata such as promoted-property flags may be incomplete. | -## Outdated or Ambiguous Items in `UNSUPPORTED_SYNTAX.md` - -`UNSUPPORTED_SYNTAX.md` contains historical material and should not be treated as -the authoritative current compatibility list without verification. - -Items that need review: - -- Attributes are not necessarily wholly unsupported. The current limitation is - narrower: some attribute argument forms, such as arrays and `new`, are not - supported. -- Traits may no longer be purely "planned support"; current implementation and - tests should be checked before documenting them as unsupported. -- `foreach` by-reference support is partial, not absent. -- `break N` and `continue N` should be rechecked against current compiler - behavior before keeping them in the unsupported list. -- DOM or `innerHTML` is not PHP language syntax and should not be listed as a - core AOT syntax incompatibility. -- Duplicate function or class names should be documented carefully. Some cases - are PHP fatal errors, while conditional declarations are a separate dynamic - declaration problem. - ## Documentation Rule When documenting a compatibility difference, use one of these labels: diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 314586b4..61de2a00 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -209,13 +209,13 @@ for ($i = 0; $i < 10; $i++) { // 错误！ ### 运行单个测试 ```bash -php run-tests.php --no-aot tests/aot/arrow-functions.phpt +PHPT=1 php run-tests.php tests/aot/arrow_fn/001.phpt ``` ### 运行所有测试 ```bash -php run-tests.php --no-aot tests/aot/ +PHPT=1 php run-tests.php tests/aot/ ``` ### 查看测试结果 @@ -263,13 +263,13 @@ project/ ## 🔍 常见问题 ### Q: 编译失败，提示 "Not implemented" -**A**: 该语法特性暂不支持。查看 [语法支持规范](UNSUPPORTED_SYNTAX.md) 了解支持的语法。 +**A**: 先查看 [兼容性清单](INCOMPATIBLE_PHP_FEATURES.md) 判断它是 TypePHP 设计规则、部分支持还是当前尚未实现。 ### Q: 如何调试编译后的程序？ -**A**: 使用 `--keep-all` 选项保留中间文件，查看生成的 C++ 代码。 +**A**: 使用 `--dry` 只生成中间代码，并通过 `--build-dir` 指定目录。 ```bash -php bin/compiler.php src/ -o app --keep-all +php bin/compiler.php src/ --dry --build-dir /tmp/typephp-build ``` ### Q: 编译速度慢怎么办？ @@ -285,9 +285,9 @@ php bin/compiler.php src/ -o app -j4 # 使用 4 个进程 完成快速入门后，建议阅读： -1. **[语法支持规范](UNSUPPORTED_SYNTAX.md)** - 详细了解支持的语法 +1. **[兼容性清单](INCOMPATIBLE_PHP_FEATURES.md)** - 了解当前限制 2. **[编译模式详解](COMPILATION_MODES.md)** - 深入了解两种编译模式 -3. **[性能优化指南](PERFORMANCE.md)** - 提升程序性能 +3. **[构建速度研究](AOT_BUILD_SPEED_RESEARCH.md)** - 优化编译流程 --- diff --git a/docs/README.md b/docs/README.md index 85a3a240..aec26807 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,230 +1,34 @@ -# PHP AOT 编译器文档索引 +# TypePHP 编译器内部文档 -## 📚 文档概览 +本目录包含编译器实现、兼容性、构建模式和专项设计文档。用户侧使用手册位于独立的 `aot/docs` 仓库；这里的研究报告和重构计划可能描述历史状态，当前行为应以代码、测试和兼容性清单为准。 -本文档集合为 PHP AOT (Ahead-Of-Time) 编译器提供完整的使用指南和技术参考。 +## 当前权威文档 ---- +- [AOT 与 PHP 不兼容特性清单](INCOMPATIBLE_PHP_FEATURES.md)：当前限制的简明清单。 +- [不兼容性分类](PHP_INCOMPATIBILITY_CLASSIFICATION.md)：区分 Hard Limit、Intentional Rule、Pending 和 Partial。 +- [编译器命令行](COMPILER_CLI.md)：当前 CLI 参数和项目配置。 +- [编译模式](COMPILATION_MODES.md)：binary、extension、library 模式。 +- [快速入门](QUICKSTART.md)：最小编译流程。 +- [编译期函数](COMPILE_TIME_FUNCTIONS.md)：`any()`、`refval()`、`objval()` 和关键词方法。 +- [原生类型](NATIVE_TYPES.md)、[高精度类型](HIGH_PRECISION_TYPES.md)、[Std 容器](STD_CONTAINERS.md)。 +- [通用与扩展方法](UNIVERSAL_METHODS.md)、[Generator](YIELD_GENERATOR.md)。 +- [类继承](CLASS_INHERITANCE.md)、[混合 C++/PHP](MIXED_CPP_PHP.md)。 -## 📖 核心文档 +## 架构与维护 -### 1. [语法支持规范](UNSUPPORTED_SYNTAX.md) -**必读指数**: ⭐⭐⭐⭐⭐ +- [后端中立 IR](BACKEND_NEUTRAL_IR.md) +- [核心重构计划](REFACTORING_PLAN.md) +- [构建速度研究](AOT_BUILD_SPEED_RESEARCH.md) +- [优化优先级](aot-optimization-priority.md) +- [GMP 差异](GMP_GAP.md) -详细说明： -- ✅ 已支持的 PHP 语法特性（50+ 个） -- ❌ 不支持的语法（7 种） -- ⏳ 计划支持的语法（2 种） -- 📊 编译模式对比表 -- 💡 代码结构最佳实践 +## 研究与历史资料 -**适合人群**: 所有使用者 +`hhvm-review.md`、`kphp-review.md`、`peachpie-review.md`、`phpstan-design-analysis.md`、`php-src-optimizer-analysis.md` 以及专利草案用于记录调研时点的比较和设计背景，不作为当前功能清单。 ---- +## 维护规则 -### 1.1 [AOT 与 PHP 不兼容特性清单](INCOMPATIBLE_PHP_FEATURES.md) -**必读指数**: ⭐⭐⭐⭐⭐ - -内容概要： -- 当前 AOT 与标准 PHP 的关键不兼容点 -- 编译期限制、运行时动态能力限制、AOT 扩展类型限制 -- 仅保留简明列表，不包含示例和长篇解释 - -**适合人群**: 所有使用者、框架适配者 - ---- - -### 1.2 [AOT 编译期函数与关键词方法](COMPILE_TIME_FUNCTIONS.md) -**必读指数**: ⭐⭐⭐⭐ - -内容概要： -- AOT 专用编译期函数清单 -- `any()`、`refval()`、`objval()` 的语义和限制 -- `toAny()`、`toRef()` 等关键词方法 -- 当前实现风险和后续统一方向 - -**适合人群**: 所有使用者、贡献者、框架适配者 - ---- - -### 2. [快速入门指南](QUICKSTART.md) -**必读指数**: ⭐⭐⭐⭐⭐ - -内容概要： -- 🚀 5 分钟快速开始 -- 📦 安装和配置 -- 🔧 基本使用示例 -- 🎯 第一个 AOT 编译项目 - -**适合人群**: 新手用户 - ---- - -### 3. [编译模式详解](COMPILATION_MODES.md) -**必读指数**: ⭐⭐⭐⭐ - -内容概要： -- 🔹 扩展模式（Extension Mode） - - 编译为 .so/.dll 文件 - - 在 php-fpm 中加载 - - Web 应用场景 - -- 🔸 二进制模式（Binary Mode） - - 编译为独立可执行文件 - - main() 函数要求 - - CLI 和服务端应用 - -**适合人群**: 开发者、架构师 - ---- - -### 4. [测试指南](TESTING_GUIDE.md) -**必读指数**: ⭐⭐⭐⭐ - -内容概要： -- 🧪 运行测试的方法 -- 📝 编写 phpt 测试文件 -- ✅ 测试规范和最佳实践 -- 🔍 调试测试失败 -- 📊 测试覆盖率分析 - -**适合人群**: 测试人员、贡献者 - ---- - -### 5. [性能优化指南](PERFORMANCE.md) -**必读指数**: ⭐⭐⭐ - -内容概要： -- ⚡ 编译优化选项 -- 🎯 运行时性能调优 -- 📈 基准测试方法 -- 💾 内存管理策略 - -**适合人群**: 高级用户、性能工程师 - ---- - -### 6. [故障排除](TROUBLESHOOTING.md) -**必读指数**: ⭐⭐⭐⭐ - -内容概要： -- ❗ 常见错误和解决方案 -- 🔧 调试技巧 -- 💬 FAQ 常见问题 -- 🆘 获取帮助 - -**适合人群**: 所有使用者 - ---- - -### 7. [架构设计](ARCHITECTURE.md) -**必读指数**: ⭐⭐⭐ - -内容概要： -- 🏗️ 编译器架构概述 -- 📐 设计理念和原则 -- 🔗 组件和模块说明 -- 📊 数据流和工作流程 - -**适合人群**: 贡献者、研究者 - ---- - -### 8. [贡献指南](CONTRIBUTING.md) -**必读指数**: ⭐⭐⭐ - -内容概要： -- 🤝 如何贡献代码 -- 📝 提交 PR 的流程 -- 🎨 代码规范 -- 🧪 测试要求 - -**适合人群**: 贡献者 - ---- - -### 9. [核心重构计划](REFACTORING_PLAN.md) -**必读指数**: ⭐⭐⭐⭐ - -内容概要： -- 核心类职责拆分方向 -- TypeSystem、SymbolResolver、PropertyAccessResolver、CallResolver 等模块规划 -- 渐进式重构阶段计划 -- 测试门禁和风险控制要求 - -**适合人群**: 核心开发者、架构重构参与者 - ---- - -## 🎯 快速导航 - -### 按使用场景 - -#### 我想开始使用 AOT 编译器 -1. 阅读 [快速入门指南](QUICKSTART.md) -2. 查看 [语法支持规范](UNSUPPORTED_SYNTAX.md) 了解限制 -3. 参考 [编译模式详解](COMPILATION_MODES.md) 选择模式 - -#### 我想运行测试 -1. 阅读 [测试指南](TESTING_GUIDE.md) -2. 使用 `php run-tests.php --no-aot tests/aot/` 命令 -3. 遇到问题查看 [故障排除](TROUBLESHOOTING.md) - -#### 我想优化性能 -1. 阅读 [性能优化指南](PERFORMANCE.md) -2. 查看基准测试结果 -3. 应用优化建议 - -#### 我想贡献代码 -1. 阅读 [贡献指南](CONTRIBUTING.md) -2. 了解 [架构设计](ARCHITECTURE.md) -3. Fork 项目并提交 PR - ---- - -## 📋 文档维护 - -### 文档位置 -- ✅ 所有 `.md` 文档必须放在 `docs/` 目录下 -- ❌ 不要在其他目录创建文档文件 - -### 文档更新 -- 保持文档与代码同步 -- 重大变更需要更新相关文档 -- 添加更新日期和版本信息 - -### 文档质量 -- 使用清晰的标题和结构 -- 包含代码示例 -- 提供实际可运行的示例 -- 使用中文编写（除非特殊需要） - ---- - -## 🔗 外部资源 - -- **PHP 官方文档**: https://www.php.net/manual/en/ -- **GitHub 仓库**: [项目地址] -- **问题追踪**: [Issue Tracker] -- **社区论坛**: [Community Forum] - ---- - -## 📞 联系方式 - -- 技术支持：[support@example.com] -- 商务合作：[business@example.com] -- 社区讨论：[Slack/Discord 链接] - ---- - -## 📜 许可证 - -本文档遵循 [MIT License](LICENSE) - ---- - -**最后更新**: 2024 年 3 月 18 日 -**文档版本**: v1.0 -**适用版本**: PHP AOT Compiler v1.x +1. 当前兼容性变化同时更新 `INCOMPATIBLE_PHP_FEATURES.md` 和分类文档。 +2. 所有语法和语义限制统一链接到当前兼容性清单，避免维护重复清单。 +3. 功能是否支持应以 PHPT/PHPUnit 回归测试为依据。 +4. 历史研究文档保留原始比较结论，并在需要时注明调研日期，不应悄然改写为当前状态。 diff --git a/docs/UNIVERSAL_METHODS.md b/docs/UNIVERSAL_METHODS.md index 259fc224..52e609b2 100644 --- a/docs/UNIVERSAL_METHODS.md +++ b/docs/UNIVERSAL_METHODS.md @@ -1103,7 +1103,7 @@ function main(): void { - **高精度类型教程**：[`docs/HIGH_PRECISION_TYPES.md`](HIGH_PRECISION_TYPES.md) - **类型系统规范**：[`docs/NATIVE_TYPES.md`](NATIVE_TYPES.md) -- **通用方法实现**：[`src/Php/UniversalMethodCall.php`](../src/Php/UniversalMethodCall.php) +- **通用方法实现**：[`src/UniversalMethodCall.php`](../src/UniversalMethodCall.php) - **集成测试**： - [`tests/aot/string_method/`](../tests/aot/string_method/) — String 通用方法测试 - [`tests/aot/array_method/`](../tests/aot/array_method/) — Array 通用方法测试