Cranefack

A cranelift powered optimizing brainfuck compiler suite.

Commandline interface

Cranefack provides a command line utility to run, compile and benchmark programs.

cargo install cranefack-cli

Run

Run a program with interpreter or jit.
Passing the -v option prints some statistics and execution time.

USAGE:
cranefack run [FLAGS] [OPTIONS] <FILE>
FLAGS:
--debug-optimizations Print statistics for optimization passes
-j, --jit Use JIT compiler
-v, --verbose --wrapping-is-ub Wrapping overflows are undefined behavior during optimization
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
--jit-level <level> Optimization level for JIT [possible values: none, speed, speed_and_size]
-O <mode> Optimization mode [default: 2] [possible values: 0, 1, 2, 3, s, wtf]
ARGS:
<FILE> Brainfuck source file. Use - to read from stdin

Compile

Compile the program.
As of now this will create an assembly like representation by default that is only useful for debugging.
In case you need something to compile into a native binary you can use the rust output format to get ugly rust code that can be compiled with rustc:

cranefack compile -f=rust some_app.bf > some_app.rs
rustc -O some_app.rs
./some_app

USAGE:
cranefack compile [FLAGS] [OPTIONS] <FILE>
FLAGS:
--debug-optimizations Print statistics for optimization passes
-v, --verbose --wrapping-is-ub Wrapping overflows are undefined behavior during optimization
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-f, --format <format> Format of compiled code [default: dump] [possible values: dump, clir, rust]
--jit-level <level> Optimization level for JIT [possible values: none, speed, speed_and_size]
-O <mode> Optimization mode [default: 2] [possible values: 0, 1, 2, 3, s, wtf]
ARGS:
<FILE> Brainfuck source file. Use - to read from stdin

Benchmark

Runs a program with different optimization settings and returns a table this the time for each program run.

USAGE:
cranefack benchmark [FLAGS] [OPTIONS] <FILE>
FLAGS:
-j, --jit Only benchmark jit
-o, --optimized-only Don't benchmark O0
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-i, --iterations <ITERATIONS> Number of benchmarking iterations [default: 2]
-r, --runs <RUNS> Number of runs per optimization in each round [default: 4]
ARGS:
<FILE> Brainfuck source file. Use - to read from stdin

Use cranefack as a library

To use cranefack as a library add the following to your Cargo.toml dependencies:

cranefack = "0.4"

To run a program with jit compilation:

use std::error::Error;use cranefack::{parse, optimize_with_config,OptimizeConfig,CompiledJitModule};fnmain() -> Result<(),Box<dynError>>{// Parse programletmut program = parse("++[<].")?;// Create optimization config for level 2let opt_level = OptimizeConfig::o2();// Optimize with optimization level 2optimize_with_config(&mut program,&opt_level);// Compile program into modulelet module = CompiledJitModule::new(&program,&opt_level)?;// Execute compiled module reading from stdin and writing to stdout
module.execute(std::io::stdin(), std::io::stdout());Ok(())}

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in cranefack by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.