是什么

该仓库包含一个CLI，使用tonic-build从protobuf文件生成Rust代码。
tonic-build已经可以这样做，该CLI是该前端，增加了一些代码以确保生成的文件放置在有效路径，并处理模块结构。

为什么

prost-build曾经附带cmake，我们想避免使用它。
cmake用于构建protoc，然后用于从protobuf到Rust代码的生成。
prost维护者的最终决定是，用户应提供自己的protoc并将代码签入，而不是在build.rs中构建，为了简化此过程，创建了此CLI。

如何

使用路径上的本地protoc版本从CLI传递的工作区规范生成Rust代码。CLI还可以用于验证生成的Rust代码与源协议文件，例如在CI中。

注意事项

此工具存在一些问题，目前它是我们Protobuf管道的最佳替代方案，以下是一些需要考虑的事项。

需要在用户机器上手动安装

运行此工具至少需要用户机器上安装protoc，野外的许多协议缓冲区文件都依赖于其他.proto文件的形式。这些文件也必须被引用。
你可能想要构建的许多.proto文件依赖于google.protobuf 类型，许多.proto作者假设这些类型对用户可用，但这可能并不总是正确的。

关于在这里引入它们的讨论已经展开，因为它们非常常见，但到目前为止还没有进行任何引入，因为它们在许多情况下不是强制性的。

一个折中的方案是自己引入依赖的proto文件，并指定放置这些.proto文件的目录来运行此工具（使用-d my-dep-dir）。

如果Tonic版本已更改（即使是次要版本）版本不兼容

在Tonic的次要版本中，有时会进行注释或其他非功能性更改，这将导致validate命令拒绝由本工具较低版本生成的旧protos，需要重新生成。
可以争论说，因此Tonic的次要版本更改对本工具来说成为了一次重大版本更改，尽管这可能有点哲学性，因为生成的代码是相同的。

文档注释被执行

Tonic将protobuf注释转换为文档注释，如果其中包含代码示例，则当在cargo test（doc-test阶段）运行时，cargo将尝试执行它们。
与使用tonic-build不同，因为那些文档注释是在cargo不会尝试运行它们的地方生成的。
运行它们几乎总是保证会失败（因为它们将是非Rust代码或根本不是代码），在最坏的情况下，如果有人在文档注释中插入恶意Rust代码，这将是一个隐藏的安全漏洞。

理想情况下，可以根据模块禁用运行doc-test会更容易。将生成的protos放置在单独的lib中，该lib不运行文档注释是一个更安全的选项，尽管doc-tests是可选的将更加安全。

用法

从一个.proto文件生成到项目中。

本项目中的示例

cargo r -r -p proto-gen -- generate -d examples/example-project/proto -f examples/example-project/proto/my-proto.proto -o examples/example-project/src/proto_types

这将从examples/example-project/proto/my-proto.proto中指定的proto生成Rust代码，并将其放置在examples/example-project/src/proto_types中。

cargo r -r -p proto-gen -- validate -d examples/example-project/proto -f examples/example-project/proto/my-proto.proto -o examples/example-project/src/proto_types

这将还生成Rust代码（到临时目录）并运行与examples/example-project/src/proto_types中包含的代码的diff。如果找到任何差异，它将以错误代码1和消息退出。

如果我们想使用包含文件，需要指定包含目录。

cargo r -r -p proto-gen -- generate -d examples/example-project/dep_protos -d examples/example-project/proto_with_deps -f examples/example-project/proto_with_deps/my-proto.proto -o examples/example-project/src/proto_types

这里我们传递了两次-d，一次用于包含依赖proto文件，一次用于包含我们想要生成的proto文件。

cargo r -r -p proto-gen -- validate -d examples/example-project/dep_protos -d examples/example-project/proto_with_deps -f examples/example-project/proto_with_deps/my-proto.proto -o examples/example-project/src/proto_types

贡献

我们欢迎社区对本项目的贡献。

请阅读我们的贡献指南，了解如何开始。在您做出任何贡献之前，也请阅读我们的贡献条款。

任何有意提交以包含在Embark Studios项目中的贡献，必须遵守Rust标准许可模型（MIT或Apache 2.0），因此将双许可，如下所述，不附加任何额外条款或条件

许可

本贡献在以下两者中双许可

• Apache许可证第2版，(LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任您选择。

为了明确，“您的”指的是Embark或任何其他贡献的许可方/用户。