← Contents

Appendix B

Flags and Environment Variables

Everything that changes what the compiler does from the outside. This is a reference for the internals; the user-facing command line is documented in docs/guide/CLI.md.

Command-line flags that select a mode

FlagEffect
(none)lex, parse, interpret
-e 'code'interpret the argument
--bundleembed the source bytes in a standalone binary
--aotparse at build time, emit C++ that rebuilds the AST
--exetranspile to C++ and compile natively
--cpp, --emit-cppprint the generated C++ instead of compiling it
-Orun the codegen optimizer. Any suffix (-O2, -Ofast, -Os, …) turns it on too and is forwarded to the C++ compiler; there is one flag here, not five

Inspection and tooling flags

FlagEffect
--ast, --dump-astprint the parsed tree as an indented outline
--ast-roundtripserialise and deserialise the tree, then run it — the cache format's own test
-c, --target=parsecompile-check only: parse and check every variable is declared
--lintstatic analysis; does not run the program
--doc-linkslink every construct of a program to its page on docs.raku.org; a list, or the program annotated with --html or --ansi, or --json
--highlightsyntax-highlight the source
--html, --ansi, --terminalpick the highlighter's renderer
--docrun DOC phasers and print rendered Pod
--profile[=dest]the routine-level wall-time profiler
--mcpserve the interpreter over the Model Context Protocol on stdio
--timeout=SECS--mcp only: the watchdog's limit; 0 disables it
--jupyter FILErun as a Jupyter kernel against Jupyter's connection file
--jupyter-installwrite the kernelspec that lets Jupyter launch this binary
--ffi-infowhich FFI backend is live, or why none is
--fmtformat Raku source to stdout (--target=raku); --check lists the files that would change, --diff shows what
--rakuastprint the RakuAST view of the program beside the Raku each node renders back to (--target=rakuast); =tree, =attrs, =compunit vary it
--jit-infowhat is in the tier-up kernel cache (Chapter 44)
--jit-cleanempty it
--precomp-infowhat the parse cache holds
--precomp-cleanempty it
--precomp-modules=on|off, --precomp-files=on|offthe two cache switches
--version, -vthe release, build and platform, on one line
-Vthe full report — the split is Rakudo's, but the report is a readable block, not Rakudo's key=value config dump
--info, --version-fullours; Rakudo spells this -V and nothing else
--help, -h, --quiet, -qas expected
-xskip everything before the #! line
--jsonmachine-readable -c and --lint findings
--ll-exceptionevery frame of an uncaught error
--exe-info FILEthe build manifest embedded in a compiled binary
--stagestatsphase timings and module loads on stderr
--traceprint each statement as it runs
--hintsperformance advice on stderr, each hint once per source line; the same as RAKUPP_HINTS=1
--detect-raceswatch the threads' reads and writes and report data races when the program ends; a run that raced exits 66
--repl-afterrun the program, then open a session on its state
--completions=bash|zsh|fishprint a shell completion script
--lsprun the Language Server: diagnostics, hover, completion and go-to-definition (Chapter 39)

Flags that shape a build

FlagEffect
-o FILEoutput file (compile modes, --target=js)
-I DIRadd a module search directory
--slim[=MODE]cut unused runtime subsystems from the binary; MODE is safe, auto, max, none, help, list or verify
--standalonea module that cannot be embedded is a build error
--staticlink the C++ runtime into the compiled binary (Linux, MinGW)
--target=jstranspile to JavaScript (Chapter 31)
--target=arduinotranspile to an Arduino sketch
--target=microbittranspile to C++ for a BBC micro:bit's runtime, CODAL
--sim--target=arduino and --target=microbit only: build the program for this computer, on a simulated board
--verifyemit JavaScript only if it agrees with the interpreter
--moduleJavaScript: export the subs, classes and MAIN instead of running
--runtimewrite just the JavaScript runtime
--fallback=wasmaccept a program outside the JavaScript core, on the WebAssembly engine

Flags that change how a run behaves

FlagEffect
--jit[=SPEC]work in progress: compile hot loops with the machine's C++ compiler while the program runs, off by default. SPEC words: off, on, sync, verbose, stats, nocache, pch, threshold=N (Chapter 44)
--cnp[=SPEC]work in progress: the same by copy-and-patch — no compiler and no cache. SPEC words: off, on, verbose, stats, threshold=N (Chapter 44)
--seedpin the random generator
--autoinstall the modules the program uses that are missing, then run it; with a compile mode, install and then embed them
--sandbox[=language]the program may compute, print and read standard input, and nothing else: no files, processes, sockets, native code or environment. Enforced by the interpreter and by the operating system under it; =language is the interpreter's checks alone
--stack-sizethe stack of the program thread, and so the recursion ceiling
--env-file FILEload KEY=VALUE lines into the environment
--color=auto|always|neverANSI colour on stderr and in the REPL
--watchre-run the program whenever it or a library file changes
-laccepted; lines already arrive chomped
-0NUL-separated records
--name, --prefix DIRkernel name and location for --jupyter-install

