Recoil

Requirements

Recoil transpiles to C, so you need two things on your machine:

• A C compiler — GCC or Clang. The generated C is plain and portable.
• Rebol 3 — the compiler itself is written in Rebol. Use the actively maintained Oldes build of Rebol 3 (the bulk variant is the easiest to start with). Binaries exist for Linux, macOS, the BSDs, Haiku, and Windows.

The Rebol executable is usually called r3 (sometimes rebol3). All commands below use r3.

Get the source

git clone https://git.rblk.eu/sony/recoil.git
cd recoil

Your first program

Create a file called hello.rcl:

; hello.rcl
print "Hello, Recoil!"

Compile and run it:

r3 -s recoil.r3 hello.rcl

This compiles the program and runs it straight away. The compiler emits a C file, invokes your C compiler and links the result under the cache/cli/ directory rather than next to the source. To keep a binary where you want it, pass -o (build only, then run it yourself); to see the generated C without building a binary, transpile only:

r3 -s recoil.r3 -o hello hello.rcl
./hello

r3 -s recoil.r3 --transpile hello.rcl

Try it

A slightly bigger program

Bindings are implicitly typed and functions return their last expression:

; sum.rcl
add: func [a [i32!] b [i32!] return: [i32!]] [
    a + b
]

total: add 2 40
print total             ; 42

Read the Language Guide for the full syntax, or skim Recoil by Example for more complete programs.

Building libraries

Recoil can emit shared or static libraries with a generated C header. Mark functions with #export (see Packages & Libraries), then:

# Shared library (name derived from the source file)
r3 -s recoil.r3 --lib mylib.rcl

# Shared library with a custom name
r3 -s recoil.r3 --lib mylib.rcl --name mylib

# Static library
r3 -s recoil.r3 --lib mylib.rcl --static

Note that --lib comes before the source file.

Running the test suite

The project uses its own test runner, RUT. Verify your setup:

# Run the whole suite
r3 -s rut.r3

# A specific test by title
r3 -s rut.r3 -t "Mandelbrot"

# A single test file
r3 -s rut.r3 -F parser.reb

# List available tests
r3 -s rut.r3 --list

Run RUT with r3 -s rut.r3 (not r3 rut.r3), and only one build at a time — RUT enforces a single active runner via a lock.

Next steps: projects, targets and release builds

Release builds

r3 -s recoil.r3 --release -o hello hello.rcl

Targets

--target selects the platform: native (default), wasm32-emscripten, esp32, windows-msvc, and others. --cc zig selects Zig as the C toolchain.

r3 -s recoil.r3 --target wasm32-emscripten hello.rcl

Projects and packages

Native capabilities such as TLS, SQLite, f00 and GUI are packages. In a project directory:

r3 -s recoil.r3 init                 # write recoil.project
r3 -s recoil.r3 install tls          # add a capability and its backend
r3 -s recoil.r3 fetch                # resolve and fetch, write recoil.lock.reb
r3 -s recoil.r3 run main.rcl         # build and run through the lockfile
r3 -s recoil.r3 compile main.rcl     # build only

Subcommands must be the first argument, so options follow them (compile --target ...). See Packages for the workflow, CLI & Targets for every option, and Standard Library for the modules you can import.

Next steps