5 releases (3 breaking)
|0.4.0||Jun 3, 2023|
|0.3.1||Jun 16, 2022|
|0.3.0||Feb 6, 2022|
|0.2.0||Jan 12, 2022|
|0.1.0||Dec 30, 2021|
#206 in Encoding
25 downloads per month
Planus – alternative flatbuffer implementation
Planus is an alternative compiler for flatbuffers, an efficient cross platform serialization library.
First, install the command line utility
cargo install planus-cli
Next, write a flatbuffers file (or use an existing one). Then you can generate code using the command
planus rust -o <output_path.rs> <input_file.fbs>
For a complete example, see examples/rust.
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:
planus view test/rust/test_files/alignment.fbs Root test/rust/test_files/alignment/serialize/alignment.bin
planus format: formatter for
planus check: check validity of
.fbsfiles with good error messages
planus dot: generate a DOT graph for
planus rust: generate Rust bindings for
- 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.
- 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.
Currently we only support Rust, though we plan to add support for more languages in the future. Pull requests are welcome!
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:
- Fixed-size arrays
- Vectors of unions
- Any attribute besides
- Some of the more exotic literal values, like hexadecimal floats or unicode surrogate pair parsing.
- JSON conversion.
Things we will probably never support:
- More than one
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.