README.md
1# gRPC-rs
2
3`gRPC-rs` is a Rust wrapper of [gRPC Core](https://github.com/grpc/grpc). [gRPC](http://www.grpc.io) is a high performance, open source universal RPC framework that puts mobile and HTTP/2 first.
4
5[](https://crates.io/crates/grpcio)
6[](https://docs.rs/grpcio)
7[](https://github.com/tikv/grpc-rs/actions)
8[](https://travis-ci.org/tikv/grpc-rs)
9
10## Status
11
12This project is still under development. The following features with the check marks are supported:
13
14- [x] Basic asynchronous unary/steaming call
15- [x] SSL
16- [x] Generic call
17- [x] Connection level compression
18- [x] Interoperability test
19- [x] QPS benchmark
20- [ ] Custom metadata
21- [x] Health check
22- [ ] Reflection
23- [X] Authentication
24- [ ] Load balance, client side is fully supported, server side load report is not implemented yet.
25
26## Prerequisites
27
28- CMake >= 3.8.0
29- Rust >= 1.36.0
30- binutils >= 2.22
31- LLVM and Clang >= 3.9 if you need to generate bindings at compile time.
32
33For Linux and MacOS, you also need to install gcc 7.3+ (or clang 6+) too.
34
35Bindings are pre-generated for x86_64/arm64 Linux. For other platforms, bindings are generated at compile time.
36
37For Windows, you also need to install following software:
38
39- Active State Perl
40- yasm
41- Visual Studio 2015+
42
43## Build
44
45```
46$ cargo xtask submodule # if you just cloned the repository
47$ cargo build
48```
49
50### Error linking OpenSSL
51
52If you're getting linker errors when building your project using `gRPC-rs`, head
53down to the `openssl` feature section for a possible fix.
54
55## Usage
56
57To generate the sources from proto files:
58
59### Option 1 - Manual Generation
60
611. Install the protobuf compiler:
62
63```
64$ cargo install protobuf-codegen
65```
66
672. Install the gRPC compiler:
68
69```
70$ cargo install grpcio-compiler
71```
72
733. Generate the sources:
74
75```
76$ protoc --rust_out=. --grpc_out=. --plugin=protoc-gen-grpc=`which grpc_rust_plugin` example.proto
77```
78
79
80### Option 2 - Programmatic Generation
81
82Programmatic generation can be used to generate Rust modules from proto files
83via your `build.rs` by using [protoc-grpcio](https://crates.io/crates/protoc-grpcio).
84
85For more information and examples see
86[README](https://github.com/mtp401/protoc-grpcio/blob/master/README.md).
87
88To include this project as a dependency:
89
90```
91[dependencies]
92grpcio = "0.13"
93```
94
95### Feature `boringssl`
96
97`boringssl` feature enables support for TLS encryption and some authentication
98mechanism. When you do not need it, for example when working in intranet,
99you can disable it by using the following configuration:
100```
101[dependencies]
102grpcio = { version = "0.13", default-features = false, features = ["protobuf-codec"] }
103```
104
105### Feature `prost-codec` and `protobuf-codec`
106
107`gRPC-rs` uses `protobuf` crate by default. If you want to use `prost` instead, you can enable
108`prost-codec` feature. You probably only want to enable only one of the two features. Though
109grpcio is completely fine with both features enabled at the same time, grpcio-compiler
110will not going to work as expected.
111
112### Feature `openssl` and `openssl-vendored`
113
114`gRPC-rs` comes vendored with `gRPC Core`, which by default uses BoringSSL
115instead of OpenSSL. This may cause linking issues due to symbol clashes and/or
116missing symbols when another one of your dependencies uses OpenSSL. To resolve
117this, you can tell `gRPC-rs` to use OpenSSL too by specifying `"openssl"` in
118your `Cargo.toml`'s features list for `gprcio`, which requires openssl (>=1.0.2). E.g.:
119
120```toml
121[dependencies]
122grpcio = { version = "0.13", features = ["openssl"] }
123```
124
125Feature `openssl-vendored` is the same as feature `openssl` except it will build openssl from
126bundled sources.
127
128## Performance
129
130See [benchmark](https://github.com/tikv/grpc-rs/tree/master/benchmark) to find out how to run a benchmark by yourself.
131
132Cross Compile
133-------------
134See [cross_compile](cross_compile.md)
135
136Contributing
137------------
138
139Make sure to format and test the code before sending a PR.
140
141If the content in grpc-sys/grpc is updated, you may need to regenerate bindings:
142
143```
144$ cargo xtask bindgen
145```
146
){kind=link}
){kind=link}
){kind=link}
){kind=link}