Chapter 25
Four Ways to Run a Program
The same binary will run the same Raku source four different ways, and the choice is not academic: one mode is for editing and re-running, one for handing someone a program that needs no interpreter installed, one for cutting start-up time, one for throughput. They share the entire front end and diverge completely after it.
One front end, seven back ends. This chapter takes one small program through the four that share the runtime library — interpret, --bundle, --aot and --exe — and shows exactly what each produces. The other three give up the shared-runtime principle everything here rests on, because their targets have no room for it: --target=js, which has its own chapter, and the two board targets, --target=arduino and --target=microbit, which have a section at the end of this one.
# demo.raku
sub square($n) { $n * $n }
my $total = 0;
for 1..5 { $total += square($_) }
say $total;
The CLI in main.cpp picks a mode from the flags and calls that mode's driver.
Mode 1 — interpret
demo.raku ─► Lexer ─► Parser ─► Program (AST)
─► Interpreter.run(Program) ─► walk the tree, node by node
main reads the source and calls rakuppRunBigStack, which lexes, parses, and hands the Program to Interpreter::run. Evaluation is the recursive eval/exec of Chapter 13: the for loop iterates and re-executes its body block, square($_) looks the sub up in the environment chain and calls it, $total += … re-dispatches through applyArith.
Nothing is compiled ahead of the run — the same AST nodes are re-interpreted on every iteration, with two exceptions that leave the tree in charge. A sub or a loop over plain Ints, Nums and Strs is run as a kernel on machine values (src/IntKernel.cpp; RAKUPP_NO_KERNELS=1 turns that off), and --jit and --cnp compile a loop that proves hot while the program runs, which is Chapter 44. Startup is 4.4 ms for a one-line say (the benchmark sitting of 2026-10-21, v5.5.0, on an Apple M4). This is the only mode that runs every construct in the language, so it is the one the language is developed against.
Mode 2 — --bundle
demo.raku ─► (embedded verbatim as bytes) ─► generated stub.cpp
─► cc stub.cpp librakupp_rt.a ─► ./demo
The driver does not depend on parsing the program at build time. It looks — for the declaration check, and for the modules to embed — but a source that does not parse is bundled all the same. It emits a small stub that embeds the source as a byte array and calls the runtime:
static const unsigned char SRC[] = { 35,32,100,101,… };
int main(int argc, char** argv) {
std::string src(reinterpret_cast<const char*>(SRC), SRC_LEN);
/* … collect argv … */
return rakupp::rakuppRunBigStack(src, args, "demo.raku", exe, {});
}
then compiles it and links against the runtime. The result is standalone — no rakupp needed on the target machine — but at run time it still lexes, parses and tree-walks. It is the interpreter in a box. The win is distribution; start-up and run time equal interpreting.
Mode 3 — --aot
demo.raku ─► Lexer ─► Parser ─► Program ← parsed at BUILD time
─► serializeAst(Program) ─► bytes ─► C++ that carries them
─► cc gen.cpp librakupp_rt.a ─► ./demo
This is genuine ahead-of-time work: the program is parsed at build time, so parse errors are reported then rather than at run time, and the tree travels as bytes:
// Generated by `rakupp --aot`. The Raku program was parsed ahead of time;
// its AST travels below as bytes and is rebuilt at startup, so there is no
// lexing or parsing at run time.
static const unsigned char kAst[] = { 82,75,65,83,62, /* … */ };
int main(int argc, char** argv) {
Program prog;
deserializeAst(std::string(reinterpret_cast<const char*>(kAst),
sizeof kAst), prog);
/* … collect argv … */
return rakupp::rakuppRunProgramBigStack(prog, args, "demo.raku", exe, "");
}
RKAS and a format version — 62 at the time of writing — then the tree. The generated main rebuilds the identical Program and hands it to rakuppRunProgram, which interprets it with no lexing or parsing at run time. It is the serializer of Chapter 30, with a C++ wrapper around it: one format, used by the precomp cache and by this mode alike.
It was not always so, and the reason it changed is the better half of the story. AstEmit used to emit one small builder function per AST node, listing each node type's fields by hand — and that was quietly lossy. A field nobody remembered to list simply did not survive, so my Int(Str) $n = "42" compiled into a binary that threw a type error, because VarExpr::declCoerce was not among the fields it emitted. Node::line, Stmt::label, most of Param and nearly all of SubDecl went the same way, which is how a compiled program's diagnostics lost their line numbers. The serializer cannot have that bug: its writer and its reader are one visitor per node type instantiated twice, so a field cannot be saved but not restored, because both directions are the same source line.
Because the interpreter runs the embedded tree, --aot handles the whole language, grammars included. If AstEmit ever meets a node it cannot rebuild, it throws AstEmitError and the driver falls back to mode 2.
The trade-offs moved with the mechanism, and mostly in --aot's favour. The generated file for the four-line demo.raku above is 2,499 bytes — less than a third of what --exe produces for the same program, where the old per-node emitter would have run to tens of thousands of lines. Building it is the slowest of the three, though: 1.2 s against --bundle's 0.4 and --exe's 0.9 (best of four on an Apple M4, v5.6.3, 2026-11-10). The bundle's stub includes no runtime header, --exe reads the header precompiled (below), and the --aot file parses it in full. And the edge is no longer only parse errors: a 2,001-line program starts in 4.5 ms under --aot against 8.2 under --bundle (measured at v3.25, in September 2026), because the bundled binary still lexes and parses its own source on every run and this one does not.
Mode 4 — --exe
demo.raku ─► Lexer ─► Parser ─► Program
─► Codegen.transpileToCpp(Program) ─► C++ source
─► cc gen.cpp librakupp_rt.a ─► ./demo (no interpreter inside)
Codegen walks the tree and emits C++ that implements the program directly — native control flow, native calls — calling the runtime only for Value operations. For demo.raku, abridged:
#include "Interpreter.h"
using namespace rakupp;
static Interpreter& __rakupp_RT() { static Interpreter rt; return rt; }
#define RT __rakupp_RT()
static Value v_stotal = Value::any(); // top-level `my $total`
static const BuiltinFn* __bfp0 = nullptr; // say — resolved once at startup
static int64_t k_u_square(int64_t p0, __KR& __r) { // the int64 twin
/* … recursion-depth guard … */
return __kMul(p0, p0, __r);
}
static Value u_square(ValueList __a) {
/* … a plain Int argument: answer from k_u_square unless it bails … */
Value v_sn = rtBoxedItem(rtPos(__a, 0));
return applyArithValue("*", v_sn, v_sn);
}
static void __rakupp_register() { __bfp0 = RT.builtinPtr("say"); }
static int __rakupp_main_body(void* __ctxp) {
/* … argv, program name … */
__rakupp_register();
try {
v_stotal = rtNilToAny(Value::integer(0LL));
{ // for 1..5 — a real C++ loop
Value __rv2 = rtRangeVal(Value::integer(1LL),
Value::integer(5LL), false, false);
/* … __lo5 and __hi6 read from the Range … */
for (long long __i7 = __lo5; __i7 <= __hi6; __i7++) {
Value v__t1 = Value::integer(__i7); // $_
try { applyArithInto("+", v_stotal,
u_square(ValueList{v__t1})); }
catch (const NextEx& __e) { /* … */ continue; }
catch (const LastEx& __e) { /* … */ break; }
}
}
rtSinkStmt(RT, rtCallB(RT, __bfp0, "say", ValueList{v_stotal}));
} catch (const RakuError& e) {
std::cerr << e.message << "\n"; __rakupp_exit = 1;
}
return RT.testRunEnd(__rakupp_exit, __rakupp_exited);
}
int main(int argc, char** argv) {
std::pair<int, char**> __ctx{argc, argv};
return rakupp::rakuppMainOnBigStack(&__rakupp_main_body, &__ctx);
}
The loop is a native for, the sub call is a direct C++ call, and only value semantics dip into the runtime. k_u_square is new since this chapter was first written: a sub that only does integer arithmetic on its parameters gets a second body over int64_t, tried first and abandoned on anything it cannot answer exactly (Chapter 27). This is the only mode whose runtime performance differs, and the only one the optimizer touches.
The C++ compile is the slow part of --exe, and most of it is not the program. Every generated file starts with #include "Interpreter.h", about 82,000 lines with the standard library behind it. The first --exe compile on a machine saves that parse as a precompiled header under ~/.cache/rakupp/pch and every later one loads it: 1.10 s down to 0.77 for a say 42 with Apple Clang on an M3, by the guide's measurement. The header is keyed by the rakupp build, the compiler's --version, the flags and the target, the three most recently used are kept, and RAKUPP_NO_PCH=1 compiles without one. MSVC and Windows builds do not use it.
Comparing them
| parse when | runs how | whole language | speed | |
|---|---|---|---|---|
| interpret | run time | tree walk | yes | baseline |
--bundle | run time | tree walk | yes | baseline |
--aot | build time | tree walk | yes | baseline |
--exe | build time | native C++ | falls back | 0.4× to 2.2× the interpreter's |
The important row is the last column of the third row: three of the four modes run at the same speed, because three of them are the same tree walk. Bundling and AOT buy distribution and build-time error reporting, not throughput.
The last row's range is the eighteen benchmark kernels at v5.5.0 (2026-10-21). It used to read "several times faster on hot loops", and it stopped being true from the other side: the interpreter now runs those hot loops as kernels, so fib gains 2.2× from compiling and loopsum 1.5×, and three kernels whose loops the interpreter's kernels cover and the generated code's lanes do not are slower compiled.
The fallback that makes --exe total
Codegen throws on any construct it cannot transpile:
// src/Codegen.h
struct CodegenError {
std::string msg; bool routineWide = false; int line = 0;
};
mainly symbolic references (::($name), which name a variable that a native local does not have at run time), state variables, a where or :D constraint on a routine parameter, roles and packages, a CATCH inside a routine or a try block, and a handful of NativeCall shapes that need copy-back the generated call site cannot express. Grammars left that list: a grammar is registered with the runtime at startup, as a class is. The driver catches the error and transparently bundles the whole program instead:
note: a symbolic reference (::("…")) — native locals have no runtime names —
not yet natively compiled; bundling the program with the interpreter instead,
its routines compiled natively where they can be.
--exe: 1 of 2 program routines compiled natively
The last line is the part that changed. A bundled fallback used to be the interpreter and nothing else. Now each of the program's routines that the generator can compile still gets a native body, attached to the tree the binary parses at startup; only the routine holding the refused construct, and the mainline, are walked. The mechanism is the one that compiles module routines, described below.
So --exe never refuses a program. It native-compiles what it can and bundles the rest, always producing a correct binary. The user is told which happened, and --exe-info reads the mode back from the binary: native or bundle.
What every mode shares
One runtime. Everything except the CLI is in librakupp_rt.a — plus four feature archives a compiled binary may leave out, which is Chapter 29. A feature implemented once behaves identically in all four modes. Value is the shared currency, callBuiltin/callCallable the shared calling convention, rtIndexRef/rtAttrRef/rtArrayVal the shared container operations, and callNative the shared FFI.
One big stack. Every entry point runs the program body on a thread with a large reserved stack, including a compiled binary's main, so the recursion budget matches across modes.
One compile-time gate. Before any mode does its own work, the parsed unit is asked whether every variable in it is declared, and a program that fails is refused rather than started — so a typo on line 90 is not discovered after 89 lines of output, and --exe reports it itself instead of emitting C++ that names an identifier it never declared. --aot and --bundle inherit it at build time; a --bundle binary, which parses its embedded source at run time, is checked again then, since that is the interpreter path. The pass, and why it is careful to the point of standing down, is in Chapter 39.
Modules are loaded by the interpreter. Codegen emits a call to Interpreter::rtUse, a thin mirror of the interpreter's use handling, which calls the same loadModule. A compiled binary still loads its modules as trees (Chapter 33): every declaration, export, role and signature binding keeps the one implementation it has. It can carry their serialised ASTs inside itself, and --exe compiles their routine bodies, which are the next two sections.
Compile-time code runs at build time. Rakudo runs a unit's BEGIN blocks and constant initializers while compiling it, and a binary is the program precompiled, so the three compiling modes do the same: they run the program's compile-time part in an interpreter while building and substitute each value for the code that computed it. constant DATA = slurp 'data.txt' reads the file where the binary is built, and the binary carries the text. Only plain data whose .raku evaluates back to an equal value is embedded; an object, a closure or a handle is left to run at startup, and the build says so (src/CompileTime.h).
Carrying modules inside a binary
A standalone binary that needs its modules' source files on the target machine is not very standalone. So the compiling modes resolve the use graph at build time and embed each module's serialised AST:
// src/Interpreter.h
struct BundledModule {
std::string name, blob, finish, src;
std::string distKey, distMeta;
std::vector<BundledResource> resources;
bool interpretOnly = false;
};
struct ModuleSkip { std::string name, reason; };
std::vector<BundledModule> collectModuleGraph(
const Program& prog, const std::vector<std::string>& searchPath,
std::set<std::string>* exportsOut = nullptr,
std::vector<ModuleSkip>* skipsOut = nullptr,
/* … native libraries, used modules, engine-answered modules … */);
void rakuppRegisterModule(const std::string& name, const char* blob,
size_t blobLen, const std::string& finish);
Registration happens once at startup, and loadModule consults the embedded table before it looks at the disk. A module's distribution travels with it: its META6.json and resource files are embedded too, once per distribution, so %?RESOURCES is not an empty hash inside a binary.
A module that cannot be found, parsed or serialised is left out rather than failing the build — the binary falls back to loading it from disk, which is also what has to happen for anything only a running program can name (require ::($x), a computed use lib). Every compiling mode says what it embedded and, one line each with the reason, what it could not, along with the native libraries the binary will still dlopen:
--exe: embedded 1 module: Mo
--exe: not embedded: Foo — not found on the module search path
(the binary will need the disk at run time)
--standalone turns that second line into a build error, exit 4: a binary that would need the disk is not built. --auto goes the other way and installs a missing module from the ecosystem first, then embeds it.
--bundle needs one extra thing, and it is a subtle one. It parses the main program at run time, and that parse has to scan each used module for the operators it declares (Chapter 6) — otherwise a program using an imported operator stops parsing once the module tree is gone. So bundled binaries also carry the module sources:
// src/Parser.h
void rakuppRegisterModuleSource(const std::string& name,
const char* src, size_t len);
const std::string* rakuppEmbeddedModuleSource(const std::string& name);
--exe and --aot parse at build time and never need it.
Native bodies for module routines
Embedding made a compiled binary self-sufficient and left it uneven: the program was native code and every module it used was a tree walk. Since October 2026 --exe also emits a native body for each module routine the generator can compile, with the same Codegen that compiles the program.
The interpreter still makes the call. It dispatches, binds the signature into a fresh frame and runs the phasers; where it would walk the body's statements it enters a C++ function instead:
// src/AotModules.h
using AotBodyFn = bool (*)(Interpreter&, Env*, Value& out);
struct AotEntry { int index; const char* name; AotBodyFn fn; };
void rakuppRegisterModuleAot(const char* module, const AotEntry* table,
size_t n);
void attachAotBodies(const std::string& module, Program& prog);
The function reads its parameters out of the frame and reaches every other outer name through it. The two sides agree on which routine a body belongs to by walking the same deserialized tree in the same order (forEachAotRoutine), so the n-th routine is the same SubDecl at build time and at load time.
Refusal is per routine here, and often per statement. A statement the generator cannot compile is serialized and handed to the interpreter from inside the native body; a routine it cannot compile at all keeps its tree; and a body the C++ compiler rejects is dropped and the file compiled again without it, so one bad routine costs that routine alone.
--exe: 1 of 2 module routines compiled natively
RAKUPP_AOT_REPORT=FILE writes what became of every routine and why, RAKUPP_NO_AOT=1 keeps them all interpreted. The bundled fallback of the previous section is this mechanism pointed at the program itself: its routines are compiled as if they were a module's, and attached only if the source the binary parses at startup serializes to the same bytes they were compiled from.
A sketch instead of a binary
--target=arduino is the sixth back end and the strictest. It turns a Raku program into one Arduino sketch: C++ that names no runtime, which the Arduino core's own compiler builds into firmware.
rakupp --target=arduino blink.raku -o blink.ino # the sketch
rakupp --target=arduino --sim blink.raku -o sim # built for this computer
// src/codegen/Arduino.h
std::string transpileToArduino(Program& prog, const ArduinoOptions& opt);
A board has no interpreter to fall back on, so there is no fallback: every construct either becomes plain C++ or is refused with its line before anything is built. The subset is native scalars, shaped native arrays, subs with native signatures, constants, say and print as serial writes, and the Arduino module's routines as the core's own names. The mainline before the top-level loop { } becomes setup() and one iteration of that loop is one call of loop(). BEGIN blocks and every constant run while building, by the compile-time pass above, so the board gets values and no code that computed them.
The same program runs without a board two ways: under the interpreter, where use Arduino is a simulated board, and with --sim, which compiles the sketch itself for this computer against a host core embedded in rakupp. The gate, t/arduino/run.raku, holds the second to the first byte for byte, so the interpreter is the oracle for the generated C++. The sketches have also run on a real board, an Uno R4 WiFi.
--target=microbit is the same emitter with a second board. The walk over the AST, the subset and its refusals live in src/codegen/BoardEmitter.h; Arduino.cpp and MicroBit.cpp are its two subclasses, each adding its module's names, where say writes, and the program's shape. For a BBC micro:bit V2 that is C++ for CODAL, the board's own runtime: the mainline runs in main() after uBit.init(), the top-level loop is a C loop there, and use MicroBit names the board by MicroPython's names spelt as Raku. CODAL's build turns the file into the .hex copied onto the board. Its gate, t/microbit/run.raku, holds the --sim build to the interpreter in the same way, and with --codal=DIR builds every program with CODAL's own toolchain.
Mode 1 in a browser
The same runtime compiled to WebAssembly is Raku.js: the interpreter running in a browser tab, with the same Value semantics and no server. It is mode 1 with a different host — but the host removes the filesystem, the threads and the dynamic loader, which changes enough to be worth its own chapter. That is Chapter 32, at the end of this part.