diff options
Diffstat (limited to 'docs/dev')
| -rw-r--r-- | docs/dev/composer-runtime-bundle.md | 40 | ||||
| -rw-r--r-- | docs/dev/php-rpc.md | 13 |
2 files changed, 48 insertions, 5 deletions
diff --git a/docs/dev/composer-runtime-bundle.md b/docs/dev/composer-runtime-bundle.md new file mode 100644 index 00000000..f152897f --- /dev/null +++ b/docs/dev/composer-runtime-bundle.md @@ -0,0 +1,40 @@ +# Composer runtime bundle + +Composer plugins and scripts expect the real PHP classes in `Composer\` itself +and packages that Composer depends on to be available. Shirabe embeds the +runtime PHP sources into the binary at compile time. + +## Building and embedding the bundle + +Shirabe archives all PHP sources and resources of Composer and its dependencies, +and embeds the archived phar file into the binary. Shirabe also calculates a +hash value from all included files and puts a file that contains the hash, +`shirabe/bundle-id`. It is used for verifying the bundle. See +`crates/shirabe-php-rpc/build.rs` for details. + +### Phar signature + +A phar signature is an optional signature to verify the archive's integrity, and +must be appended to the end of the file. Shirabe's runtime bundle has no +signature because the bundle is not always at the end of the executable file. +To disable phar verification, the PHP worker is started with `-d phar.require_hash=0`. +The worker restores it to `1` right after opening the bundle, so that the rest +of the process still verifies the phars it opens. A verification result is +cached per file, and the bundle is never re-verified. + +### `__HALT_COMPILER();` tokens + +A phar file consists of 3 or 4 sections: a stub, a manifest, the actual contents +and an optional signature. The stub and the manifest are separated by +`__HALT_COMPILER();` tokens, which means that Shirabe's executable binary +must not contain the tokens except for phar's one. + +## Accessing files at runtime + +Shirabe tries to open the embedded bundle, and sets the executable as the base +path of autoloading. If loading phar fails for some reason, e.g., no phar ext, +Shirabe unpacks the archive to `<Shirabe's cache dir>/runtime/<bundle id>` once, +and uses that directory for the base path instead. + +NOTE: the environment variable `SHIRABE_COMPOSER_PHP_DIR` can override the +location for development. diff --git a/docs/dev/php-rpc.md b/docs/dev/php-rpc.md index 8418db88..b1c992d7 100644 --- a/docs/dev/php-rpc.md +++ b/docs/dev/php-rpc.md @@ -7,12 +7,15 @@ runtime. The `shirabe-php-rpc` crate spawns the system PHP as a child process and talks to it over a Unix domain socket. There is exactly one child process per Shirabe process, shared by every caller. -## Locating PHP +## Locating and spawning PHP -The existing `PhpExecutableFinder` class resolves the PHP binary. The child is started with -`-d serialize_precision=-1` so the wire codec's float formatting is pinned to the default PHP -behavior, and with `-d xdebug.mode=off` unless `COMPOSER_ALLOW_XDEBUG` asks for Xdebug to stay -(see `xdebug.md`). +The existing `PhpExecutableFinder` class resolves the PHP binary. + +The child is started with the following arguments: + +* `-d serialize_precision=-1` for stable float formatting of `serialize()`/`unserialize()` +* `-d phar.require_hash=0` (see [docs/dev/composer-runtime-bundle.md](./composer-runtime-bundle.md)) +* `-d xdebug.mode=off` (see [docs/dev/xdebug.md](./xdebug.md)) ## Transport |