Graven

Getting started

Graven schemas (.graven) are language-neutral. The gravenc compiler validates schemas, tracks compatibility in <schema>.lock, inspects binary files, and generates code.

1. Install gravenc

cargo install graven-compiler

(Or from a source checkout: cargo build --release -p graven-compiler --bin gravenc.)

2. Write a schema and create its lockfile

Create schemas/bank.graven:

namespace bank;

enum Currency : u16 { BRL = 0, USD = 1, EUR = 2 }

table Entry {
  account @0: u64;
  amount  @1: i64;
  memo    @2: string?;
}

table Transaction {
  id         @0: u64;
  ts         @1: u64;
  currency   @2: Currency;
  from_shard @3: u32;
  to_shard   @4: u32;
  entries    @5: [Entry];
  note       @6: string?;
}

Initialize its lockfile once:

gravenc update schemas/bank.graven --init

The lockfile (schemas/bank.graven.lock) records every table's schema_id, fixed-part layout, defaults, and validation rules. Commit it alongside your .graven files.

3. Evolve, check, and generate

Because <schema>.lock records the resolved layout and schema_ids, generators for other languages can target the lockfile directly without reimplementing the layout rules.

Option: Rust project (Cargo.toml + build.rs)

If you are using Rust, you can run code generation automatically during cargo build instead of invoking gravenc gen manually:

  1. Install the compiler: cargo install graven-compiler (provides gravenc). Add the runtime and the code generator to your crate's Cargo.toml:

    [dependencies]
graven = "0.2"

[build-dependencies]
graven-compiler = "0.2"

  2. Write schemas/bank.graven and create its lockfile once: gravenc update schemas/bank.graven --init.

  3. Generate code from build.rs (it reads the lock and never writes it):

    fn main() {
    graven_compiler::build::Build::new()
        .schema("schemas/bank.graven")
        .compile()
        .unwrap_or_else(|e| panic!("{e}"));
}

  4. Include the generated file alone in its own module:

    pub mod bank {
    include!(concat!(env!("OUT_DIR"), "/bank.rs"));
}

  5. When the schema changes, run gravenc update schemas/bank.graven: it checks compatibility against the lock before rewriting it. In CI, gravenc check --locked schemas/*.graven.

Next steps