Planus – 平坦缓冲区的替代实现

Planus 是一个针对 flatbuffers（一个高效的跨平台序列化库）的替代编译器。

入门指南

首先，安装命令行工具

cargo install planus-cli

然后，编写一个 flatbuffers 文件（或使用现有的一个）。然后可以使用以下命令生成代码：

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

有关完整示例，请参阅 examples/rust。

功能

• planus view：用于序列化 flatbuffer 文件的 TUI 查看器

使用时，需要指定 .fbs 文件、根类型和二进制文件

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

• planus format：用于格式化 .fbs 文件

• planus check：通过良好的错误消息检查 .fbs 文件的合法性

• planus dot：为 .fbs 文件生成 DOT 图

• planus rust：为 .fbs 文件生成 Rust 绑定

目标

• 用户体验：我们的命令行界面具有出色的错误和帮助信息。我们的目标是输出良好的错误信息，即使是非支持功能。
• 代码风格：我们希望生成高度符合目标编程语言程序员习惯的代码。
• 安全性：生成的代码中任何未定义/不安全的行为都被视为关键错误。
• 性能：我们希望至少与官方实现一样高效。
• 模块化：我们编写代码的方式使得解析、验证和转换清晰分离。我们希望这将使得实现具有完全支持的额外后端变得容易。
• 有争议的：在某些情况下，我们比官方实现更为严格。
• 开发者工具：我们希望使用我们的库构建良好的开发者工具。这至少包括一个模式格式化器和用于输出模式中类型 DOT 图 的工具。
• Rust：选择使用Rust作为我们的编译器，我们可以利用诸如clap、LALRPOP和codespan等出色的crate作为力量倍增器。

非目标

• 完整功能一致性：某些功能难以以干净的方式重新实现。
• API级别兼容性：我们旨在实现二进制级别的兼容性，但我们生成的代码将无法直接与官方实现的API兼容。
• 语言特定扩展：我们不计划支持任何会破坏不同语言之间支持的扩展。
• 无验证访问：无验证访问使得自伤很容易发生。我们将不会提供此类API。

支持的语言

目前我们只支持Rust，尽管我们计划在未来添加更多语言的支持。欢迎提交pull请求！

社区

在贡献或与社区进行讨论之前，您应该熟悉我们在本项目遵循的行为准则。

• Discord：Planus的官方Discord服务器。
• GitHub Discussions：关于planus的复杂讨论的最佳场所。

如果您想贡献，请打开一个issue或pull request来讨论您的想法。

对于更开放的问题或复杂的决定，您可以自由地打开一个Github讨论或在Discord上ping开发者。

实现状态

我们支持大多数基本语言，尽管某些部分尚未进行深入测试。

我们不支持的功能

• rpc_service
• file_extension、file_identifier和root_type
• 固定大小数组
• 联合类型的向量
• 除了required、deprecated、id或force_align之外的任何属性。
• 一些更特殊的字面值，如十六进制浮点数或Unicode代理对解析。
• JSON转换。

我们可能永远不会支持的功能

• native_includes
• 每个文件中超过一个namespace。
• Flexbuffers。

最低支持的Rust版本（MSRV）

我们当前的最低支持的Rust版本是1.64.0。在添加功能时，我们将遵循以下准则

• 我们旨在支持最新的五个次要Rust版本。这为您提供了6个月的时间来升级您的编译器。
• 对MSRV的任何更改都将伴随着小版本的提升
• 在crate为1.0之前，这将是对补丁版本的更改。

我认为我找到了一个bug！

请提交一个issue！我们还将将错误信息不清晰或难以理解的行为视为高优先级的bug。