protobuf 包的 Protobuf 代码生成器

此包主要从 build.rs 脚本中生成 .rs 文件时使用。

如何生成代码

从 .proto 文件生成 .rs 文件主要有三种主要方式

• 使用 protoc 命令行工具和 protoc-gen-rust 插件
• 使用此包 Codegen 与纯 Rust 解析器
• 使用此包 Codegen 与 protoc 解析器

您应该使用哪种取决于您的需求。

如果您使用非 cargo 构建系统（如 Bazel），您可能更喜欢使用 protoc-gen-rust 插件。

如果您使用 cargo 构建，您可能希望使用此包中的 Codegen。

Protoc 解析器与纯 Rust 解析器

此包可以插入两个 protobuf 解析器

• protoc-基于的解析器（protoc 是 Google protobuf 的命令行工具）
• 纯 Rust 解析器（protobuf-parse crate）

protoc-基于的解析器预计可以非常正确地解析 .proto 文件：所有 Google 的 protobuf 实现都依赖于它。

尽管在 protobuf-parse 中没有已知错误，但它没有得到很好的测试。此外，protobuf-parse 没有实现 .proto 解析器的一些很少使用的功能，主要是 .proto 文件中指定的复杂消息选项。我从未见过有人使用它们，但您已经被警告。

注意，可以从 protoc-bin-vendored crate 获取 protoc 命令。

示例

// Use this in build.rs
protobuf_codegen::Codegen::new()
    // Use `protoc` parser, optional.
    .protoc()
    // Use `protoc-bin-vendored` bundled protoc command, optional.
    .protoc_path(&protoc_bin_vendored::protoc_bin_path().unwrap())
    // All inputs and imports from the inputs must reside in `includes` directories.
    .includes(&["src/protos"])
    // Inputs must reside in some of include paths.
    .input("src/protos/apple.proto")
    .input("src/protos/banana.proto")
    // Specify output directory relative to Cargo output directory.
    .cargo_out_dir("protos")
    .run_from_script();

如何使用 protoc-gen-rust

如果需要的话。

（注意，可以通过 protoc crate 以编程方式调用 protoc）

0. 为 protoc 二进制文件安装 protobuf。

在 OS X 上，可以使用 Homebrew

brew install protobuf

在 Ubuntu 上，可以安装 protobuf-compiler 包

apt-get install protobuf-compiler

Protobuf 仅用于代码生成，rust-protobuf 运行时不需要 C++ protobuf 库。

1. 安装 protoc-gen-rust 程序（它是 protoc 插件）

可以从源代码安装或使用 cargo install protobuf-codegen 命令安装。

2. 将 protoc-gen-rust 添加到 $PATH

如果您使用 cargo 安装，应该是这样的

PATH="$HOME/.cargo/bin:$PATH"

3. 生成 .rs 文件

protoc --rust_out . foo.proto

这将在当前目录中生成 .rs 文件。

自定义生成代码

有时生成的代码需要调整，例如，以拥有自定义的 derive。

rust-protobuf 提供了两种方法来实现这一点

• 生成的 .rs 文件包含 @@protoc_insertion_point(...) 标记（类似于 Google 的 protobuf 生成器为 C++ 或 Java 插入的标记）。可以使用简单的 sed 单行脚本来用自定义注解替换这些标记。
• Codegen::customize_callback 可以在从 build.rs 脚本调用时用来修补生成的代码。

Serde

从版本 3 开始，rust-protobuf 不再直接支持 serde。

Rust-protobuf 3 完全支持

• 运行时反射
• 通过 protobuf-json-mapping 进行 JSON 解析和打印

这涵盖了大部分 serde 用例。

如果您仍然需要 serde，可以使用通用的自定义回调（见上文）来插入 #[serde(...)] 注解。

在 rust-protobuf 存储库中的 示例项目 展示了如何实现它。