Flags are position-independent, and the perl-compatible one-liner family (-n, -p, -a, -F, -i, -0777, -M) is documented in the CLI guide.

This list is checked against the binary rather than maintained by hand: tools/check-book-appendix.raku reads kFlagDocs out of src/main.cpp — the same table --help prints from — and fails if a flag is in one and not the other. It was written because this appendix was missing twenty-seven of the sixty-six flags the binary accepts, including a whole run mode. The table has 81 flags now.

Subcommands

A first argument that is one of these words is a command, not a program file.

CommandEffect
installfetch, test and install modules into the store (Chapter 34)
uninstallremove distributions this installer put there
reinstalluninstall and install fresh
testrun a module's test suite against the store, installing nothing but its dependencies
doclook a builtin, method or operator up in the language reference, offline
upgradereplace this binary with a newer release

Environment variables

Search and loading

VariableEffect
RAKULIBextra module search paths; both , and : separate
ROASTadds the specification suite's test-helper library
RAKUPP_HOMEwhere the binary considers itself installed
RAKUPP_CONFIGoverride the settings file location
RAKUPP_VM_NAMEwhat $*VM.name answers instead of cpp, for modules that branch on it
RAKUPP_NO_CWD_LIB=1do not search lib and rakulib under the current directory
RAKUPP_OPToptions prepended to every command line; options only, never a program
RAKUPP_DEPS=0make --auto do nothing, for a harness whose children inherit it through RAKUPP_OPT
XDG_CONFIG_HOME, XDG_CACHE_HOMEthe settings and cache directories

The parse cache

VariableEffect
RAKUPP_PRECOMP_MODULESoverride the module-cache switch for one run
RAKUPP_PRECOMP_FILESoverride the file-cache switch
RAKUPP_NO_PRECOMP=1force both off
RAKUPP_PRECOMP_DIRwhere cache entries live

The tier-up compilers

VariableEffect
RAKUPP_JIT_THRESHOLDiterations before a loop counts as hot, for whichever back end is on
RAKUPP_JIT_VERBOSEnarrate every tier-up decision to stderr
RAKUPP_JIT_DIRwhere --jit keeps compiled kernels
RAKUPP_CNPa bundled binary only, which has no option surface of its own: 0 or off turns the baked-in back end off for one run, 1 on, anything else is read as a --cnp spec
RAKUPP_CNP_X86=1run the x86-64 patcher on Linux, where it is refused at startup until it has been verified on ELF (it runs on macOS x86-64 without this)

Kernels and native bodies

VariableEffect
RAKUPP_NO_KERNELS=1run subs and loops over plain Ints, Nums and Strs the ordinary way, not as kernels on machine values; under --exe, no integer sub twins either. The kernels' oracle is the same build with this set
RAKUPP_KERNEL_TRACE=1name each sub and loop as its kernel is decided
RAKUPP_HYPER_THREADS=Ncap the threads the hyper-operator kernels split a long operand over; 1 is serial
RAKUPP_NO_SELFPACK=1do not pack a fresh untyped Array of plain Nums or plain machine Ints into machine words; RAKUPP_NO_SELFPACK_INT=1 keeps Nums packing and turns the Ints off; RAKUPP_SELFPACK_MIN=n is the fewest elements packed
RAKUPP_NO_AOT=1--exe: keep the embedded modules' routines interpreted (RAKUPP_AOT_VERBOSE=1 says why one stays interpreted)
RAKUPP_AOT_REPORT=FILE--exe: write which module routines got native bodies and why the others did not
RAKUPP_AOT_RUNLOG=FILEin a compiled binary: at exit, write how often each native module body was entered or declined
RAKUPP_NO_PCH=1, RAKUPP_PCH_DIR--exe: compile without the cached precompiled header; where that cache is kept

The foreign-function interface

VariableEffect
RAKUPP_FFI=0force the no-libffi fallback path
RAKUPP_FFI=/pathuse only that library; if it fails to load, report and fall back rather than silently substituting the system copy
RAKUPP_FFI_TRACE=1log every crossing, with marshalled arguments and raw returns

Memory

VariableEffect
RAKUPP_CYCLE=0no cycle collection: reference counting alone (Chapter 12)
RAKUPP_CYCLE=dryfind cyclic garbage and count it, free nothing
RAKUPP_CYCLE_STATS=1at exit, report collections, candidates, walks and what was freed
RAKUPP_CYCLE_POISON=1give a collected object a class whose every method dies, instead of clearing it
RAKUPP_CYCLE_TRIGGER=Ncollect whenever N candidates wait; 1 collects at nearly every scope exit

