Rust implementation of Google protocol buffers
Clone or download
Permalink
Failed to load latest commit information.
ci Self-check May 24, 2018
google-protobuf @ b5fbb74 Include original google protobuf May 6, 2018
perftest Fix perftest Sep 9, 2018
proto singular_field_option_box and singular_field_option codegen options Jun 17, 2018
protobuf-codegen-pure-test Use bytes version 0.4 in all crates which use bytes Jul 19, 2018
protobuf-codegen-pure message and repeated fields and public now Sep 8, 2018
protobuf-codegen message and repeated fields and public now Sep 8, 2018
protobuf-fuzz Use bytes version 0.4 in all crates which use bytes Jul 19, 2018
protobuf-serde serde: RepeatedField support Jun 16, 2018
protobuf-test-common json: properly print and parse map field Sep 9, 2018
protobuf-test json: `ignore_unknown_fields` parser options Sep 9, 2018
protobuf json: `ignore_unknown_fields` parser options Sep 9, 2018
protoc-rust message and repeated fields and public now Sep 8, 2018
protoc Disable all targets everywhere, so `build.rs` won't be executed twice May 28, 2018
.editorconfig editorconfig Sep 24, 2016
.gitignore Code cleanup/regorganization Jun 9, 2017
.gitmodules Include original google protobuf May 6, 2018
.rustfmt.toml Whe we can't use rustfmt Jun 27, 2017
.travis.yml protoc from proto2 is long gone Jun 17, 2018
CHANGELOG.md Update CHANGELOG.md Sep 9, 2018
Cargo.toml update-version is a separate crate now Jun 18, 2018
LICENSE.txt Add LICENSE Oct 25, 2013
README.md +help Jun 8, 2018
publish-all.sh Script to publish all crates May 11, 2018

README.md

rust-protobuf

Build Status crates.io version License

Protobuf implementation in Rust.

  • Written in pure rust
  • Generate rust code
  • Has runtime library for generated code (Coded{Input|Output}Stream impl)

About versions and branches

  • 2.0.* is the latest stable version
  • 1.7.* is previous stable version
  • 1.6.* was republished as 2.0.* and no longer maintained. Should be compatible with 2.0.*. If you are using 1.6.* please update to 2.0.*.
  • 1.5.* was republished as 1.7.* and no longer maintained. Should be compatible with 1.7.*. If you are using 1.5.* please update to 1.7.*.

1.7+ 2.* versions should follow semver conventions. However, if you are developing critical library it's probably better to specify version as ~2.0 (>= 2.0 and <= 2.1), but not as 2.0 (>= 2.0 and <= 3.0).

Version 3.* will not follow semver conventions, releases from master will be published as 3.*. 3.* branch can be considered experimental.

Eventually some 3.* version will be stable enough and will be re-released as 4.0.

See CHANGELOG.md for a list of changes and compatility issues between versions.

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 (alpha)

Readme should be in protobuf-codegen-pure crate.

Use protoc-gen-rust plugin

Readme is here.

Generated code

Have a look at generated files, used internally in rust-protobuf:

Rustdoc

docs.rs hosts rustdoc for protobuf.

Getting help

Feel free to open an issue if you need help with rust-protobuf.

Copy-on-write

Rust-protobuf can be used with bytes crate.

To enable Bytes you need to:

  1. Enable with-bytes feature in rust-protobuf:
[dependencies]
protobuf = { version = "~2.0", features = ["with-bytes"] }
  1. 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.

serde_derive support

(Only in master, not released yet)

Rust-protobuf can be used with serde.

To enable serde you need to:

  1. Enable serde option

with Customize when codegen is invoked programmatically:

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

or in .proto file:

import "rustproto.proto";

option (rustproto.serde_derive_all) = true;

You may now Serialize and Deserialize messages:

let my_message = MyMessage::new();
serde_json::to_string(&my_message).unwrap();

Related projects