Google Git
Sign in
chromium / external / github.com / grpc / grpc / HEAD / . / src / ruby / README.md
blob: e6ae90250a255c7ae66b347ce7a82e213ca09ab0 [file] [log] [blame] [view]
Jan Tattermuscha9b933e2015-10-30 15:52:19[diff] [blame]1[![Gem](https://img.shields.io/gem/v/grpc.svg)](https://rubygems.org/gems/grpc/)
Tim Emiola9fe51782015-01-23 02:23:32[diff] [blame]2gRPC Ruby
3=========
nnoble097ef9b2014-12-02 01:06:10[diff] [blame]4
Tim Emiolac33efe42015-02-19 17:39:49[diff] [blame]5A Ruby implementation of gRPC.
nnoble097ef9b2014-12-02 01:06:10[diff] [blame]6
Tim Emiola50773e62015-06-03 17:19:21[diff] [blame]7PREREQUISITES
8-------------
nnoble097ef9b2014-12-02 01:06:10[diff] [blame]9
Chad Wilsonb238b492025-05-27 17:53:40[diff] [blame]10- Ruby 3.x. The gRPC API uses keyword args.
nnoble097ef9b2014-12-02 01:06:10[diff] [blame]11
Tim Emiola50773e62015-06-03 17:19:21[diff] [blame]12INSTALLATION
Tim Emiolac33efe42015-02-19 17:39:49[diff] [blame]13---------------
Stanley Cheunga79a8962015-08-19 17:43:28[diff] [blame]14
murgatroid99d8521e72016-01-15 18:12:28[diff] [blame]15**Linux and Mac OS X:**
Stanley Cheung1894f182015-08-19 23:32:39[diff] [blame]16
17```sh
18gem install grpc
19```
20
Brian Buchalter59179842021-04-19 21:31:26[diff] [blame]21If using a Gemfile and you wish to pull from a git repository or GitHub, make sure to tell bundler to retrieve submodules:
22```
23gem 'grpc', github: 'grpc/grpc', submodules: true
24```
25
Tim Emiola50773e62015-06-03 17:19:21[diff] [blame]26BUILD FROM SOURCE
27---------------------
28- Clone this repository
Tim Emiola9fe51782015-01-23 02:23:32[diff] [blame]29
Frank Natividad235a2e72017-12-14 09:48:55[diff] [blame]30- Init submodules
31
32```sh
33git submodule update --init
34```
35
Chad Wilsonb238b492025-05-27 17:53:40[diff] [blame]36- Install Ruby 3.x. Consider doing this with [RVM](http://rvm.io), it's a nice way of controlling
Tim Emiola9fe51782015-01-23 02:23:32[diff] [blame]37 the exact ruby version that's used.
Tim Emiolac33efe42015-02-19 17:39:49[diff] [blame]38```sh
nnoble0c475f02014-12-05 23:37:39[diff] [blame]39$ command curl -sSL https://rvm.io/mpapis.asc | gpg --import -
Chad Wilsonb238b492025-05-27 17:53:40[diff] [blame]40$ \curl -sSL https://get.rvm.io | bash -s stable --ruby=ruby-3
nnoble097ef9b2014-12-02 01:06:10[diff] [blame]41$
nnoble0c475f02014-12-05 23:37:39[diff] [blame]42$ # follow the instructions to ensure that your're using the latest stable version of Ruby
43$ # and that the rvm command is installed
Tim Emiola0343f7f2015-01-26 20:04:48[diff] [blame]44```
Tim Emiola400ba762015-02-20 23:31:42[diff] [blame]45- Make sure your run `source $HOME/.rvm/scripts/rvm` as instructed to complete the set up of RVM
46
Tim Emiola9fe51782015-01-23 02:23:32[diff] [blame]47- Install [bundler](http://bundler.io/)
Tim Emiola0343f7f2015-01-26 20:04:48[diff] [blame]48```
Tim Emiola9fe51782015-01-23 02:23:32[diff] [blame]49$ gem install bundler
Tim Emiola0343f7f2015-01-26 20:04:48[diff] [blame]50```
nnoble097ef9b2014-12-02 01:06:10[diff] [blame]51
Tim Emiola50773e62015-06-03 17:19:21[diff] [blame]52- Finally, build and install the gRPC gem locally.
Tim Emiolac33efe42015-02-19 17:39:49[diff] [blame]53```sh
Tim Emiola5b071902015-02-20 23:35:22[diff] [blame]54$ # from this directory
Tim Emiolabd871622015-02-20 23:37:17[diff] [blame]55$ bundle install # creates the ruby bundle, including building the grpc extension
56$ rake # runs the unit tests, see rake -T for other options
Tim Emiola0343f7f2015-01-26 20:04:48[diff] [blame]57```
Tim Emiola9fe51782015-01-23 02:23:32[diff] [blame]58
Tim Emiola50773e62015-06-03 17:19:21[diff] [blame]59DOCUMENTATION
60-------------
61- rubydoc for the gRPC gem is available online at [rubydoc][].
62- the gRPC Ruby reference documentation is available online at [grpc.io][]
63
Tim Emiola9fe51782015-01-23 02:23:32[diff] [blame]64CONTENTS
65--------
Tim Emiola50773e62015-06-03 17:19:21[diff] [blame]66Directory structure is the layout for [ruby extensions][]
67- ext: the gRPC ruby extension
68- lib: the entrypoint gRPC ruby library to be used in a 'require' statement
69- spec: Rspec unittests
70- bin: example gRPC clients and servers, e.g,
Tim Emiola9fe51782015-01-23 02:23:32[diff] [blame]71
Tim Emiola50773e62015-06-03 17:19:21[diff] [blame]72 ```ruby
Teodore898ee62016-08-23 10:18:16[diff] [blame]73 stub = Math::Math::Stub.new('my.test.math.server.com:8080', :this_channel_is_insecure)
Tim Emiola50773e62015-06-03 17:19:21[diff] [blame]74 req = Math::DivArgs.new(dividend: 7, divisor: 3)
75 GRPC.logger.info("div(7/3): req=#{req.inspect}")
76 resp = stub.div(req)
77 GRPC.logger.info("Answer: #{resp.inspect}")
78 ```
murgatroid99d8521e72016-01-15 18:12:28[diff] [blame]79
Tim Emiola50773e62015-06-03 17:19:21[diff] [blame]80[ruby extensions]:http://guides.rubygems.org/gems-with-extensions/
81[rubydoc]: http://www.rubydoc.info/gems/grpc
Patrice Chalin4c4933e2020-06-16 12:40:59[diff] [blame]82[grpc.io]: https://grpc.io/docs/languages/ruby/quickstart
Stanley Cheung581846b2015-09-04 19:04:17[diff] [blame]83[Debian jessie-backports]:http://backports.debian.org/Instructions/