# Hypothalamus
[](https://crates.io/crates/hypothalamus)
[](https://crates.io/crates/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](https://brainfuck.org/brainfuck.html):
- 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
```sh
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:
```sh
cargo build --release --target x86_64-unknown-linux-gnu
```
## Usage
Compile a Brainfuck program to a native executable:
```sh
cargo run -- examples/hello.b -o hello
./hello
```
Emit LLVM IR:
```sh
cargo run -- --emit llvm-ir examples/hello.b -o hello.ll
```
Emit an object file for another LLVM target:
```sh
cargo run -- --emit obj --target x86_64-unknown-linux-gnu examples/hello.b -o hello.o
```
Emit assembly:
```sh
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
```text
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
```