Modules
A module starts with a Recoil [...] header that declares its type,
id, imports, and exports. Imports may pull specific names from a module:
Recoil [
Type: module
Module: tests/math-module-demo
Imports: [
std/math/core [abs-value clamp-value]
]
Exports: []
]
print abs-value [i32!] -7
print clamp-value [i32!] 10 0 5
Some modules (extensions) are called through a namespace prefix instead of importing individual names — see Extensions.
The package manager
Recoil ships a dependency workflow driven through the same CLI. A workspace
has a recoil.project manifest and a generated
recoil.lock.reb lockfile.
| Command | What it does |
|---|---|
init | create a minimal recoil.project in the workspace |
install <capability> | add a first-party capability package and its provider for the current platform (e.g. install tls for TLS/HTTPS, install sqlite); --target picks a target-specific provider, e.g. install raylib --target wasm32-emscripten |
fetch | resolve dependencies, populate the source store, write the lockfile |
compile -o <out> <entry.rcl> / run <entry.rcl> | build or run an entry point using recoil.lock.reb, resolving it first if missing |
update | refresh dependency refs / archives |
doctor | validate the workspace without fetching or compiling |
repair | rebuild missing source-store entries referenced by the lockfile |
toolchain fetch zig | download the Zig toolchain for use as an alternate C compiler (--cc zig) |
r3 -s recoil.r3 init
r3 -s recoil.r3 fetch
r3 -s recoil.r3 run app.rcl
On success, package commands print exactly one Rebol value (tagged
Recoil-Init, Recoil-Fetch, …) that can be loaded
directly for scripting. Failures use the standard CLI diagnostics.
Exporting functions
Mark functions with #export in the spec to expose them from a
generated library. An exported init function is declared in the header but is not
called automatically; the host calls it once before using the library.
add: func [
"Add two signed 32-bit integers."
#export
a [i32!] "Left operand."
b [i32!] "Right operand."
return: [i32!] "The sum."
] [return a + b]
sub: func [
"Subtract the second integer from the first."
#export
a [i32!] "The integer to subtract from."
b [i32!] "The integer to subtract."
return: [i32!] "The difference."
] [return a - b]
init: func [
"Announce that the library loaded."
#export
return: [none!] "Nothing."
] [print "Library loaded!"]
Building libraries
Compile a source file to a shared or static library:
r3 -s recoil.r3 --lib mylib.rcl # shared, name from source
r3 -s recoil.r3 --lib mylib.rcl --name mylib # shared, custom name
r3 -s recoil.r3 --lib mylib.rcl --static # static
Given mylib.rcl, the compiler produces the C source
mylib.c, a header mylib.h with the exported
declarations, and the library itself (.so for shared, .a for static;
.dll/.lib with the MSVC toolchain).
Using it from C
// main.c
#include "mylib.h"
int main() {
init(); // call the library's init once, if it defines one
int32_t r = add(1, 2);
printf("%d\n", r);
return 0;
}
gcc -o myprogram main.c -L. -lmylib # shared
gcc -o myprogram main.c libmylib.a # static
Extensions
Extensions under the ext/ tree wrap C libraries behind a Recoil
module. They are imported by module id, with the functions you want listed in the
import, and called by their bare names.
For example, ext/sqlite:
Recoil [
Title: "sqlite demo"
Imports: [
ext/sqlite [
db-open db-close prepare-stmt bind-int stmt-step row-code
column-int stmt-finalize
]
]
]
db: db-open ":memory:"
stmt: prepare-stmt db "select ? + ?"
bind-int stmt 1 10
bind-int stmt 2 20
rc: stmt-step stmt
if rc = row-code [
v: column-int stmt 0
print v ; 30
]
stmt-finalize stmt
db-close db
Writing your own extension (foreign declarations, type mapping, refinement patterns, one-shot vs handle wrappers, build/link choices, and a test pattern) is covered in the repository's extension authoring guide.
GUI, Draw & plug-ins
recoil-gui is a backend-neutral window, drawing and input API. A bare install
picks the platform default (Cocoa on macOS, GTK on Linux, Win32/GDI+ on Windows), and a
variant such as gui/raylib overrides it where the provider supports the target.
Application code imports gui/gui and never names the provider.
r3 -s recoil.r3 install gui
r3 -s recoil.r3 install gui/raylib
Two dialects sit on top. VID builds a face tree from a pure-data block, with
flow words such as across, below and return, and actors
such as on-click. Draw lowers a block of graphics commands at
compile time into calls on the backend, taking points as fpair! values
from std/geometry so a size and an offset cannot be swapped. Embedded,
host-parented contexts (Win32 and Pugl on macOS and Linux/X11) let the same code run inside
a plug-in editor.
The Pokuston audio plug-ins (Kaprálová, Loos, Mach) are built from Recoil as CLAP, VST3 and AUv2 through one shared driver in the separate Pokuston repository, which owns their build and packaging instructions. See the Recoil docs for GUI backends, VID, and Draw.