diff options
author | Chris Fallin <cfallin@c1f.net> | 2015-02-23 12:27:52 -0800 |
---|---|---|
committer | Chris Fallin <cfallin@c1f.net> | 2015-02-23 12:28:43 -0800 |
commit | 21fb217e6ae4c28e20f91b93d25f030f0bba237f (patch) | |
tree | f0817ccfcdf658ff3c24e48677e50e242cb6690d /ruby/README.md | |
parent | 5b033ae2f7381779e28e665b85304b6764899b70 (diff) | |
download | protobuf-21fb217e6ae4c28e20f91b93d25f030f0bba237f.tar.gz protobuf-21fb217e6ae4c28e20f91b93d25f030f0bba237f.tar.bz2 protobuf-21fb217e6ae4c28e20f91b93d25f030f0bba237f.zip |
Updated Ruby README with more details on getting started.
Change-Id: I54df314660cdb861ad8c4da75a08d4cb97faf638
Diffstat (limited to 'ruby/README.md')
-rw-r--r-- | ruby/README.md | 47 |
1 files changed, 45 insertions, 2 deletions
diff --git a/ruby/README.md b/ruby/README.md index 59d5ace8..84f4a775 100644 --- a/ruby/README.md +++ b/ruby/README.md @@ -7,8 +7,51 @@ we recommend using protoc's Ruby generation support with .proto files. The build process in this directory only installs the extension; you need to install protoc as well to have Ruby code generation functionality. -Installation ------------- +Installation from Gem +--------------------- + +When we release a version of Protocol Buffers, we will upload a Gem to +[RubyGems](https://www.rubygems.org/). To use this pre-packaged gem, simply +install it as you would any other gem: + + $ gem install [--prerelease] google-protobuf + +The `--pre` flag is necessary if we have not yet made a non-alpha/beta release +of the Ruby extension; it allows `gem` to consider these "pre-release" +alpha/beta versions. + +Once the gem is installed, you may or may not need `protoc`. If you write your +message type descriptions directly in the Ruby DSL, you do not need it. +However, if you wish to generate the Ruby DSL from a `.proto` file, you will +also want to install Protocol Buffers itself, as described in this repository's +main `README` file. The version of `protoc` included in the latest release +supports the `--ruby_out` option to generate Ruby code. + +A simple example of using the Ruby extension follows. More extensive +documentation may be found in the RubyDoc comments (`call-seq` tags) in the +source, and we plan to release separate, more detailed, documentation at a +later date. + + require 'google/protobuf' + + # generated from my_proto_types.proto with protoc: + # $ protoc --ruby_out=. my_proto_types.proto + require 'my_proto_types' + + mymessage = MyTestMessage.new(:field1 => 42, :field2 => ["a", "b", "c"]) + mymessage.field1 = 43 + mymessage.field2.push("d") + mymessage.field3 = SubMessage.new(:foo => 100) + + encoded_data = MyTestMessage.encode(mymessage) + decoded = MyTestMessage.decode(encoded_data) + assert decoded == mymessage + + puts "JSON:" + puts MyTestMessage.encode_json(mymessage) + +Installation from Source (Building Gem) +--------------------------------------- To build this Ruby extension, you will need: |