Installation

Pluvial is implemented in C (C11) as a stack-based bytecode VM, following the architecture of Bob Nystrom’s Crafting Interpreters (clox). The compiler and runtime ship as a single binary, pluvial.

Requirements

• A C11 compiler. GCC or Clang is recommended: the dispatch loop uses the labels-as-values extension (computed-goto direct threading). Compilers without it (such as MSVC) fall back to a switch-based dispatcher, so the build stays portable.
• The standard C library and math.h — the runtime uses pow() and fmod() for the ** and % operators.

Optional dependencies (for some standard-library modules)

Module	Dependency	Notes
std/http	libcurl	Linked via curl-config --libs / --cflags. macOS uses the system libcurl.
std/regex	libpcre2 (libpcre2-8)	Detected with pkg-config. Building with HAVE_PCRE2=0 falls back to error stubs.
pluvial build (AOT)	LLVM (llc) and clang	Required only for ahead-of-time native compilation.

Recommended build flag

Build the runtime with -O2. The NaN-boxed value representation and the computed-goto dispatcher rely on the optimizer inlining a small set of static inline helpers; without -O2 those calls remain function calls and the optimizations do not pay off.

Per the language spec, a 100M tight arithmetic loop runs about 2.59× faster at -O2 than at -O0 (median 4.40s vs 11.40s) with byte-identical output.

CLI entry points

pluvial                 # start the REPL (no arguments)
pluvial file.plu        # compile and run file.plu

The .plu extension is a convention, not a requirement. The full set of subcommands and flags is documented in the CLI reference.

Exit codes

Pluvial follows the sysexits convention:

Code	Meaning
0	Success
64	Misuse of the CLI (no arguments / too many)
65	Compile error (type error, syntax error, static error)
66	Could not open or read the input file
70	Runtime error (division by zero, stack overflow)