1<!-- cargo-sync-readme start --> 2 3# Library to read and write protocol buffers data 4 5# Version 2 is stable 6 7Currently developed branch of rust-protobuf [is 3](https://docs.rs/protobuf/%3E=3.0.0-alpha). 8It has the same spirit as version 2, but contains numerous improvements like: 9* runtime reflection for mutability, not just for access 10* protobuf text format and JSON parsing (which rely on reflection) 11* dynamic message support: work with protobuf data without generating code from schema 12 13Stable version of rust-protobuf will be supported until version 3 released. 14 15[Tracking issue for version 3](https://github.com/stepancheg/rust-protobuf/issues/518). 16 17# How to generate rust code 18 19There are several ways to generate rust code from `.proto` files 20 21## Invoke `protoc` programmatically with protoc-rust crate (recommended) 22 23Have a look at readme in [protoc-rust crate](https://docs.rs/protoc-rust/=2). 24 25## Use pure rust protobuf parser and code generator 26 27Readme should be in 28[protobuf-codegen-pure crate](https://docs.rs/protobuf-codegen-pure/=2). 29 30## Use protoc-gen-rust plugin 31 32Readme is [here](https://docs.rs/protobuf-codegen/=2). 33 34## Generated code 35 36Have a look at generated files (for current development version), 37used internally in rust-protobuf: 38 39* [descriptor.rs](https://github.com/stepancheg/rust-protobuf/blob/master/protobuf/src/descriptor.rs) 40 for [descriptor.proto](https://github.com/stepancheg/rust-protobuf/blob/master/protoc-bin-vendored/include/google/protobuf/descriptor.proto) 41 (that is part of Google protobuf) 42 43# Copy on write 44 45Rust-protobuf can be used with [bytes crate](https://github.com/tokio-rs/bytes). 46 47To enable `Bytes` you need to: 48 491. Enable `with-bytes` feature in rust-protobuf: 50 51```rust 52[dependencies] 53protobuf = { version = "~2.0", features = ["with-bytes"] } 54``` 55 562. Enable bytes option 57 58with `Customize` when codegen is invoked programmatically: 59 60```rust 61protoc_rust::run(protoc_rust::Args { 62 ... 63 customize: Customize { 64 carllerche_bytes_for_bytes: Some(true), 65 carllerche_bytes_for_string: Some(true), 66 ..Default::default() 67 }, 68}); 69``` 70 71or in `.proto` file: 72 73```rust 74import "rustproto.proto"; 75 76option (rustproto.carllerche_bytes_for_bytes_all) = true; 77option (rustproto.carllerche_bytes_for_string_all) = true; 78``` 79 80With these options enabled, fields of type `bytes` or `string` are 81generated as `Bytes` or `Chars` respectively. When `CodedInputStream` is constructed 82from `Bytes` object, fields of these types get subslices of original `Bytes` object, 83instead of being allocated on heap. 84 85# Accompanying crates 86 87* [`protoc-rust`](https://docs.rs/protoc-rust/=2) 88 and [`protobuf-codegen-pure`](https://docs.rs/protobuf-codegen-pure/=2) 89 can be used to rust code from `.proto` crates. 90* [`protobuf-codegen`](https://docs.rs/protobuf-codegen/=2) for `protoc-gen-rust` protoc plugin. 91* [`protoc`](https://docs.rs/protoc/=2) crate can be used to invoke `protoc` programmatically. 92* [`protoc-bin-vendored`](https://docs.rs/protoc-bin-vendored/=2) contains `protoc` command 93 packed into the crate. 94 95<!-- cargo-sync-readme end --> 96