Planus – alternative flatbuffer implementation

Planus is an alternative compiler for flatbuffers, an efficient cross platform serialization library.

Getting started

First, install the command line utility

shell cargo install planus-cli

Next, write a flatbuffers file (or use an existing one). Then you can generate code using the command

shell planus rust -o <output_path.rs> <input_file.fbs>

For a complete example, see examples/rust.

Features

• planus view: a TUI viewer for serialized flatbuffer files

To use it you need to specify the .fbs file, the root type and the binary file:

shell planus view test/rust/test_files/alignment.fbs Root test/rust/test_files/alignment/serialize/alignment.bin

• planus format: formatter for .fbs files

• planus check: check validity of .fbs files with good error messages

• planus dot: generate a DOT graph for .fbs files

• planus rust: generate Rust bindings for .fbs files

Goals

• User experience: Our command-line interface has excellent error and help messages. We aim to output good error messages even for non-supported features.
• Idiomatic code: We want to generate highly idiomatic code that should be very familiar to programmers of the target programming language.
• Safety: Any undefined/unsafe behavior in the generated code is considered a critical bug.
• Performance: We want to be at least as performant as the official implementation.
• Modularity: We have written our code such that parsing, validation and translation are clearly separated. We hope this will make it easy to implement additional backends with full support.
• Opinionated: We are in some cases more strict than the official implementation.
• Developer tools: We want to build good developer tools using our library. This includes at least a schema formatter and a tool to output a DOT graph of the types in a schema.
• Rust: By choosing to use Rust for our compiler, we are able to utilize excellent crates such as clap, LALRPOP and codespan as force multipliers.

Non-goals

• Full feature parity: Certain features are difficult to re-implement in a clean fashion.
• API-level compatibility: We aim for binary-level compatibility, but the code we generate will not works directly with the APIs of the official implementation.
• Language-specific extensions: We do not plan to support any extensions that break support between different languages.
• Validation-free access: Validation-free access makes it very easy to shoot yourself in the foot. We will not provide such APIs.

Languages supported

Currently we only support Rust, though we plan to add support for more languages in the future. Pull requests are welcome!

Community

Before contributing or participating in discussions with the community, you should familiarize yourself with the Code of Conduct we follow in this project.

• Discord: Planus' official discord server.
• GitHub Discussions: The best place for complex discussions about planus.

If you would like to contribute, please open an issue or pull request to discuss your idea.

For more more open-ended questions or complex decisions, feel free to open a Github Discussion or ping the developers on Discord.

Status of the implementation

We support most of the base language, though some parts have not been tested in-depth.

Things we do not currently support:

• rpc_service
• file_extension, file_identifier and root_type
• Fixed-size arrays
• Vectors of unions
• Any attribute besides required, deprecated, id or force_align.
• Some of the more exotic literal values, like hexadecimal floats or unicode surrogate pair parsing.
• JSON conversion.

Things we will probably never support:

• native_includes
• More than one namespace per file.
• Flexbuffers.

Minimum Supported Rust Version (MSRV)

Our current Minimum Supported Rust Version is 1.64.0. When adding features, we will follow these guidelines:

• We will aim to support the latest five minor Rust versions. This gives you a 6 month window to upgrade your compiler.
• Any change to the MSRV will be accompanied with a minor version bump
• While the crate is pre-1.0, this will be a change to the patch version.

I think I found a bug!

Please file an issue! We also consider poor error messages or unintuitive behavior to be high-priority bugs.