1 //! # Library to read and write protocol buffers data 2 //! 3 //! # Version 2 is stable 4 //! 5 //! Currently developed branch of rust-protobuf [is 3](https://docs.rs/protobuf/%3E=3.0.0-alpha). 6 //! It has the same spirit as version 2, but contains numerous improvements like: 7 //! * runtime reflection for mutability, not just for access 8 //! * protobuf text format and JSON parsing (which rely on reflection) 9 //! * dynamic message support: work with protobuf data without generating code from schema 10 //! 11 //! Stable version of rust-protobuf will be supported until version 3 released. 12 //! 13 //! [Tracking issue for version 3](https://github.com/stepancheg/rust-protobuf/issues/518). 14 //! 15 //! # How to generate rust code 16 //! 17 //! There are several ways to generate rust code from `.proto` files 18 //! 19 //! ## Invoke `protoc` programmatically with protoc-rust crate (recommended) 20 //! 21 //! Have a look at readme in [protoc-rust crate](https://docs.rs/protoc-rust/=2). 22 //! 23 //! ## Use pure rust protobuf parser and code generator 24 //! 25 //! Readme should be in 26 //! [protobuf-codegen-pure crate](https://docs.rs/protobuf-codegen-pure/=2). 27 //! 28 //! ## Use protoc-gen-rust plugin 29 //! 30 //! Readme is [here](https://docs.rs/protobuf-codegen/=2). 31 //! 32 //! ## Generated code 33 //! 34 //! Have a look at generated files (for current development version), 35 //! used internally in rust-protobuf: 36 //! 37 //! * [descriptor.rs](https://github.com/stepancheg/rust-protobuf/blob/master/protobuf/src/descriptor.rs) 38 //! for [descriptor.proto](https://github.com/stepancheg/rust-protobuf/blob/master/protoc-bin-vendored/include/google/protobuf/descriptor.proto) 39 //! (that is part of Google protobuf) 40 //! 41 //! # Copy on write 42 //! 43 //! Rust-protobuf can be used with [bytes crate](https://github.com/tokio-rs/bytes). 44 //! 45 //! To enable `Bytes` you need to: 46 //! 47 //! 1. Enable `with-bytes` feature in rust-protobuf: 48 //! 49 //! ``` 50 //! [dependencies] 51 //! protobuf = { version = "~2.0", features = ["with-bytes"] } 52 //! ``` 53 //! 54 //! 2. Enable bytes option 55 //! 56 //! with `Customize` when codegen is invoked programmatically: 57 //! 58 //! ```ignore 59 //! protoc_rust::run(protoc_rust::Args { 60 //! ... 61 //! customize: Customize { 62 //! carllerche_bytes_for_bytes: Some(true), 63 //! carllerche_bytes_for_string: Some(true), 64 //! ..Default::default() 65 //! }, 66 //! }); 67 //! ``` 68 //! 69 //! or in `.proto` file: 70 //! 71 //! ```ignore 72 //! import "rustproto.proto"; 73 //! 74 //! option (rustproto.carllerche_bytes_for_bytes_all) = true; 75 //! option (rustproto.carllerche_bytes_for_string_all) = true; 76 //! ``` 77 //! 78 //! With these options enabled, fields of type `bytes` or `string` are 79 //! generated as `Bytes` or `Chars` respectively. When `CodedInputStream` is constructed 80 //! from `Bytes` object, fields of these types get subslices of original `Bytes` object, 81 //! instead of being allocated on heap. 82 //! 83 //! # Accompanying crates 84 //! 85 //! * [`protoc-rust`](https://docs.rs/protoc-rust/=2) 86 //! and [`protobuf-codegen-pure`](https://docs.rs/protobuf-codegen-pure/=2) 87 //! can be used to rust code from `.proto` crates. 88 //! * [`protobuf-codegen`](https://docs.rs/protobuf-codegen/=2) for `protoc-gen-rust` protoc plugin. 89 //! * [`protoc`](https://docs.rs/protoc/=2) crate can be used to invoke `protoc` programmatically. 90 //! * [`protoc-bin-vendored`](https://docs.rs/protoc-bin-vendored/=2) contains `protoc` command 91 //! packed into the crate. 92 93 #![deny(missing_docs)] 94 #![deny(rustdoc::broken_intra_doc_links)] 95 96 #[cfg(feature = "bytes")] 97 extern crate bytes; 98 #[cfg(feature = "with-serde")] 99 extern crate serde; 100 #[macro_use] 101 #[cfg(feature = "with-serde")] 102 extern crate serde_derive; 103 pub use crate::cached_size::CachedSize; 104 #[cfg(feature = "bytes")] 105 pub use crate::chars::Chars; 106 pub use crate::clear::Clear; 107 pub use crate::coded_input_stream::CodedInputStream; 108 pub use crate::coded_output_stream::CodedOutputStream; 109 pub use crate::enums::ProtobufEnum; 110 pub use crate::error::ProtobufError; 111 pub use crate::error::ProtobufResult; 112 #[allow(deprecated)] 113 pub use crate::message::parse_from_bytes; 114 #[cfg(feature = "bytes")] 115 #[allow(deprecated)] 116 pub use crate::message::parse_from_carllerche_bytes; 117 #[allow(deprecated)] 118 pub use crate::message::parse_from_reader; 119 #[allow(deprecated)] 120 pub use crate::message::parse_length_delimited_from; 121 #[allow(deprecated)] 122 pub use crate::message::parse_length_delimited_from_bytes; 123 #[allow(deprecated)] 124 pub use crate::message::parse_length_delimited_from_reader; 125 pub use crate::message::Message; 126 pub use crate::repeated::RepeatedField; 127 pub use crate::singular::SingularField; 128 pub use crate::singular::SingularPtrField; 129 pub use crate::unknown::UnknownFields; 130 pub use crate::unknown::UnknownFieldsIter; 131 pub use crate::unknown::UnknownValue; 132 pub use crate::unknown::UnknownValueRef; 133 pub use crate::unknown::UnknownValues; 134 pub use crate::unknown::UnknownValuesIter; 135 136 // generated 137 pub mod descriptor; 138 pub mod plugin; 139 pub mod rustproto; 140 141 pub mod wire_format; 142 143 mod clear; 144 mod coded_input_stream; 145 mod coded_output_stream; 146 pub mod compiler_plugin; 147 mod enums; 148 pub mod error; 149 pub mod ext; 150 pub mod json; 151 pub mod lazy; 152 mod lazy_v2; 153 mod message; 154 pub mod reflect; 155 mod repeated; 156 pub mod rt; 157 mod singular; 158 pub mod text_format; 159 pub mod types; 160 pub mod well_known_types; 161 mod well_known_types_util; 162 163 // used by test 164 #[cfg(test)] 165 #[path = "../../protobuf-test-common/src/hex.rs"] 166 mod hex; 167 168 // used by rust-grpc 169 pub mod descriptorx; 170 171 mod cached_size; 172 mod chars; 173 #[doc(hidden)] // used by codegen 174 pub mod rust; 175 mod strx; 176 mod unknown; 177 mod varint; 178 mod zigzag; 179 180 mod misc; 181 182 mod buf_read_iter; 183 mod buf_read_or_reader; 184 185 /// This symbol is in generated `version.rs`, include here for IDE 186 #[cfg(never)] 187 pub const VERSION: &str = ""; 188 /// This symbol is in generated `version.rs`, include here for IDE 189 #[cfg(never)] 190 #[doc(hidden)] 191 pub const VERSION_IDENT: &str = ""; 192 include!(concat!(env!("OUT_DIR"), "/version.rs")); 193