Hypothalamus

Hypothalamus is a Brainfuck ahead-of-time compiler with an LLVM IR backend. It parses Brainfuck source, performs small local optimizations, 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.

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.

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

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, or llvm-ir [default: exe]
      --target <TRIPLE>     LLVM target triple passed to clang and embedded in IR
      --tape-size <CELLS>   Tape cell count [default: 30000]
      --cc <PATH>           clang-compatible LLVM driver [default: clang]
      --keep-ll             Keep generated LLVM IR beside the output
  -h, --help                Print help
      --version             Print version