Concurrency

VariableEffect
RAKUPP_GIL=1coordinate threads under one global lock. Since v3 the default is the other way: start blocks and workers run on all cores
RAKUPP_PARALLEL=0a synonym for RAKUPP_GIL=1, kept from when parallel was the opt-in
RAKUPP_PRIVATE_SLOTS=0take the stripe lock for every variable slot, including the ones proved private to one thread; an A/B instrument
RAKUPP_STRIPE_STATS=1at exit, how often each stripe was found already held
RAKUPP_RACE=1what --detect-races sets; RAKUPP_RACE_TRACE=edges or =accesses narrates what the detector sees
RAKUPP_MAIN_THREAD=1run the program on the process's main thread, not the spawned 1 GiB one — for Cocoa, which refuses to create windows anywhere else
RAKUPP_FREEZE_TRACE=1report any symbol-table mutation after concurrency engaged, and which thread did it

The regex engine

VariableEffect
RAKUPP_LTM=0rank longest-token alternatives with the legacy greedy probe. The NFA ranker is the default, where it is gap-free
RAKUPP_LTM_DEBUG=1rank both ways and print every disagreement — works without RAKUPP_LTM
RAKUPP_LTM_RANKDUMP=1print each decided alternation's ranking

Diagnostics

VariableEffect
RAKUPP_TRACE=1the module search path and every resolution
RAKUPP_DUMPTOKENS=1the token stream
RAKUPP_NO_DECLCHECK=1skip the undeclared-variable gate (Chapter 39)
RAKUPP_NO_CALLCHECK=1skip the will-never-work call gate (Chapter 39)
RAKUPP_BACKTRACE=0|short|fullhow much of an uncaught error's backtrace prints
RAKUPP_HINTS=1performance advice on stderr, as --hints
NO_COLOR, RAKUPP_COLOR=0|1colour off by convention; forced off or on
RAKUPP_UNICODE=0|1force the non-ASCII glyphs in rakupp's own output off or on
RAKUPP_ACTTRACE=1grammar action firing
RAKUPP_TAP_TRACE=1the test harness's own emission
RAKUPP_KEEPGEN=1keep the generated C++ from a compiling mode
RAKUPP_DEBUG_MAKEgrammar make diagnostics
RAKUPP_NFC_CHECK=1, RAKUPP_DYNCACHE_CHECK=1, RAKUPP_ATTR_LAYOUT_CHECKeach checks one cache against the slow path it replaces — the NFC flag on a string body, the dynamic-variable memo, the attribute layout — and reports a mismatch

The interactive session

VariableEffect
RAKUPP_REPL=1force a session even when standard input is not a terminal
RAKUPP_HISTORYthe history file

Test-harness variables

RAKU_TEST_DIE_ON_FAIL stops a suite after a real failure; RAKU_EXCEPTIONS_HANDLER=JSON serialises uncaught exceptions as JSON. Both follow Rakudo's spelling because test harnesses set them.

Build-time switches

DefineEffect
RAKUPP_PTR_CENSUScount which combinations of Value's eleven pointers are actually live together — the empirical input to shrinking the struct
RAKUPP_STR_CENSUScount the strings a Value makes, copies and writes, by length — the measurement that picked VALUE32-PLAN's design C, a 15-byte inline string, over B, a body for every string (tools/str-census.md)
_GLIBCXX_USE_CXX11_ABIrelevant only because it is the ABI break copy-on-write strings caused (Chapter 9)

The pointer census is a good example of the project's habit: before collapsing Value's pointers into tag-dispatched slots, a special build counts which sets are live simultaneously, rather than reasoning about what the type tags suggest.

A note on flags that change behaviour

Two of the variables above change results rather than speed: RAKUPP_LTM and RAKUPP_GIL. The policy for both is the same: the old path stays available for at least one release after the default changes, so a regression can be bisected to the switch rather than to the release. Both defaults have changed. The NFA ranker and parallel workers are what runs, and the two variables are now the way back.

RAKUPP_VM_NAME is a third, and a different kind. It changes one answer — $*VM.name, and the $*RAKU.VMnames list it has to stay a member of — so that a module which branches on the name and dies on the else takes its moar branch instead. Nothing sets it on your behalf, and no measurement this project publishes runs with it set: the default is what this engine is, and asserting a dialect is the caller's statement, not the engine's. $*VM.config is untouched either way, because the toolchain values in it were already real.

Everything else here either reports something or selects a code path that is required to produce identical output.