Installation

Pluvial is implemented in C (C11) as a stack-based bytecode VM. The compiler and runtime are distributed as a single binary, pluvial.

Requirements

• A C11 compiler with the GCC or Clang label-as-values extension (used for computed-goto dispatch). Other compilers fall back to a switch-based dispatcher.
• The standard C library and math.h (used by the runtime for pow() / fmod()).

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.

Empirically (see the language spec, §1), 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 commands

pluvial                 # start the REPL
pluvial file.plu        # compile and run file.plu
pluvial run file.plu    # explicit run subcommand
pluvial check file.plu  # compile only; do not run (editor / CI dry-run)
pluvial --version       # print the version and exit
pluvial -v              # same as --version
pluvial --help          # print usage and exit
pluvial -h              # same as --help

• pluvial file.plu is the standard entry point. The .plu extension is a convention, not a requirement.
• pluvial check compiles the source and reports type errors without executing the program. It is intended for editor integration, pre-commit hooks, and CI.
• pluvial --help is written to stdout; usage errors are written to stderr and exit with code 64.

Exit codes

Pluvial follows the sysexits convention:

Code	Meaning
0	Success
64	Misuse of the CLI (wrong number of arguments)
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, etc.)

Colored error output

Error blocks use ANSI color when stderr is a TTY:

• error: / runtime error: — bold red
• --> file:line:col — bold
• caret span ^^^ — bold red
• = help: — bold blue
• gutter | and source line — unstyled

When stderr is not a TTY (pipes, CI, test harnesses), color is suppressed entirely; output is byte-identical to the uncolored form.