From cfcb9a459be6766c4d666f693bdcd338dc7f0c91 Mon Sep 17 00:00:00 2001 From: soyuka Date: Mon, 25 Sep 2023 18:56:21 +0200 Subject: [PATCH] docs --- Dockerfile | 1 + README.md | 118 +++++++++++++++++++++++++++-------------------------- 2 files changed, 61 insertions(+), 58 deletions(-) diff --git a/Dockerfile b/Dockerfile index 9c10c0eb2..bfc4c0d1e 100644 --- a/Dockerfile +++ b/Dockerfile @@ -50,6 +50,7 @@ FROM php_src AS php-wasm ARG WASM_ENVIRONMENT=web ARG ASSERTIONS=0 ARG OPTIMIZE=-O2 +# TODO: find a way to keep this, it can't be empty if defined... # ARG PRE_JS= ARG INITIAL_MEMORY=256mb COPY --from=libxml /src/libxml2/build/ /src/usr diff --git a/README.md b/README.md index 7178c7968..2d5969195 100644 --- a/README.md +++ b/README.md @@ -3,32 +3,70 @@ Project based on https://github.com/seanmorris/php-wasm which was forked from https://github.com/oraoto/pib I fixed some inconsistencies in the Makefile and removed non-essential things. This fork: - - does build sqlite3 - - does build libxml - - has no javascript abstraction + - builds sqlite3 + - builds libxml + - no javascript abstraction + - exposes FS and builds with [IDBFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#FS.syncfs) - does not build https://github.com/seanmorris/vrzno which allows javascript access from PHP (TODO add this back opt-in cause it's really cool) - does not add preloaded data, having this separatly from php-wasm builds allows for more flexibility (see [preload data section](#preload-data)) - - exposes FS and builds with [IDBFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#FS.syncfs) - - reduces memory to 256mb - -## Usage - -Some build ## Build ``` docker build . -t php-wasm +# create a temporary container docker create --name=php-wasm php-wasm +# to copy builded files docker cp php-wasm:/build/php-web.wasm ./build docker cp php-wasm:/build/php-web.mjs ./build/php-web.mjs ``` Builded files will be located in `build/php-web.js` and `build/php-web.wasm`. +The module we export in this image is called `createPhpModule`. + +### Build arguments + +Use this as template to build PHP with emscripten. At build these arguments are available: + +``` +LIBXML2_TAG=v2.9.10 +PHP_BRANCH=PHP-8.2.9 +``` + +The next args are used for [emcc options](https://github.com/soyuka/php-wasm/blob/513f284e1ba8f26d66e08a97291f484b3dd7de1b/Dockerfile#L108) `-sOPTION` +see [settings.js](https://github.com/emscripten-core/emscripten/blob/9bdb310b89472a0f4d64f36e4a79273d8dc7fa98/src/settings.js#L633). +In fact it's even easier for you to set them directly in [the Dockerfile](https://github.com/soyuka/php-wasm/blob/513f284e1ba8f26d66e08a97291f484b3dd7de1b/Dockerfile#L108). + +``` +WASM_ENVIRONMENT=web +ASSERTIONS=0 +OPTIMIZE=-O2 +INITIAL_MEMORY=256mb +``` + +### Preload data + +My prefered option is to use the [`file_packager`](https://github.com/emscripten-core/emscripten/blob/9bdb310b89472a0f4d64f36e4a79273d8dc7fa98/tools/file_packager) tool to build the preloaded data in a `php-web.data.js` (and `php-web.data` file). These are preloaded into IDBFS. That can be changed changing the `-lidbfs.js` argument to `emcc`. + +This will preload `SOME_DIR` into the `/src` directory inside the WASM filesystem: + +``` +mkdir -p php-wasm +docker run -v SOME_DIR:/src -v $(pwd)/php-wasm:/dist -w /dist soyuka/php-wasm:8.2.9 python3 /emsdk/upstream/emscripten/tools/file_packager.py php-web.data --use-preload-cache --lz4 --preload "/src" --js-output=php-web.data.js --no-node --exclude '*/.*' --export-name=createPhpModule +ls php-wasm/ +``` + +Note that the `php-web.data.js` must be either used as `PRE_JS` argument to emcc or it needs to be included inside the `php-web.js`: + +``` +sed '/--pre-js/r php-wasm/php-web.data.js' php-wasm/php-web.mjs > this-has-preloaded-data-php-web.mjs +``` + +We match the `export-name` with the emcc `EXPORT_NAME` option. Use excludes to downsize the preloaded data weight. ## Usage -To execute some php, call `pib_exec` using [`ccall`](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html#interacting-with-code-ccall-cwrap), for example: +To execute some php, call `phpw_exec` using [`ccall`](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html#interacting-with-code-ccall-cwrap), for example: ```javascript const phpBinary = require('build/php-web'); @@ -46,7 +84,7 @@ return phpBinary({ }) .then(({ccall, FS}) => { const phpVersion = ccall( - 'pib_exec' + 'phpw_exec' , 'string' , ['string'] , [`phpversion();`] @@ -54,61 +92,25 @@ return phpBinary({ }) ``` -The builded PHP WASM version exposes these functions that will help you execute PHP: `_pib_init`, `_pib_destroy`, `_pib_run`, `_pib_exec`, `_pib_refresh`. The source code behind them is located under `source/pib_eval.c` and the exported function are declared in the final build command (see `Makefile`). - -Thanks to [@seanmorris](https://github.com/seanmorris/php-wasm) you can also use persistent calls to keep things in memory by using: +### API ```javascript -let retVal = ccall( - 'pib_init' - , NUM - , [STR] - , [] -); - -console.log('PHP initialized', retVal) - -function runCode(phpCode) { - ccall( - 'pib_run' - , NUM - , [STR] - , [`?>${phpCode}`] - ) -} - -// Remove things kept in-memory -function refresh() { - ccall( - 'pib_refresh' - , NUM - , [] - , [] - ); -} +phpw_exec(string code): string +phpw_run(string code): void +phpw(string filePath): void ``` -More examples on the code usage are available on [@seanmorris's repository](https://github.com/seanmorris/php-wasm/tree/master/docs-source) or on [APIPlatform By Examples](). - -## Preload data +### Example calls: -You can build preloaded assets (`PRELOAD_ASSETS=/data`) using `make preload-data`. Then you'll need to add the `php-web.data.js` to the actual `php-web.js` file. -This step on API Platform By Examples is done with the following Makefile using the original file as `php-web.ori.js`: - -```make -UID=1000 -API_PLATFORM_DIR=examples -DOCKER_RUN=docker run --rm -e ENVIRONMENT=web -v $(CURDIR):/src -v $(CURDIR)/../${API_PLATFORM_DIR}:/src/${API_PLATFORM_DIR} -w /src soyuka/php-emscripten-builder:latest - -preload: - ${DOCKER_RUN} python3 /emsdk/upstream/emscripten/tools/file_packager.py ./public/php-web.data --preload "/src/${API_PLATFORM_DIR}" --js-output=./php-wasm/php-web.data.js - ${DOCKER_RUN} chown ${UID} ./php-wasm/php-web.data.js - sed -e '/function(Module) {/r./php-wasm/php-web.data.js' php-wasm/php-web.ori.js > php-wasm/php-web.js - rmdir ${API_PLATFORM_DIR} +```javascript +const STR = 'string'; +ccall("phpw", null, [STR], ["public/index.php"]); +console.log(ccall("phpw_exec", STR, [STR], ["phpversion();"]); ``` +[More about how to call exposed functions](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html?highlight=call#interacting-with-code-ccall-cwrap) + ## TODO -- cache libxml and sqlite to speed up builds - add opt-in / opt-out sqlite libxml vrzno and mb more