6 releases (1 stable)
1.0.0 | Sep 29, 2024 |
---|---|
0.4.0 | Jun 3, 2023 |
0.3.1 | Jun 16, 2022 |
0.3.0 | Feb 6, 2022 |
0.1.0 | Dec 30, 2021 |
#523 in Encoding
186 downloads per month
445KB
11K
SLoC
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
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.
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:
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
androot_type
- Fixed-size arrays
- Vectors of unions
- Any attribute besides
required
,deprecated
,id
orforce_align
. - Some of the more exotic literal values, like hexadecimal floats or unicode surrogate pair parsing.
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.70.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
I think I found a bug!
Please file an issue! We also consider poor error messages or unintuitive behavior to be high-priority bugs.
Dependencies
~13–24MB
~313K SLoC