Hypothalamus

Hypothalamus is a Brainfuck ahead-of-time compiler with an LLVM IR backend. It parses Brainfuck source, lowers it into an optimized Brainfuck-specific IR, emits LLVM IR, and can use clang to lower that IR to an executable, object file, or assembly for any target your LLVM toolchain supports. It can also execute the generated LLVM IR directly through lli.

The language behavior follows Daniel B. Cristofani's Brainfuck reference:

• Only the eight Brainfuck commands are meaningful; all other bytes are ignored.
• The tape defaults to 30,000 zeroed byte cells.
• Cell arithmetic wraps modulo 256.
• [ and ] must match and nest correctly.
• . writes one byte through putchar.
• , reads one byte through getchar; EOF leaves the current cell unchanged.
• Moving the pointer outside the configured tape is undefined behavior, matching the reference's "unpredictable" boundary behavior.

Optimizations

Hypothalamus performs Brainfuck-specific optimizations before LLVM emission:

• folds adjacent cell additions and pointer moves;
• removes no-op arithmetic and movement;
• turns clear loops such as [-] and [+] into direct stores;
• combines arithmetic at fixed pointer offsets;
• removes dead arithmetic before clears;
• turns scan loops such as [>], [<], [>>], and [<<] into explicit scan operations;
• turns transfer and multiply-transfer loops such as [->+<] and [->+++>++<<] into straight-line multiply/add operations.

Native builds pass -O2 to clang by default. Use --opt-level or -O0, -O1, -O2, -O3, -Os, or -Oz to choose another LLVM optimization level. Use --bounds-check when debugging if you want generated programs to trap on out-of-range tape access instead of using Brainfuck's usual undefined boundary behavior.

Build

cargo build --release

The compiler itself has no third-party Rust dependencies. Native code emission requires a clang executable or compatible LLVM driver.

Because Hypothalamus is a plain Rust binary, the compiler can also be cross-built through Cargo for any Rust target available in your toolchain:

cargo build --release --target x86_64-unknown-linux-gnu

Usage

Compile a Brainfuck program to a native executable:

cargo run -- examples/hello.b -o hello
./hello

Emit LLVM IR:

cargo run -- --emit llvm-ir examples/hello.b -o hello.ll

Emit an object file for another LLVM target:

cargo run -- --emit obj --target x86_64-unknown-linux-gnu examples/hello.b -o hello.o

Emit assembly:

cargo run -- --emit asm examples/hello.b -o hello.s

Run through LLVM's JIT-capable lli tool:

cargo run -- --emit jit examples/hello.b

Compile the Brainfuck self-interpreter fixture:

cargo run -- -O3 examples/dbfi.b -o dbfi
printf ',+.!A' | ./dbfi

If your LLVM tools are not on PATH, pass --cc <path> for clang or --lli <path> for lli.

Cross-compiling a full executable requires the target linker, C runtime, and sysroot that your selected clang --target=<triple> needs. Emitting LLVM IR, assembly, or object files works with fewer target runtime assumptions.

CLI

hypothalamus [OPTIONS] <INPUT>

Options:
  -o, --output <PATH>       Output path. Use '-' with --emit llvm-ir for stdout
      --emit <KIND>         exe, obj, asm, llvm-ir, or jit [default: exe]
      --jit, --run          Execute the generated LLVM IR with lli
      --target <TRIPLE>     LLVM target triple passed to clang and embedded in IR
      --tape-size <CELLS>   Tape cell count [default: 30000]
      --bounds-check        Trap on out-of-range tape access
      --opt-level <LEVEL>   clang optimization level: 0, 1, 2, 3, s, or z [default: 2]
      --cc <PATH>           clang-compatible LLVM driver [default: clang]
      --lli <PATH>          LLVM lli executable for --emit jit [default: lli]
      --keep-ll             Keep generated LLVM IR beside the output
  -h, --help                Print help
      --version             Print version