A Flattened Representation for Bril

(Final project for CS 6120 (Advanced Compilers), Spring 2025.)

This repo contains:

• A flattened representation for the Bril IR
• An interpreter that works natively over the flattened Bril representation
• Infrastructure for converting to/from Bril's canonical JSON format to the flattened representation

For more details, see the blog post for this project!

Repo structure

• main.rs: Reads in a JSON Bril file from stdin
• flatten.rs: Converts a JSON Bril file to a flattened instruction format
• unflatten.rs: Converts a flattened Bril instruction back to JSON
• memfile.rs: Serializes/De-serializes a flattened Bril file to/from disk
• interp.rs: Bril interpreter which works over the flattened Bril representation
• types.rs: Type definitions & pretty-printers
• json_roundtrip.rs: Round-trip tests for converting from JSON -> flat format -> JSON
• bench.py, plot_results.py, bench.sh: Miscellaneous Python/Bash scripts for running benchmarks (using Hyperfine) and plotting

The test subdirectory contains the Core Bril benchmarks on which we tested our implementation and compared its performance to the reference TypeScript / Rust Brili interpreters.

Command-line interface

• To install flat-bril, run cargo install --path . and make sure $HOME/.cargo/bin is on your path.
• Run flat-bril --help to see all the supported flags.

Here are some examples:

• To create a flattened Bril file (.fbril) from an existing Bril file (eg. on call.bril):

$ bril2json < test/call.bril | cargo run -- --filename test/call.fbril --fbril

• To interpret a flattened Bril file:

$ cargo run -- --filename test/call.fbril --interp

• To check that the JSON round-trip test works for a single Bril file:

$ bril2json < test/call.bril | cargo run -- --json

Building & Testing

• This repo compiles using cargo build. Run cargo doc --open to see documentation for internal functions.
• Run turnt -e interp test/*.bril to check that our flattened interpreter returns the same result as the reference Brili interpreter on the Core Bril benchmarks
• Run turnt -e json test/*.bril to run JSON round-trip tests on all the Core Bril benchmarks

---

**Other stuff in the repo (existing Bril infrastructure): **

• bril-rs: existing JSON to Bril infra
• brilirs: existing Bril interpreter
• bril2json: existing bril2json tool