rust-protobuf
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 version1.7.*
is previous stable version1.6.*
was republished as2.0.*
and no longer maintained. Should be compatible with2.0.*
. If you are using1.6.*
please update to2.0.*
.1.5.*
was republished as1.7.*
and no longer maintained. Should be compatible with1.7.*
. If you are using1.5.*
please update to1.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:
- descriptor.rs for descriptor.proto (that is part of Google 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:
- 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.
serde_derive support
(Only in master, not released yet)
Rust-protobuf can be used with serde.
To enable serde
you need to:
- 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
- quick-protobuf — alternative protobuf implementation in Rust
- prost — another protobuf implementation in Rust
- serde-protobuf
- grpc-rust — implementation of gRPC based on this library
- grpc-rs — another gRPC implementation for Rust