Docs/How plugins start and stop
Guide

How plugins start and stop

Every DominScript plugin has an init and a deinit hook. The init answers one question before a single statement runs: am I ready to work on this machine? This page shows what the host does with that answer, why a missing library stops a script at the start rather than in the middle, and how plugins pass data to each other without knowing each other.

Ready / Deinitsince plugin header revision 3applies to every plugin, official or yours

Where Ready fits: the three phases

A script passes three phases before and while it runs (Core concept): the parser checks the syntax, the binder checks names, types and the calls into plugins, and the runtime checks what can only be checked while running. The plugin lifecycle sits inside the second and at the end of the third phase:

1 · parserthe whole script, withits #includes: syntaxan error stops here —no plugin is loaded yet 2 · binderloads each plugin andasks its Ready();then names, types, verbssteps 1–3 of Figure 1 3 · runtimemain() runs; range andtype checks on the way;Deinit() at shutdownsteps 4–5 of Figure 1

Figure 0 — the plugin lifecycle inside the three phases: Ready at the start of the binder, Deinit at the end of the run.

So a typo in the script is reported before any plugin is touched, and a missing library before a single statement runs: each problem is caught in the earliest phase that can see it.

What happens at startup

Once the parser has accepted the whole script, the binder loads each plugin named in its plugin lines. Right after loading one — before the script’s names and types are checked, before main() — it calls the plugin’s Ready hook. The plugin answers with a constant, READY or NOT_READY, and may add a message.

domin script.domthe script has parsed; then, before anything runs: 1 · loaddlopen/LoadLibrary+ host version 2 · Ready()the plugin's check+ REQUIRE_HOST READY 2b · the line'sversion condition>= "1.2.0" 3 · bindnames, types 4 · runmain() starts NOT_READY does not fit refused — nothing runsplugin 'X' is not ready: <the plugin's message>plugin 'X' 1.1.0 is older than the script requires: 1.2.0 or newerexit 1 · with --validate: a warning instead 5 · Deinit()at shutdown a plugin built against an older header states no version -- refused at step 1; rebuild it

Figure 1 — the steps; a NOT_READY answer or a plugin that does not fit the line’s condition ends the run before step 3.

A NOT_READY answer is final: the host prints plugin 'Sdl2ImagePlugin' is not ready: followed by the plugin’s own message, and exits with status 1. No statement of the script has run, no file has been touched, nothing is half done. This is the point of the mechanism: a problem that can be found before running is found before running. The old behaviour — a plugin that loaded fine and failed on its first real call, possibly minutes into a run — is gone.

A plugin that has no Ready hook at all (one built against an older plugin header) is treated as not ready too; the message says to rebuild it.

Versions

From 0.1.1 on, versions travel both ways at startup, and each side decides only what it can know (amber in Figure 1).

The host tells the plugin its version when it loads it (step 1). A plugin that needs a newer DominScript says so in its Ready hook — one line, DOMIN_PLUGIN_REQUIRE_HOST(Message, Cap, 0, 2, 0); — and the script does not start: plugin 'X' is not ready: needs DominScript 0.2.0 or newer; this is 0.1.1. The host itself never judges whether a plugin fits it; the plugin knows what it needs.

Every plugin states its own version, and the oldest DominScript it is meant for; a script sees both with plugin.Version(i) and plugin.MinDominVersion(i). A built-in plugin carries the DominScript version.

The script may set a version condition on the plugin line (step 2b), with ==, >=, >, <= or <:

plugin "tls" >= "1.2.0";    // at least 1.2.0
plugin "tls" < "2.0.0";     // and not 2.0 or later: both must hold

The version is written "1", "1.2" or "1.2.0" (a missing part is 0). An exact version is == — a single = assigns in DominScript, and on a plugin line it is refused with that hint; pin an exact version only on purpose, as a fix release of the plugin then stops the script too. The condition is checked right after the plugin loaded and answered READY, before anything runs: a plugin that does not fit stops the script — even though its Ready said yes — with, e.g., plugin 'TlsPlugin' 1.1.0 is older than the script requires: 1.2.0 or newer (net.dom:3). If several lines name the same plugin — also inside an #included file — every condition must hold, and the message names the line of the first one that does not. With --validate it is a warning, as for a NOT_READY plugin: the script is fine, the plugin on this machine does not fit.

