The game as one executable (Linux, Windows)
bin/jumphp export:standalone <game> makes one file that runs the game on a computer with nothing installed:
no PHP, no Docker, no SDL. The player downloads it and runs it. About 23 MB (Pong, 3D Jumpball): PHP and its
libraries ~20 MB, the rest the game.
bin/jumphp export:standalone pong # games/pong/dist/standalone/pong-linux-x86_64
bin/jumphp export:standalone pong --windows # games/pong/dist/standalone/pong-windows-x86_64.exe
bin/jumphp export:standalone pong --linux --windows
What is inside
| Part | What | Where it comes from |
|---|---|---|
| PHP | StaticPHP's micro: PHP 8.5 as one executable that runs the PHAR appended to it | built once per set of extensions (below) |
| the extensions | php-sdl, sdl_image, sdl_mixer, sdl_ttf, PHP-OpenGL (with JumPHP's patch), PHP-OpenAL, gd, zip, openssl, mbstring, bcmath, sockets… | JumPHP's StaticPHP registry: docker/standalone/registry |
| the libraries | SDL2, SDL2_image (PNG/JPG/GIF/BMP), SDL2_mixer (WAV, OGG, MP3, FLAC), SDL2_ttf (FreeType inside), OpenAL Soft: static | same |
| the game | games/<game> with its vendor/ (the engine), as a PHAR; not var/, dist/, tests/, site/ |
tools/standalone.sh |
On Linux the executable needs glibc 2.17 or newer (any Linux since 2013: built with Zig's toolchain) and loads the display (X11, or XWayland), OpenGL and the sound (PulseAudio/PipeWire, ALSA) from the player's system when the game starts, as every Linux game does. On Windows nothing is needed (Windows 10 or newer).
HTTPS ($engine->http(), online play over wss://): PHP's openssl is inside; its CA certificates are the Linux
system's (Debian / Ubuntu / Arch, Fedora / openSUSE), else the game's own cacert.pem (Windows, the others), through
SSL_CERT_FILE (tools/standalone-stub.php).
The game's own php.ini settings
project.yaml php_ini: "my.setting=1\nother=2" (one line, \n between settings) adds them to the executable's php.ini
section: get_cfg_var('my.setting') reads them. A tool can rewrite that section of a copy of the executable later
(jumphp2installer writes a server's address there); to keep every offset in place (Windows), rewrite it at the same
size, from room reserved by such a setting.
When the player runs it
The first launch unpacks the game (its PHP, pictures, sounds, fonts: SDL reads real files) into the player's cache, in a folder of its own version; later launches start at once. A new version of the game unpacks beside the old one.
| Linux | Windows | |
|---|---|---|
| the game, unpacked | ~/.cache/jumphp/<id>-<build> ($XDG_CACHE_HOME) |
%LOCALAPPDATA%\JumPHP\<id>-<build> |
| saves and options | ~/.local/share/<id> ($XDG_DATA_HOME) |
%APPDATA%\<id> |
<id> is project.yaml's id, <build> a hash of the game's files. JUMPHP_STANDALONE_DIR unpacks elsewhere,
JUMPHP_VAR puts the saves elsewhere (tools/standalone-stub.php).
The micro binaries
The micro (PHP + the extensions) is the long part: ~15 minutes to build, the same for every game. It is kept in
~/.jumphp/standalone/micro-<target>-<key>.sfx, <key> being a hash of what makes it (tools/standalone-key.sh:
PHP's version, tools/standalone-extensions.txt, docker/standalone with StaticPHP's commit, the registry and
its patches). export:standalone looks for it, in order:
- in
~/.jumphp/standalone; - on JumPHP's GitHub releases:
standalone-<key>/micro-<target>.sfx(JUMPHP_STANDALONE_RELEASES: another address); - Linux: built here, in Docker (
docker/standalone: StaticPHP pinned,SPC_TARGET=native-native-gnu.2.17).JUMPHP_STANDALONE_BUILD=1builds even when a release has it. Its build files stay in~/.jumphp/standalone/spc(the next build only does what changed).
Windows' micro is built on Windows only (Visual Studio 2022): by the GitHub workflow
.github/workflows/standalone.yml (Actions > standalone > Run workflow). It builds both micros and publishes them
as the release standalone-<key>; run it after each change of docker/standalone, tools/standalone-extensions.txt
or docker/ext/php-opengl.patch. A fork of JumPHP runs it in its own repository and sets
JUMPHP_STANDALONE_RELEASES=https://github.com/<you>/<repo>/releases/download.
On Windows the extensions are built with JumPHP's config.w32 (registry/w32); Windows' OpenGL library has only
OpenGL 1.1, so PHP-OpenGL's newer functions are asked to the driver on their first call (registry/functions.php,
jumphp_wgl).
TrueAsync micro (threads: the JumPHP IDE for Linux and Windows)
A desktop app whose project.yaml says export_runtime: async (or runtime: async) gets, on Linux and Windows, another micro:
PHP 8.6 ZTS from TrueAsync's fork (tag php-8.6.0-trueasync-0.11.3) + ext/async v0.11.3 + libuv (static), with
the apps' extensions (tools/app-async-extensions.txt, FFI included). Its recipe is docker/standalone-async (the fork's
archive and ZTS in craft.yml, ext/async in its registry, loaded after docker/standalone/registry); it is part of
the key only for that list, so the other micros keep theirs. bin/jumphp app:export <app> --linux builds it like the
others (~2 min once the libraries are built, work folder ~/.jumphp/standalone/spc-app-async) and checks it has
uv_loop_init. Its php.ini adds register_argc_argv=0 (PHP 8.6 warns in each new thread without it; $argv stays).
Two fixes in its registry (src/Extension/async.php): StaticPHP builds the packages of an extra registry only
while it loads that registry's PHP classes (so the class exists even for one package), and PHP 8.6's poll API is told
there is no epoll_pwait2() (Zig's headers declare it, glibc 2.17 has none: the link failed).
Windows (MSVC, same recipe): built by the workflow standalone with extensions=tools/app-async-extensions.txt (or by hand on
a Windows machine with Visual Studio 2022: the same craft.yml, both registries), published in the same release standalone-<key>
as micro-windows-x86_64.sfx. The registry's src/Extension/async.php makes ext/async's config.w32 find StaticPHP's libuv
(uv.h straight in buildroot/include, its sources include libuv/uv.h on Windows) and links the system libraries libuv needs
(synchronization.lib for libuv >= 1.53, Iphlpapi, Psapi, Userenv, Dbghelp...). StaticPHP splits SPC_REGISTRIES on ::
on Windows the paths are relative to its folder (..\jumphp\docker\standalone\registry\spc.registry.yml:..\jumphp\docker\standalone-async\...),
a drive letter would cut them. The workflow runs the micro with a script that starts an Async\ThreadPool before publishing.
tools/standalone.sh recognises the async micro by the string Libuv Reactor (a Windows PE has no symbol names: no uv_loop_init).
One TrueAsync difference on Windows: once its scheduler has run (a thread pool's first job), stream_socket_accept($server, 0)
always answers false, even with a client waiting. The IDE's servers polled every frame (LocalLink, the page's loopback, MCP, the
debugger, Remote) go through JumPHP\Ide\Net\Accept::now(): stream_select() first, then accept with a short timeout.
macOS keeps the PHP 8.5 micro for now (the app falls back to helper processes): the same craft on both Macs (the epoll_pwait2
patch changes nothing there: macOS uses kqueue), then the same thread check; macOS runners exist only on GitHub (or an own Mac runner).
Limits
- x86_64 only (no ARM, no macOS yet: StaticPHP can, the registry has no macOS build of SDL yet).
- The executable is not signed: Windows SmartScreen asks "Run anyway" the first time; on Linux,
chmod +xafter a download. - A game that runs other programs, or reads files outside its folder, does it on the player's computer.
Le cache des micros : ne jamais copier un fichier d'une clé à l'autre
~/.jumphp/standalone/micro-<système>-<clé>.sfx : la clé est le hash de tools/standalone-key.sh (version de PHP, liste d'extensions, StaticPHP, docker/standalone,
patchs). Jeux et applications graphiques : tools/standalone-extensions.txt (SDL, OpenGL, OpenAL) ; applications de bureau Tauri : tools/app-extensions.txt (FFI, sans SDL) :
deux clés, deux fichiers. Copier ou renommer un micro sous une autre clé « pour éviter de reconstruire » donne des exécutables qui plantent chez les joueurs
(Call to undefined function SDL_Init()), c'est arrivé le 6 novembre 2026. tools/standalone.sh vérifie maintenant que le micro contient chaque extension de sa liste
(symboles SDL_CreateWindow, IMG_Load, Mix_OpenAudio, TTF_OpenFont, glGenBuffers, alcOpenDevice) : un mauvais fichier est retiré du cache et l'export s'arrête.
La clé a changé ? Reconstruire : Linux JUMPHP_STANDALONE_BUILD=1 bin/jumphp export:standalone <id> --linux, Windows / macOS par le workflow standalone.
Avant de publier un exécutable : le lancer (SDL_VIDEODRIVER=dummy SDL_RENDER_DRIVER=software SDL_AUDIODRIVER=dummy timeout 10 ./fichier).