Crate flatbuffers_build

This crate provides a set of functions to facilitate compiling flatbuffers to Rust from within Rust. This is particularly helpful for use in build.rs scripts. Please note that for compatiblity this crate will only support a single version of the flatc compiler. Please check what version that is against whatever version is installed on your system.That said, due to flatbuffers’ versioning policy, it could be ok to mix patch and even minor versions.

Usage

If you’re not sure where to start, take a look at BuilderOptions. Please also look at the flatbuffers-example folder in the repo for an example. However, we’ll explain the full functionality here.

As an example, imagine a crate with the following folder structure:

├── build.rs
├── Cargo.toml
├── schemas
│   ├── example.fbs
│   └── weapon.fbs
└── src
    └── main.rs

In order to compile and use the code generated from both example.fbs and weapon.fbs, first you need to add flatbuffers-build to your build dependencies, as well as a matching version of flatbuffers:

# Cargo.toml
# [...]
[dependencies]
flatbuffers = "=23.5.26"

[build-dependencies]
flatbuffers-build = "=23.5.26"
# [...]

You can then have a very simple build.rs as follows:

use flatbuffers_build::BuilderOptions;

BuilderOptions::new_with_files(["schemas/weapon.fbs", "schemas/example.fbs"])
    .set_symlink_directory("src/gen_flatbuffers")
    .compile()
    .expect("flatbuffer compilation failed");

Note here that weapon.fbs and example.fbs are based on the schemas provided by flatbuffers as an example. The namespace is MyGame.Sample and it contains multiple tables and structs, including a Monster table.

This will just compile the flatbuffers and drop them in ${OUT_DIR}/flatbuffers and will create a symlink under src/gen_flatbuffers. You can then use them in lib.rs like so:

#[allow(warnings)]
mod gen_flatbuffers;

use gen_flatbuffers::my_game::sample::Monster;

fn some_fn() {
    // Make use of `Monster`
}

Note that since this will generate a symlink under src/gen_flatbuffers, you need to add this file to your gitignore as this symlink will dynamically change at runtime.

On file ordering

Unfortunately due to a quirk in the flatc compiler the order you provide the fbs files does matter. From some experimentation, the guidance is to always list files after their dependencies. Otherwise, the resulting mod.rs will be unusable. As an example, we have a weapon.fbs and example.fbs. Since the latter has an include directive for weapon.fbs, it should go after in the list. If you were to put example.fbs before weapon.fbs, you’d end up only being able to import the contents of weapon.fbs and with compilation errors if you tried to use any other components.

Structs

• BuilderOptions
  Builder for options to the flatc compiler options. When consumed using BuilderOptions::compile, this generates rust code from the flatbuffer definition files provided. The basic usage for this struct looks something like this:

Enums

• Error
  Primary error type returned when you compile your flatbuffer specifications to Rust.

Constants

• SUPPORTED_FLATC_VERSION
  Version of flatc supported by this library. Make sure this matches exactly with the flatc binary you’re using and the version of the flatbuffers rust library.

Type Aliases

• Result
  Alias for a Result that uses Error as the default error type.