grpc/src/ruby/README.md

gRPC Ruby

A Ruby implementation of gRPC.

Status

Alpha : Ready for early adopters

PREREQUISITES

• Ruby 2.x. The gRPC API uses keyword args.
• homebrew on Mac OS X, linuxbrew on Linux. These simplify the installation of the gRPC C core.

INSTALLATION

On Mac OS X, install homebrew. On Linux, install linuxbrew. Run the following command to install gRPC Ruby.

$ curl -fsSL https://goo.gl/getgrpc | bash -s ruby

This will download and run the gRPC install script, then install the latest version of gRPC Ruby gem. It also installs Protocol Buffers compiler (protoc) and the gRPC protoc plugin for ruby.

BUILD FROM SOURCE

• Clone this repository
• Build the gRPC C core E.g, from the root of the gRPC Git repository

$ cd ../..
$ make && sudo make install

• Install Ruby 2.x. Consider doing this with RVM, it's a nice way of controlling the exact ruby version that's used.

$ command curl -sSL https://rvm.io/mpapis.asc | gpg --import -
$ \curl -sSL https://get.rvm.io | bash -s stable --ruby=ruby-2
$
$ # follow the instructions to ensure that your're using the latest stable version of Ruby
$ # and that the rvm command is installed

• Make sure your run source $HOME/.rvm/scripts/rvm as instructed to complete the set up of RVM

• Install bundler

$ gem install bundler

• Finally, build and install the gRPC gem locally.

$ # from this directory
$ bundle install  # creates the ruby bundle, including building the grpc extension
$ rake  # runs the unit tests, see rake -T for other options

DOCUMENTATION

• rubydoc for the gRPC gem is available online at rubydoc.
• the gRPC Ruby reference documentation is available online at grpc.io

CONTENTS

Directory structure is the layout for ruby extensions

• ext: the gRPC ruby extension

• lib: the entrypoint gRPC ruby library to be used in a 'require' statement

• spec: Rspec unittests

• bin: example gRPC clients and servers, e.g,

  stub = Math::Math::Stub.new('my.test.math.server.com:8080')
  req = Math::DivArgs.new(dividend: 7, divisor: 3)
  GRPC.logger.info("div(7/3): req=#{req.inspect}")
  resp = stub.div(req)
  GRPC.logger.info("Answer: #{resp.inspect}")