A plugin built against an older plugin header states no version, and is refused at load with a message that says how to rebuild it.

Adapters: the library opens in Ready

Most plugins have nothing to check and simply answer READY. The ones that matter are the adapters — plugins that wrap a third-party library at run time: SDL2, SDL2_image, FFmpeg, OpenSSL, SQLite, the MariaDB and PostgreSQL clients, cJSON. Their Ready opens the library, keeps the handle, and answers accordingly.

adapter plugine.g. sdl2_image Ready() tries, in this order: 1 the runtime/ folder2 3rd_party/ (dev tree)3 the system library foundhandle kept · answer: READY library missinganswer: NOT_READY, message:"SDL2_image not found. Install it, or copy SDL2_image.dll into …\runtime" handle SDL2_image.dlllibSDL2_image-2.0.so.0 The constant decides whetherthe script starts; the messageis the instruction for theperson reading it.

Figure 2 — an adapter’s Ready: the runtime folder first, then the system; the message names the file and the folder.

The search order is the same for every adapter and is described on the Optional libraries page. What matters here: the message the person reads is written by the plugin at the moment it knows exactly what is missing, so it can say which file and which folder.

Constants and messages are independent

The constant decides; the text informs. A plugin may answer READY and still leave a note — the ffmpeg plugin does, when it was built without decoding support: the script runs, and the host shows plugin 'FfmpegPlugin': decoding is disabled in this build … as a notice. An empty message means nothing to say, and the host stays silent.

AnswerMessageWhat the host does
READYemptynothing; the script runs
READYtextshows it as a notice; the script runs
NOT_READYtextrefuses to start, quoting the text; exit 1
NOT_READYemptyrefuses to start: “the plugin gave no reason”

domin --validate runs the same check but reports a NOT_READY plugin as a warning, anchored at the plugin line, and still says Validation OK. A script can therefore be checked — and edited in VS Code with live diagnostics — on a machine that lacks the library it will run with elsewhere.

Shutdown and Deinit

At the end of a run — a normal return from main(), a runtime error, or a Stop from the debugger — the host calls each plugin’s Deinit hook, in load order, before unloading the library. The plugin closes what Ready opened and frees what it allocated. Deinit answers with a constant and an optional message in the same way: DEINIT_OK with an empty message is silence; a message is shown as a notice; anything other than OK is reported as a warning on stderr — the script’s exit code is not changed by it, because the script itself did not fail.

How plugins hand data to each other

One plugin per library is a rule with a consequence: a PNG decoded by sdl2_image has to reach a texture owned by sdl2 or open_gl, and the two plugins must not know each other’s internals. DominScript’s answer is the one it gives everywhere: the blob is the interface. The decoder returns a pixel packet — a small fixed header (width, height, stride, format) followed by raw RGBA bytes — and anything that draws pixels accepts that packet.

sdl2_image.LoadSDL2_image decodes image.Loadno extra library pixel packet (blob)64-byte header:width, height, stridethen RGBA bytes sdl2.TextureFromPixels open_gl.UpdateTexture a file, a socket the script's own code

Figure 3 — producers on the left, consumers on the right, one packet format in the middle; a file, a socket or the script’s own code can be either (the arrows both ways). No handles cross a plugin boundary.

The same packet can be written to a file, sent over a socket, inspected by the script with a struct over the header, or produced by your own code. A plugin you write joins either side of the picture by reading or writing the same bytes.

If you write a plugin

Two functions with fixed names, PluginReady(Message, Cap) and PluginDeinit(Message, Cap), defined before the export line; the export macro wires them, and a plugin without them does not compile. A plain plugin writes one line, DOMIN_PLUGIN_ALWAYS_READY(). An adapter opens its library in Ready with the shared loader and, when that fails, lets DominRtl_NotFound write the message; if the library has a purely software init of its own (IMG_Init, mysql_library_init), that runs in Ready too, and its counterpart in Deinit. Device- or session-level initialisation (an SDL subsystem, a GL context) is not Ready’s business: only the script knows whether it needs video, audio or both, so those come up at the first verb that asks for them. The Writing an adapter plugin page shows the whole file; plugins/adapter_skeleton in the tree is the pattern with every obligation numbered.