blob: af32486836272a8031223c3f3a228475531cee34 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
<!-- cargo-sync-readme start -->
# 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:
```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 -->
|
