- Create comprehensive guide for rebuilding PHPX WASM static library - Document directory conventions and toolchain preparation steps - Provide detailed instructions for daily development builds with CMake - Include procedures for full SDK rebuild and PHP ABI changes - Add validation steps and common error troubleshooting - Update main documentation index with new rebuild guide linkmaster
parent
496e6a4d69
commit
f79d40f8ee
2 changed files with 356 additions and 0 deletions
@ -0,0 +1,355 @@ |
||||
# 重建 PHPX WASM 静态库 |
||||
|
||||
本文面向 TypePHP/PHPX 开发者，说明如何为 `wasm32-wasip2` 重新编译并安装 |
||||
PHPX 静态库。普通 TypePHP 用户不需要执行这些步骤；发行包应直接提供完整的 |
||||
WASI SDK。 |
||||
|
||||
## 目录约定 |
||||
|
||||
本文假设源码布局如下： |
||||
|
||||
```text |
||||
/home/swoole/workspace/aot/ |
||||
├── compiler/ |
||||
└── phpx/ |
||||
``` |
||||
|
||||
建议先设置 PHPX 根目录： |
||||
|
||||
```shell |
||||
export PHPX_HOME=/home/swoole/workspace/aot/phpx |
||||
``` |
||||
|
||||
安装前缀固定为： |
||||
|
||||
```text |
||||
$PHPX_HOME/wasm/wasm32-wasip2 |
||||
``` |
||||
|
||||
该目录既是已有 PHP/WASI SDK 的输入，也是 PHPX 构建结果的安装位置： |
||||
|
||||
```text |
||||
wasm/wasm32-wasip2/ |
||||
├── include/php/ PHP/WASI 头文件 |
||||
├── include/phpx/ PHPX/TypePHP 运行时头文件 |
||||
├── lib/libphp.a |
||||
├── lib/libphpx.a |
||||
├── lib/libgmp.a |
||||
├── lib/libgmpxx.a |
||||
├── lib/libmpfr.a |
||||
├── lib/libmpdec.a |
||||
├── lib/libmpdec++.a |
||||
└── .typephp-wasi-sdk-abi |
||||
``` |
||||
|
||||
不要把 host 平台的 `libphpx.so`、`phpx.dll` 或 `.a` 文件复制到这里。 |
||||
WASM 静态库包含目标 ABI，不能跨 WASI、Linux、macOS 或 Windows 使用。 |
||||
|
||||
## 工具链准备 |
||||
|
||||
PHPX WASM 当前只支持 WASI 0.2 Preview 2。将 WASI SDK 加入 `PATH`： |
||||
|
||||
```shell |
||||
export PATH=/opt/wasi-sdk-33.0/bin:$PATH |
||||
``` |
||||
|
||||
`PATH` 只负责让 shell 和构建工具找到 WASI SDK 程序，并不会让 CMake 自动选择 |
||||
WASI target。第一次配置构建目录时仍然必须传入 |
||||
`-DCMAKE_TOOLCHAIN_FILE=.../wasi-sdk-p2.cmake`。如果省略它，CMake 会选择 host |
||||
平台的 `/usr/bin/cc` 和 `/usr/bin/c++`，PHPX 的目标检查会立即拒绝该配置。 |
||||
|
||||
确认必要工具： |
||||
|
||||
```shell |
||||
command -v wasm32-wasip2-clang |
||||
command -v wasm32-wasip2-clang++ |
||||
command -v llvm-ar |
||||
command -v llvm-ranlib |
||||
command -v llvm-nm |
||||
command -v cmake |
||||
command -v ninja |
||||
``` |
||||
|
||||
确认编译目标： |
||||
|
||||
```shell |
||||
wasm32-wasip2-clang++ --print-target-triple |
||||
``` |
||||
|
||||
必须输出： |
||||
|
||||
```text |
||||
wasm32-unknown-wasip2 |
||||
``` |
||||
|
||||
安装前缀必须已经包含与当前 PHPX 匹配的 PHP/WASI 头文件和 `libphp.a`： |
||||
|
||||
```shell |
||||
test -f "$PHPX_HOME/wasm/wasm32-wasip2/include/php/main/php.h" |
||||
test -f "$PHPX_HOME/wasm/wasm32-wasip2/lib/libphp.a" |
||||
``` |
||||
|
||||
## 日常开发：直接使用 CMake 重建 PHPX |
||||
|
||||
PHPX 的 `.cc` 或头文件发生变化时，直接使用 `phpx/wasm/CMakeLists.txt` 增量重建。 |
||||
这是日常开发的推荐流程，不会重新下载或编译 PHP、GMP 和 MPFR，也不会重新生成 |
||||
`libphp.a`。 |
||||
|
||||
首先从当前 WASI 编译器定位 CMake toolchain，避免依赖硬编码的 SDK 版本路径： |
||||
|
||||
```shell |
||||
WASI_RESOURCE_DIR="$(wasm32-wasip2-clang++ --print-resource-dir)" |
||||
WASI_SDK_ROOT="$(cd "$WASI_RESOURCE_DIR/../../.." && pwd)" |
||||
WASI_CMAKE_TOOLCHAIN="$WASI_SDK_ROOT/share/cmake/wasi-sdk-p2.cmake" |
||||
test -f "$WASI_CMAKE_TOOLCHAIN" |
||||
``` |
||||
|
||||
### 使用 Ninja（推荐） |
||||
|
||||
首次配置持久化构建目录： |
||||
|
||||
```shell |
||||
cmake \ |
||||
-S "$PHPX_HOME/wasm" \ |
||||
-B "$PHPX_HOME/build/wasm32-wasip2" \ |
||||
-G Ninja \ |
||||
-DCMAKE_TOOLCHAIN_FILE="$WASI_CMAKE_TOOLCHAIN" \ |
||||
-DCMAKE_BUILD_TYPE=Release \ |
||||
-DPHPX_WASI_SDK_DIR="$PHPX_HOME/wasm/wasm32-wasip2" \ |
||||
-DCMAKE_INSTALL_PREFIX="$PHPX_HOME/wasm/wasm32-wasip2" |
||||
``` |
||||
|
||||
toolchain 在 CMake 执行 `project()` 时生效，所以只能在构建目录的第一次配置时设置。 |
||||
如果该目录此前未传 toolchain、已经缓存了 host 编译器，不要直接在原缓存上补参数； |
||||
改用一个新的构建目录，例如： |
||||
|
||||
```shell |
||||
cmake \ |
||||
-S "$PHPX_HOME/wasm" \ |
||||
-B "$PHPX_HOME/build/wasm32-wasip2-wasi" \ |
||||
-G Ninja \ |
||||
-DCMAKE_TOOLCHAIN_FILE="$WASI_CMAKE_TOOLCHAIN" \ |
||||
-DCMAKE_BUILD_TYPE=Release \ |
||||
-DPHPX_WASI_SDK_DIR="$PHPX_HOME/wasm/wasm32-wasip2" \ |
||||
-DCMAKE_INSTALL_PREFIX="$PHPX_HOME/wasm/wasm32-wasip2" |
||||
``` |
||||
|
||||
后续的 build/install 命令也应使用这个新目录。 |
||||
|
||||
编译并安装： |
||||
|
||||
```shell |
||||
cmake --build "$PHPX_HOME/build/wasm32-wasip2" --parallel 16 |
||||
cmake --install "$PHPX_HOME/build/wasm32-wasip2" |
||||
``` |
||||
|
||||
以后 PHPX 源码再次变化时，只需要执行： |
||||
|
||||
```shell |
||||
cmake --build "$PHPX_HOME/build/wasm32-wasip2" --parallel 16 |
||||
cmake --install "$PHPX_HOME/build/wasm32-wasip2" |
||||
``` |
||||
|
||||
CMake/Ninja 只会重新编译发生变化的源文件，然后更新安装目录中的 `libphpx.a`。 |
||||
|
||||
### 使用 Make |
||||
|
||||
可以使用 `make`，但首次配置时必须选择 `Unix Makefiles` 生成器，并使用另一个构建 |
||||
目录，不能在已经由 Ninja 配置的目录中切换生成器： |
||||
|
||||
```shell |
||||
cmake \ |
||||
-S "$PHPX_HOME/wasm" \ |
||||
-B "$PHPX_HOME/build/wasm32-wasip2-make" \ |
||||
-G "Unix Makefiles" \ |
||||
-DCMAKE_TOOLCHAIN_FILE="$WASI_CMAKE_TOOLCHAIN" \ |
||||
-DCMAKE_BUILD_TYPE=Release \ |
||||
-DPHPX_WASI_SDK_DIR="$PHPX_HOME/wasm/wasm32-wasip2" \ |
||||
-DCMAKE_INSTALL_PREFIX="$PHPX_HOME/wasm/wasm32-wasip2" |
||||
|
||||
make -C "$PHPX_HOME/build/wasm32-wasip2-make" -j16 |
||||
make -C "$PHPX_HOME/build/wasm32-wasip2-make" install |
||||
``` |
||||
|
||||
后续修改 PHPX 代码后，只需重复两条 `make` 命令。也可以使用生成器无关的形式： |
||||
|
||||
```shell |
||||
cmake --build "$PHPX_HOME/build/wasm32-wasip2-make" --parallel 16 |
||||
cmake --install "$PHPX_HOME/build/wasm32-wasip2-make" |
||||
``` |
||||
|
||||
Ninja 与 Make 的产物相同；Ninja 通常依赖扫描和增量构建更快，因此内部开发默认 |
||||
使用 Ninja。 |
||||
|
||||
此流程会更新： |
||||
|
||||
- `lib/libphpx.a` |
||||
- `lib/libmpdec.a` 和 `lib/libmpdec++.a`（仅相关源码变化时重编） |
||||
- `include/phpx/` 下的 PHPX 公共头文件 |
||||
- `.typephp-wasi-runtime-abi` |
||||
|
||||
它不会更新 `libphp.a`、GMP、MPFR，也不会重写完整 SDK 的 |
||||
`.typephp-wasi-sdk-abi`。因此该流程应在一个已经完整安装的 SDK 上执行。 |
||||
|
||||
### 强制重新编译 PHPX |
||||
|
||||
怀疑旧对象或 CMake 缓存不再可信时，优先使用一个新的、明确的构建目录： |
||||
|
||||
```shell |
||||
cmake \ |
||||
-S "$PHPX_HOME/wasm" \ |
||||
-B "$PHPX_HOME/build/wasm32-wasip2-clean" \ |
||||
-G Ninja \ |
||||
-DCMAKE_TOOLCHAIN_FILE="$WASI_CMAKE_TOOLCHAIN" \ |
||||
-DCMAKE_BUILD_TYPE=Release \ |
||||
-DPHPX_WASI_SDK_DIR="$PHPX_HOME/wasm/wasm32-wasip2" \ |
||||
-DCMAKE_INSTALL_PREFIX="$PHPX_HOME/wasm/wasm32-wasip2" |
||||
|
||||
cmake --build "$PHPX_HOME/build/wasm32-wasip2-clean" --parallel 16 |
||||
cmake --install "$PHPX_HOME/build/wasm32-wasip2-clean" |
||||
``` |
||||
|
||||
这样不会删除安装目录中的 `libphp.a` 和依赖库，也不会混用旧的 CMake 配置。 |
||||
|
||||
## 首次构建或重建 PHPX 数值依赖 |
||||
|
||||
以下情况使用 PHPX 的统一构建入口： |
||||
|
||||
- 首次建立 PHPX WASI 安装目录； |
||||
- GMP 或 MPFR 版本、补丁、编译参数发生变化； |
||||
- PHPX vendored mpdecimal 或其 WASI 配置发生变化； |
||||
- 需要同时检查并安装 PHPX 所有 WASI 头文件和静态库。 |
||||
|
||||
```shell |
||||
cd "$PHPX_HOME" |
||||
|
||||
./wasm/build.sh \ |
||||
--prefix "$PHPX_HOME/wasm/wasm32-wasip2" \ |
||||
--build-dir "$PHPX_HOME/build/wasm32-wasip2-sdk" \ |
||||
--jobs 16 |
||||
``` |
||||
|
||||
显式使用 `$PHPX_HOME/build/`，避免默认 `/tmp` 构建目录在重启后丢失。下载的 GMP、 |
||||
MPFR 源码与构建缓存会保留，可以在后续构建中复用。 |
||||
|
||||
该入口会构建或安装： |
||||
|
||||
- `libphpx.a` |
||||
- `libgmp.a`、`libgmpxx.a` |
||||
- `libmpfr.a` |
||||
- `libmpdec.a`、`libmpdec++.a` |
||||
- 对应头文件和 PHPX runtime ABI marker |
||||
|
||||
它要求安装前缀中已经存在 PHP/WASI 头文件；它不会构建 `libphp.a`。 |
||||
|
||||
## PHP ABI 变化：重建完整 SDK |
||||
|
||||
如果 PHP 源码、扩展集合、PHP 配置、Zend ABI 或 PHP 安装头文件发生变化，必须从 |
||||
TypePHP 编译器仓库重建完整 SDK，不能只替换 `libphpx.a`： |
||||
|
||||
```shell |
||||
cd /home/swoole/workspace/aot/compiler |
||||
|
||||
./wasm/build-sdk.sh \ |
||||
--prefix "$PHPX_HOME/wasm/wasm32-wasip2" \ |
||||
--php-source "$PWD/projects/php-8.5.9" \ |
||||
--phpx-source "$PHPX_HOME" \ |
||||
--build-dir "$PWD/build/wasm-sdk" \ |
||||
--jobs 16 |
||||
``` |
||||
|
||||
完整构建依次安装 PHP 与 PHPX 部分，并在全部产物验证成功后写入： |
||||
|
||||
```text |
||||
.typephp-wasi-sdk-abi |
||||
``` |
||||
|
||||
不要手工伪造该 marker。marker 存在只表示构建流程声明 ABI 匹配，不能修复实际混用 |
||||
的旧头文件或静态库。 |
||||
|
||||
## 产物检查 |
||||
|
||||
完成安装后检查关键文件： |
||||
|
||||
```shell |
||||
WASI_PREFIX="$PHPX_HOME/wasm/wasm32-wasip2" |
||||
|
||||
test -s "$WASI_PREFIX/lib/libphpx.a" |
||||
test -s "$WASI_PREFIX/lib/libphp.a" |
||||
test -f "$WASI_PREFIX/include/phpx/phpx.h" |
||||
test -f "$WASI_PREFIX/include/phpx/phpx_helper.h" |
||||
test -f "$WASI_PREFIX/include/phpx/typephp_helper.h" |
||||
|
||||
llvm-ar t "$WASI_PREFIX/lib/libphpx.a" | head |
||||
cat "$WASI_PREFIX/.typephp-wasi-runtime-abi" |
||||
cat "$WASI_PREFIX/.typephp-wasi-sdk-abi" |
||||
``` |
||||
|
||||
当前 marker 应分别为： |
||||
|
||||
```text |
||||
typephp-wasip2-phpx-abi-v1 |
||||
typephp-wasip2-sdk-abi-v4 |
||||
``` |
||||
|
||||
marker 版本将随 ABI 设计升级；如果代码中的预期值已经变化，应以当前构建脚本为准， |
||||
不能为了通过检测而回写旧值。 |
||||
|
||||
## TypePHP 回归验证 |
||||
|
||||
先验证 Wasmtime component： |
||||
|
||||
```shell |
||||
cd /home/swoole/workspace/aot/compiler |
||||
|
||||
PHPX_HOME="$PHPX_HOME" \ |
||||
./run-tests.php --wasm --compiler ./bin/tpc.php tests/wasm/ |
||||
``` |
||||
|
||||
再验证 Wasmtime 与 Chrome 输出一致，并覆盖并行 build/output 目录隔离： |
||||
|
||||
```shell |
||||
PHPX_HOME="$PHPX_HOME" \ |
||||
./run-tests.php -j 4 --target wasm-all --compiler ./bin/tpc.php tests/wasm/ |
||||
``` |
||||
|
||||
browser 测试还要求 `jco`、Node.js 和 Chrome 位于 `PATH`。`wasm-all` 会分别在 |
||||
Wasmtime 和 Chrome 中执行每个用例，并比较两端输出。 |
||||
|
||||
最后构建浏览器示例： |
||||
|
||||
```shell |
||||
cd examples/wasm-hello |
||||
PHPX_HOME="$PHPX_HOME" ../../bin/tpc.php project.yml |
||||
npm run build |
||||
``` |
||||
|
||||
## 常见错误 |
||||
|
||||
### `PersistentCacheSlot` 或 PHPX helper 未定义 |
||||
|
||||
生成代码使用了新 PHPX 头文件/API，但安装前缀中的 `include/phpx/` 或 |
||||
`lib/libphpx.a` 仍是旧版本。执行“日常开发：仅重建 PHPX”流程，并确保配置和安装 |
||||
使用同一个 `PHPX_WASI_SDK_DIR`/`CMAKE_INSTALL_PREFIX`。 |
||||
|
||||
### `TypePHP WASI SDK is missing or ABI-incompatible` |
||||
|
||||
检查 `PHPX_HOME` 是否指向实际 PHPX 根目录，以及完整 SDK marker、PHP/PHPX 头文件 |
||||
和静态库是否来自同一次兼容构建。PHP ABI 已变化时执行完整 SDK 重建。 |
||||
|
||||
### CMake 检测到 host 编译器 |
||||
|
||||
必须传入 WASI SDK 的 `wasi-sdk-p2.cmake`。不要直接用 PHPX 根目录的 host |
||||
`CMakeLists.txt` 构建 WASM。将 WASI SDK 加入 `PATH` 本身并不等价于加载 CMake |
||||
toolchain。如果 `CMakeCache.txt` 已记录 `/usr/bin/cc` 或 `/usr/bin/c++`，使用一个 |
||||
新的构建目录重新配置。 |
||||
|
||||
### 修改 PHPX 后 TypePHP 仍链接旧实现 |
||||
|
||||
确认 `PHPX_HOME` 的优先级高于 Composer 目录，并检查实际产物时间： |
||||
|
||||
```shell |
||||
stat "$PHPX_HOME/wasm/wasm32-wasip2/lib/libphpx.a" |
||||
``` |
||||
|
||||
TypePHP 应从同一个 `$PHPX_HOME/wasm/wasm32-wasip2` 同时读取头文件与静态库。 |
||||
Loading…
Reference in new issue