Common forms
recoil.r3 is the user-facing entry point for compiling, running, transpiling, package maintenance and target builds. -s disables Rebol security for the wrapper process; compile and test flows write C, binaries, lockfiles and caches, so it is the expected invocation. Starting the CLI with no source file or subcommand opens the interactive REPL.
r3 -s recoil.r3 tests/simple-test.rcl # compile and run
r3 -s recoil.r3 --transpile tests/simple-test.rcl # emit C
r3 -s recoil.r3 --transpile -o out.c tests/simple-test.rcl
r3 -s recoil.r3 --ast tests/simple-test.rcl # print the AST
r3 -s recoil.r3 -o out.bin tests/simple-test.rcl # build, don't run
r3 -s recoil.r3 --lib examples/net/http-server.rcl # shared library
r3 -s recoil.r3 --lib examples/net/http-server.rcl --static # static library
r3 -s recoil.r3 --lib examples/net/http-server.rcl --name mylibProgram arguments
Arguments after -- are not parsed as Recoil options; they go to the compiled program. Without --, option-looking words are treated as CLI options and may fail validation.
r3 -s recoil.r3 app.rcl -- first secondRead them with std/io. The program name is not included; arg-at is 0-based and returns an empty string out of range.
Recoil [
Title: "Args"
Type: module
Module: app
Imports: [
std/io [arg-count arg-at args]
]
Exports: []
]
print arg-count ; 2
foreach [a] args [ print a ]
print arg-at 0 ; firstTargets with no argv (the ESP-IDF entry and the Emscripten main(void)) report a count of 0 and an empty args instead of failing.
Options
Source & output
| Option | Effect |
|---|---|
-s, --source CODE | compile a source string instead of a file |
-o, --output FILE | C for --transpile, an executable for normal runs, a library for --lib |
-l, --lib | build a library instead of an executable |
--static | with --lib: static library (shared is the default) |
--name NAME | with --lib or --rebol-extension: library or extension base name |
--rebol-extension | build a Rebol native extension (.rebx, always a shared library; --static is rejected). See Rebol Extensions |
Behavior
| Option | Effect |
|---|---|
-t, --transpile | emit C instead of building and running |
-a, --ast | print the AST |
--release | optimization level 2 (the default build is unoptimized — measure with this) |
-g, --debug | emit debug info (-g) |
--optimize LEVEL | optimization level or named profile |
--build-seed N | seed for codegen temporary names; an integer pins it so the same source transpiles to byte-identical C (default 1), random leaves the sequence unpinned, so generated C is no longer byte-reproducible (useful for shaking out a temp-name collision) |
--prec | disable operator precedence |
--rebol-static / --rebol-shared | link the Rebol runtime statically (default) or dynamically |
--lsp-parse-only | with --transpile: parse and typecheck without running comptime/compfunc |
--quiet / --no-quiet | progress logging off/on; RECOIL_QUIET=1 has the same default effect as --quiet |
-h, --help | embedded CLI help |
Compiler & linker flags
--cflag FLAG and --linkflag FLAG add one argument each and may be repeated. Quote flags that contain spaces.
r3 -s recoil.r3 --cflag -Wall --cflag -Wextra app.rcl
r3 -s recoil.r3 --linkflag -lm --linkflag -pthread app.rclTargets & toolchains
--target TARGET chooses the toolchain id: native, arm-linux-gnueabihf, wasm32-emscripten, windows-msvc or esp32. Browser WASM targets transpile or build artifacts but are not run by the host CLI. ESP32 builds go through a generated ESP-IDF project under cache/<host-platform>/esp-idf/; flashing and monitoring stay ESP-IDF commands (see f00 & Embedded).
| Option | Effect |
|---|---|
--target TARGET | target toolchain id |
--cc COMPILER | override the C compiler for this build (one command, not a place for flags) |
--msvc-root PATH | MSVC installation root for windows-msvc |
--sysroot PATH | override the target sysroot |
--c-profile PROFILE | c99, c11, c17, gnu11, gnu17 |
C profiles
The gnu* profiles (the default) allow GCC statement-expressions, so an expression that needs statements is emitted inline. The portable profiles (c99, c11, c17, and what a Windows/MSVC target uses) have no such construct, so those expressions are lifted into helper functions.
gnu11 compiles under c99, c11, c17 and MSVC, and every rejected source is rejected identically with the same diagnostic. A program whose verdict depends on --c-profile is a compiler bug.Zig as the C toolchain
--cc zig is recognized specially: Recoil invokes zig cc / zig ar instead of a compiler binary, so a machine with no gcc, clang or MSVC can still build. When cross-compiling, -target <triple> is injected for targets Zig supports (currently arm-linux-gnueabihf). It is opt-in: Recoil never falls back to Zig on its own.
r3 -s recoil.r3 toolchain fetch zigDownloads the pinned Zig release for the host into cache/toolchains/zig/<version>/<platform>/, verifies its sha256 against the values published by ziglang.org, and prints the resolved path. After that, --cc zig finds the cached toolchain whenever zig is not on PATH. The fetch is always explicit: a --cc zig build with no Zig anywhere fails with R6108 instead of downloading. Supported hosts: macOS (aarch64, x86_64), Linux (aarch64, x86_64), Windows (x86_64); anything else is R6132, and a corrupted download is R6033.
Recoil REPL
Starting recoil.r3 with no source file or subcommand opens an interactive console (a standalone Recoil executable does the same when run with no arguments). It is meant for small compile/run checks, generated-C inspection and quick Rebol-side debugging of the compiler process. It is a different tool from the browser-based f00 REPL, which runs the f00 language in a web page.
r3 -s recoil.r3The prompt is Recoil>; input is line-oriented and quit exits.
| Command | Effect |
|---|---|
compile <file> | compile a .rcl file to an executable without running it |
run <file> | compile and run a .rcl file |
transpile <file> | print the generated C |
recoil <code> | compile and run a Recoil source snippet |
rebol <code> | evaluate Rebol code in the host running the compiler and print the result |
quiet / verbose | suppress / re-enable build progress messages (program output is still printed) |
help, quit | list the commands; exit |
Recoil> rebol 1 + 2
== 3
Recoil> recoil print 1
1compile, run and recoil use the normal pipeline, so they need the same C compiler, runtime objects and writable caches as ordinary builds. The console requires Rebol 3's line-editor!; a host without it fails with a build/configuration error.
Package commands
Package-aware projects use subcommands, which must be the first CLI argument, so --target follows the subcommand (compile --target …, install raylib --target …).
| Command | Effect |
|---|---|
init | create a recoil.project workspace |
install <capability> | add a first-party capability package and its providers, then write the lockfile (install tls adds TLS/HTTPS; --target selects a target-specific provider) |
fetch | resolve dependencies, fetch archives or git refs, write recoil.lock.reb (target-agnostic) |
update | refresh dependency resolution and lockfile entries |
doctor | validate the workspace and native package cache |
repair | rebuild missing or partial source-store entries from the lockfile |
compile <entry.rcl> | compile a package entry using the lockfile |
run <entry.rcl> | compile and run a package entry using the lockfile |
compile and run accept the same build options as single-file compilation. fetch and update reject --offline. See Packages.
Security options
| Option | Effect |
|---|---|
--strict / --no-strict | enable/disable the strict security profile (also Security/Strict in recoil.project) |
--offline / --no-offline | forbid/allow HTTP(S) package downloads during compile or run; strict implies offline unless overridden |
--security-audit FILE | write a machine-readable audit report while compiling |
--security-audit-format FORMAT | rebol (default) or jsonl |
--fail-on-comptime-in-untrusted | fail if comptime/compfunc runs in package-store or unknown code (see Comptime) |