RageKit turns a PHP app with .rk templates into a native executable: TypePHP compiles the PHP
to machine code, Slint draws the UI. This page explains where everything lives and how the pieces
fit together.
RageKit contains code that ends up inside your app and code that only runs on your machine while you build or develop. Keeping them apart is the main rule of the layout.
| Ends up in your app | Runs only on your machine |
|---|---|
core PHP (src/*.php) |
the ragekit command (src/Cli/) |
the Slint backend's PHP (src/Slint/*.php) |
the dev runtime (src/Slint/Dev/) |
the Slint bridge + host (native/slint/bridge, native/slint/host) |
the dev shell (native/slint/devshell) |
| kits' Slint code and enabled modules | tests, demos |
TypePHP only compiles the files a backend lists one by one in its backend.yml (sources:), so
nothing from the right-hand column can end up in an app by accident.
src/ PHP only
native/ RageKit's own C and C++ only
kits/ UI kits: what core elements look like (Slint)
modules/ native modules: device and OS features (audio, http, crypto, keyring, notifications, tray, …)
demo/ example apps
tests/ PHPUnit tests (+ small C++ test programs in tests/fixtures)
toolchain/ the TypePHP and Slint versions RageKit builds with (toolchain.yml) + TypePHP patches
docs/ user guides (getting started, toolchain, templates, kits, modules, dev mode)
bin/ the ragekit command's entry point
vendor/ Composer dependencies (not in git)
src/
App.php, Backend.php, Component.php, Screen.php, the app model every backend implements: the
Window.php, Navigator.php, Store.php, RootStore.php app class, windows and their stacks of
screens, app-wide state
Events.php, Modules.php, ModuleUnavailable.php module events and availability
Timer.php Timer::every()/after() (ticks are events)
Links.php app links: Links::register() (App::linkOpened())
LocalTime.php times in the computer's timezone
Slint/
backend.yml what the Slint backend adds to an app's build (sources, libraries,
options, dev shell)
backend.php ragekit_backend(): which backend App uses
SlintBackend.php windows, event dispatch ┐ compiled into apps
SlintWindow.php one window: values in, actions out ┘
Dev/ dev runtime: \slint_* over a loopback connection to the dev shell,
bindings read from screens.json, state snapshots (plain PHP, never
compiled)
Cli/ the ragekit command (never compiled)
src/Cli/ is grouped by job:
src/Cli/
Application.php boots symfony/console; Command/ holds build, run, dev
Project/ project.yml, backend.yml, merging them into TypePHP's config, paths
Toolchain/ TypePHP, the C++ compiler (Gcc / Msvc), running processes, NativeBuild
for compiling C++ only when its inputs changed
Build/ the build pipeline: one class per step in Build/Steps
Package/ ragekit package: the build's runtime files as a .tar.gz or .deb in dist/
Templates/ .rk parser, reading the app's classes (introspect.php), the
ViewGenerator interface backends implement
Rageblade/ the Blade-style parts of .rk files: @foreach/@if (Directives) and the
{{ expression }} parser
Kits/ kit.yml (the element contract: ElementSpec, PropSpec), finding kits,
ragekit eject
Make/ ragekit make:* — Maker writes a class (+ template) from stubs in
Make/stubs (or the app's stubs/), StoreRegistrar adds a store to the
root store
Slint/ turning templates into Slint + the C++/PHP glue that connects them:
ElementDispatcher hands each element to its compiler in Slint/Elements/
(one class per construct, sharing a CompileContext); fixed shapes of
generated Slint, C++ glue and PHP binder are stubs in Slint/stubs/
(rendered by Cli/Stub)
Modules/ module.yml and the glue generated for modules (from Modules/stubs/)
Fetch/ downloading what kits and modules declare under fetch:
Setup/ ragekit setup (installing the pinned toolchain) and ragekit doctor
Dev/ ragekit dev: watching files, the dev shell, reloads
native/
include/
ragekit_module.h what a module's library includes: export macro, event callback type
slint/
bridge/ libragekit_slint (C++20): everything that touches Slint or the OS —
windows, events, loading module libraries at runtime. Built by
ragekit with g++/cl next to the executable.
host/ the PHPX host (C++17) + slint.stub.php: the \slint_* functions PHP
calls. Compiled into the app by TypePHP (also in Nano builds).
devshell/ ragekit-devshell (C++20): runs Slint's interpreter and the app's PHP
for `ragekit dev`. It talks to PHP and to `ragekit` over 127.0.0.1
(loopback.cc); starting PHP and loading modules differ per OS
(platform_posix.cc, platform_win32.cc).
window/ what Slint's C++ API lacks for frameless windows (layouts): moving and
resizing (Windows: the OS's loop; X11: the app follows the pointer) and
the floating look. window.h + one file per platform
(window_x11.cc, window_win32.cc), compiled into both bridge and dev shell.
Platform-specific code follows one pattern: a shared header plus one file per platform, each
wrapped whole in #if (the build compiles whole folders), like modules/http/native/transfer_*.cc.
The split between bridge (C++20) and host (C++17) exists because TypePHP's Nano builds require
C++17 while Slint requires C++20; the two talk through the plain C functions in
bridge/ragekit_slint.h.
A kit maps RageKit's core elements (Button, Slider, Tabs, …) to Slint components and can add
its own elements. Each kit is self-contained:
kits/<name>/
kit.yml elements and their attributes (the core element contract is the same
for every kit, so a template builds with any of them)
<name>.slint the Slint components
library/ third-party Slint code it needs (fetched, not in git)
RageKit ships material (Slint's Material 3 library) and shadcn. Third-party code a kit or module
needs is declared under fetch: in its kit.yml / module.yml, either a file (URL + sha256) or a
folder from a pinned git commit, and ragekit build / ragekit dev fetch it into the package the
first time. Apps can have their own kits
in <project>/kits/, and Composer packages can provide kits (extra.ragekit.kit).
A module gives PHP access to something native (sound, later network, files, …). It is loaded at
runtime, never linked: an app runs without a module's library, and RageKit\Modules::available()
tells whether it's there.
modules/<name>/
module.yml the native functions and their types (int, float, bool, string)
src/ the PHP API apps use (e.g. RageKit\Audio\Sound), compiled into apps
native/ the library's C++ (C++17)
native/third_party/ third-party code it needs (fetched, not in git)
From module.yml RageKit generates all glue: the C header the library implements, an entry for
calling functions by name (used by the dev shell), the PHP functions and their host for release
builds. Apps enable modules with ragekit: { modules: [audio] }; their own modules can live in
<project>/modules/, and Composer packages can provide modules (extra.ragekit.module).
Events (e.g. "a sound finished") travel from the module's thread through the bridge to PHP on the
UI thread (RageKit\Events), and the windows refresh afterwards, like after a click.
myapp/
project.yml TypePHP settings + ragekit: { backend, kit, modules, assets, nano, … }
main.php main(): runs the app class (src/…App.php: first screen, store, start())
src/ Screens and components (PHP)
templates/ their .rk templates (each component says where in template())
assets/ files read at runtime (copied next to the executable with `assets:`)
kits/, modules/ the app's own kits and modules (optional)
build/ build output (not in git): build/slint for releases, build/dev for dev mode
A build needs TypePHP (compiles PHP to C++ and machine code) and Slint's C++ package. RageKit pins
exact versions in toolchain/toolchain.yml: TypePHP as a git commit plus its composer.lock
and our patch files (toolchain/typephp/patches/, fixes not yet upstream), Slint as release
downloads with checksums. ragekit setup installs them into a toolchain folder
(Setup\ToolchainDir: RAGEKIT_TOOLCHAIN, else the nearest .ragekit/ from the app's folder
upward, else a per-user folder named after the pins' hash, e.g.
~/.local/share/ragekit/toolchains/<id>/, shared by all apps on that RageKit version) and writes
a marker of what it installed. Builds find the folder the same way and stop with "run ragekit setup again" when the marker doesn't match RageKit's pins,
so updating RageKit can never build with a stale or unpatched TypePHP. TYPEPHP_HOME and
SLINT_HOME override the installed versions (used as is). ragekit doctor checks all of it,
plus PHP, the C++ compiler and the tools setup needs.
- Read
project.ymland the backend'sbackend.yml, merge them into a TypePHP config. - Fetch what kits and modules declare under
fetch:(only the first time). - Compile the
.rktemplates to Slint and generate the code that connects them to PHP. - Generate the glue for enabled modules.
- Build the native libraries: the Slint bridge (linked) and module libraries (not linked).
- Linux, normal builds: prepare the host PHP's libphp for TypePHP (
Toolchain\HostPhp). - Copy runtime files and assets next to the executable.
- Run TypePHP: the app's PHP, the core and the host become one executable.
ragekit dev skips steps 5–8 for the app: it runs the PHP on plain php inside the prebuilt dev
shell, which reloads templates in place and restarts only PHP when PHP changes.