commit	0af506eab5a6d52635e775e0ad9b6439da826a3a	[log] [tgz]
author	David LeGare <legare@google.com>	Mon Mar 07 15:23:26 2022 +0000
committer	Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>	Mon Mar 07 15:23:26 2022 +0000
tree	f0d3f05c18afd04b9824b485585518fe06641ee1
parent	6dd1c2138911f1f67cdd13a5944e858c7e14f2b9 [diff]
parent	b339df415eca5be903110599f85a188faf522f4d [diff]

tree: f0d3f05c18afd04b9824b485585518fe06641ee1

README.md

Library to read and write protocol buffers data

Version 2 is stable

Currently developed branch of rust-protobuf is 3. It has the same spirit as version 2, but contains numerous improvements like:

runtime reflection for mutability, not just for access
protobuf text format and JSON parsing (which rely on reflection)
dynamic message support: work with protobuf data without generating code from schema

Stable version of rust-protobuf will be supported until version 3 released.

Tracking issue for version 3.

How to generate rust code

There are several ways to generate rust code from .proto files

Invoke `protoc` programmatically with protoc-rust crate (recommended)

Have a look at readme in protoc-rust crate.

Use pure rust protobuf parser and code generator

Readme should be in protobuf-codegen-pure crate.

Use protoc-gen-rust plugin

Readme is here.

Generated code

Have a look at generated files (for current development version), used internally in rust-protobuf:

descriptor.rs for descriptor.proto (that is part of Google protobuf)

Copy on write

Rust-protobuf can be used with bytes crate.

To enable Bytes you need to:

Enable with-bytes feature in rust-protobuf:

[dependencies]
protobuf = { version = "~2.0", features = ["with-bytes"] }

Enable bytes option

with Customize when codegen is invoked programmatically:

protoc_rust::run(protoc_rust::Args {
    ...
    customize: Customize {
        carllerche_bytes_for_bytes: Some(true),
        carllerche_bytes_for_string: Some(true),
        ..Default::default()
    },
});

or in .proto file:

import "rustproto.proto";

option (rustproto.carllerche_bytes_for_bytes_all) = true;
option (rustproto.carllerche_bytes_for_string_all) = true;

With these options enabled, fields of type bytes or string are generated as Bytes or Chars respectively. When CodedInputStream is constructed from Bytes object, fields of these types get subslices of original Bytes object, instead of being allocated on heap.

Accompanying crates

protoc-rust and protobuf-codegen-pure can be used to rust code from .proto crates.
protobuf-codegen for protoc-gen-rust protoc plugin.
protoc crate can be used to invoke protoc programmatically.
protoc-bin-vendored contains protoc command packed into the crate.