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$ cargo xtask submodule # 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$ cargo xtask bindgen 146``` 147
){kind=link}
){kind=link}
){kind=link}
){kind=link}