README.android
1The patch in patches/env.diff needs to be updated with crate version update to match
2the new crate version.
3
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- By default, the [secure feature](#feature-secure) is provided by boringssl. You can also use openssl instead by enabling [openssl feature](#feature-openssl).
33
34For Linux and MacOS, you also need to install gcc 4.9+ (or clang) too.
35
36Bindings are pre-generated for x86_64/arm64 Linux. For other platforms, bindings are generated at compile time.
37
38For Windows, you also need to install following software:
39
40- Active State Perl
41- yasm
42- Visual Studio 2015+
43
44## Build
45
46```
47$ ./scripts/reset-submodule.cmd # if you just cloned the repository
48$ cargo build
49```
50
51### Error linking OpenSSL
52
53If you're getting linker errors when building your project using `gRPC-rs`, head
54down to the `openssl` feature section for a possible fix.
55
56## Usage
57
58To generate the sources from proto files:
59
60### Option 1 - Manual Generation
61
621. Install the protobuf compiler:
63
64```
65$ cargo install protobuf-codegen
66```
67
682. Install the gRPC compiler:
69
70```
71$ cargo install grpcio-compiler
72```
73
743. Generate the sources:
75
76```
77$ protoc --rust_out=. --grpc_out=. --plugin=protoc-gen-grpc=`which grpc_rust_plugin` example.proto
78```
79
80
81### Option 2 - Programmatic Generation
82
83Programmatic generation can be used to generate Rust modules from proto files
84via your `build.rs` by using [protoc-grpcio](https://crates.io/crates/protoc-grpcio).
85
86For more information and examples see
87[README](https://github.com/mtp401/protoc-grpcio/blob/master/README.md).
88
89To include this project as a dependency:
90
91```
92[dependencies]
93grpcio = "0.6"
94```
95
96### Feature `secure`
97
98`secure` feature enables support for TLS encryption and some authentication
99mechanism. When you do not need it, for example when working in intranet,
100you can disable it by using the following configuration:
101```
102[dependencies]
103grpcio = { version = "0.6", default-features = false, features = ["protobuf-codec"] }
104```
105
106### Feature `prost-codec` and `protobuf-codec`
107
108`gRPC-rs` uses `protobuf` crate by default. If you want to use `prost` instead, you can enable
109`prost-codec` feature. You probably only want to enable only one of the two features. Though
110grpcio is completely fine with both features enabled at the same time, grpcio-compiler
111will not going to work as expected.
112
113### Feature `openssl` and `openssl-vendored`
114
115`gRPC-rs` comes vendored with `gRPC Core`, which by default uses BoringSSL
116instead of OpenSSL. This may cause linking issues due to symbol clashes and/or
117missing symbols when another one of your dependencies uses OpenSSL. To resolve
118this, you can tell `gRPC-rs` to use OpenSSL too by specifying `"openssl"` in
119your `Cargo.toml`'s features list for `gprcio`, which requires openssl (>=1.0.2). E.g.:
120
121```toml
122[dependencies]
123grpcio = { version = "0.6", features = ["openssl"] }
124```
125
126Feature `openssl-vendored` is the same as feature `openssl` except it will build openssl from
127bundled sources.
128
129## Performance
130
131See [benchmark](https://github.com/tikv/grpc-rs/tree/master/benchmark) to find out how to run a benchmark by yourself.
132
133Cross Compile
134-------------
135See [cross_compile](cross_compile.md)
136
137Contributing
138------------
139
140Make sure to format and test the code before sending a PR.
141
142If the content in grpc-sys/grpc is updated, you may need to regenerate bindings:
143
144```
145$ ./scripts/generate-bindings.sh
146```
147
){kind=link}
){kind=link}
){kind=link}
){kind=link}