diff options
Diffstat (limited to 'ruby/README.md')
-rw-r--r-- | ruby/README.md | 111 |
1 files changed, 111 insertions, 0 deletions
diff --git a/ruby/README.md b/ruby/README.md new file mode 100644 index 00000000..d2fa76ab --- /dev/null +++ b/ruby/README.md @@ -0,0 +1,111 @@ +This directory contains the Ruby extension that implements Protocol Buffers +functionality in Ruby. + +The Ruby extension makes use of generated Ruby code that defines message and +enum types in a Ruby DSL. You may write definitions in this DSL directly, but +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 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: + +* Rake +* Bundler +* Ruby development headers +* a C compiler + +To Build the JRuby extension, you will need: + +* Maven +* The latest version of the protobuf java library +* Install JRuby via rbenv or RVM + +First switch to the desired platform with rbenv or RVM. + +Then install the required Ruby gems: + + $ gem install bundler + $ bundle + +Then build the Gem: + + $ rake gem + $ gem install pkg/protobuf-$VERSION.gem + +To run the specs: + + $ rake test + +This gem includes the upb parsing and serialization library as a single-file +amalgamation. It is up-to-date with upb git commit +`535bc2fe2f2b467f59347ffc9449e11e47791257`. + +Version Number Scheme +--------------------- + +We are using a version number scheme that is a hybrid of Protocol Buffers' +overall version number and some Ruby-specific rules. Gem does not allow +re-uploads of a gem with the same version number, so we add a sequence number +("upload version") to the version. We also format alphabetical tags (alpha, +pre, ...) slightly differently, and we avoid hyphens. In more detail: + +* First, we determine the prefix: a Protocol Buffers version "3.0.0-alpha-2" + becomes "3.0.0.alpha.2". When we release 3.0.0, this prefix will be simply + "3.0.0". +* We then append the upload version: "3.0.0.alpha.2.0" or "3.0.0.0". If we need + to upload a new version of the gem to fix an issue, the version becomes + "3.0.0.alpha.2.1" or "3.0.0.1". +* If we are working on a prerelease version, we append a prerelease tag: + "3.0.0.alpha.3.0.pre". The prerelease tag comes at the end so that when + version numbers are sorted, any prerelease builds are ordered between the + prior version and current version. + +These rules are designed to work with the sorting rules for +[Gem::Version](http://ruby-doc.org/stdlib-2.0/libdoc/rubygems/rdoc/Gem/Version.html): +release numbers should sort in actual release order. |