# Cranefack
[](https://docs.rs/cranefack/)
[](https://crates.io/crates/cranefack/)
[](https://github.com/vstroebel/cranefack/actions/workflows/rust.yml)
A cranelift powered optimizing brainfuck compiler suite.
## Commandline interface
Cranefack provides a command line utility to run, compile and benchmark programs.
```shell
cargo install cranefack-cli
```
### Run
Run a program with interpreter or jit.<br>
Passing the `-v` option prints some statistics and execution time.
```text
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.<br>
As of now this will create an assembly like representation by default that is only useful for debugging.<br>
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:
```shell
cranefack compile -f=rust some_app.bf > some_app.rs
rustc -O some_app.rs
./some_app
```
```text
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.
```text
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:
```toml
cranefack = "0.2"
```
To run a program with jit compilation:
```rust
use std::error::Error;
use cranefack::{parse, optimize_with_config, OptimizeConfig, CompiledJitModule};
fn main() -> Result<(), Box<dyn Error>> {
// Parse program
let mut program = parse("++[<].")?;
// Create optimization config for level 2
let opt_level = OptimizeConfig::o2();
// Optimize with optimization level 2
optimize_with_config(&mut program, &opt_level);
// Compile program into module
let 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](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](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.