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}