diff options
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 97 |
1 files changed, 93 insertions, 4 deletions
@@ -1,6 +1,95 @@ -## How to develop rust-protobuf itself +<!-- cargo-sync-readme start --> -`cargo test --all` to build everything. +# Library to read and write protocol buffers data -If code generator is changed, code needs to be regenerated, see -`regenerate.sh`. +# Version 2 is stable + +Currently developed branch of rust-protobuf [is 3](https://docs.rs/protobuf/%3E=3.0.0-alpha). +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](https://github.com/stepancheg/rust-protobuf/issues/518). + +# 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](https://docs.rs/protoc-rust/=2). + +## Use pure rust protobuf parser and code generator + +Readme should be in +[protobuf-codegen-pure crate](https://docs.rs/protobuf-codegen-pure/=2). + +## Use protoc-gen-rust plugin + +Readme is [here](https://docs.rs/protobuf-codegen/=2). + +## Generated code + +Have a look at generated files (for current development version), +used internally in rust-protobuf: + +* [descriptor.rs](https://github.com/stepancheg/rust-protobuf/blob/master/protobuf/src/descriptor.rs) + for [descriptor.proto](https://github.com/stepancheg/rust-protobuf/blob/master/protoc-bin-vendored/include/google/protobuf/descriptor.proto) + (that is part of Google protobuf) + +# Copy on write + +Rust-protobuf can be used with [bytes crate](https://github.com/tokio-rs/bytes). + +To enable `Bytes` you need to: + +1. Enable `with-bytes` feature in rust-protobuf: + +```rust +[dependencies] +protobuf = { version = "~2.0", features = ["with-bytes"] } +``` + +2. Enable bytes option + +with `Customize` when codegen is invoked programmatically: + +```rust +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: + +```rust +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`](https://docs.rs/protoc-rust/=2) + and [`protobuf-codegen-pure`](https://docs.rs/protobuf-codegen-pure/=2) + can be used to rust code from `.proto` crates. +* [`protobuf-codegen`](https://docs.rs/protobuf-codegen/=2) for `protoc-gen-rust` protoc plugin. +* [`protoc`](https://docs.rs/protoc/=2) crate can be used to invoke `protoc` programmatically. +* [`protoc-bin-vendored`](https://docs.rs/protoc-bin-vendored/=2) contains `protoc` command + packed into the crate. + +<!-- cargo-sync-readme end --> |