diff options
Diffstat (limited to 'src/lib.rs')
| -rw-r--r-- | src/lib.rs | 95 |
1 files changed, 93 insertions, 2 deletions
@@ -1,7 +1,97 @@ -//! Library to read and write protocol buffers data. +//! # Library to read and write protocol buffers data +//! +//! # 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: +//! +//! ``` +//! [dependencies] +//! protobuf = { version = "~2.0", features = ["with-bytes"] } +//! ``` +//! +//! 2. Enable bytes option +//! +//! with `Customize` when codegen is invoked programmatically: +//! +//! ```ignore +//! 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: +//! +//! ```ignore +//! 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. #![deny(missing_docs)] -#![deny(broken_intra_doc_links)] +#![deny(rustdoc::broken_intra_doc_links)] #[cfg(feature = "bytes")] extern crate bytes; @@ -90,6 +180,7 @@ mod zigzag; mod misc; mod buf_read_iter; +mod buf_read_or_reader; /// This symbol is in generated `version.rs`, include here for IDE #[cfg(never)] |