1This directory contains the Ruby extension that implements Protocol Buffers 2functionality in Ruby. 3 4The Ruby extension makes use of generated Ruby code that defines message and 5enum types in a Ruby DSL. You may write definitions in this DSL directly, but 6we recommend using protoc's Ruby generation support with .proto files. The 7build process in this directory only installs the extension; you need to 8install protoc as well to have Ruby code generation functionality. 9 10Installation from Gem 11--------------------- 12 13When we release a version of Protocol Buffers, we will upload a Gem to 14[RubyGems](https://www.rubygems.org/). To use this pre-packaged gem, simply 15install it as you would any other gem: 16 17 $ gem install [--prerelease] google-protobuf 18 19The `--pre` flag is necessary if we have not yet made a non-alpha/beta release 20of the Ruby extension; it allows `gem` to consider these "pre-release" 21alpha/beta versions. 22 23Once the gem is installed, you may or may not need `protoc`. If you write your 24message type descriptions directly in the Ruby DSL, you do not need it. 25However, if you wish to generate the Ruby DSL from a `.proto` file, you will 26also want to install Protocol Buffers itself, as described in this repository's 27main `README` file. The version of `protoc` included in the latest release 28supports the `--ruby_out` option to generate Ruby code. 29 30A simple example of using the Ruby extension follows. More extensive 31documentation may be found in the RubyDoc comments (`call-seq` tags) in the 32source, and we plan to release separate, more detailed, documentation at a 33later date. 34 35```ruby 36require 'google/protobuf' 37 38# generated from my_proto_types.proto with protoc: 39# $ protoc --ruby_out=. my_proto_types.proto 40require 'my_proto_types' 41 42mymessage = MyTestMessage.new(:field1 => 42, :field2 => ["a", "b", "c"]) 43mymessage.field1 = 43 44mymessage.field2.push("d") 45mymessage.field3 = SubMessage.new(:foo => 100) 46 47encoded_data = MyTestMessage.encode(mymessage) 48decoded = MyTestMessage.decode(encoded_data) 49assert decoded == mymessage 50 51puts "JSON:" 52puts MyTestMessage.encode_json(mymessage) 53``` 54 55Installation from Source (Building Gem) 56--------------------------------------- 57 58To build this Ruby extension, you will need: 59 60* Rake 61* Bundler 62* Ruby development headers 63* a C compiler 64 65To Build the JRuby extension, you will need: 66 67* Maven 68* The latest version of the protobuf java library (see ../java/README.md) 69* Install JRuby via rbenv or RVM 70 71First switch to the desired platform with rbenv or RVM. 72 73Then install the required Ruby gems: 74 75 $ gem install bundler 76 $ bundle 77 78Then build the Gem: 79 80 $ rake 81 $ rake clobber_package gem 82 $ gem install `ls pkg/google-protobuf-*.gem` 83 84To run the specs: 85 86 $ rake test 87 88This gem includes the upb parsing and serialization library as a single-file 89amalgamation. It is up-to-date with upb git commit 90`535bc2fe2f2b467f59347ffc9449e11e47791257`. 91 92Version Number Scheme 93--------------------- 94 95We are using a version number scheme that is a hybrid of Protocol Buffers' 96overall version number and some Ruby-specific rules. Gem does not allow 97re-uploads of a gem with the same version number, so we add a sequence number 98("upload version") to the version. We also format alphabetical tags (alpha, 99pre, ...) slightly differently, and we avoid hyphens. In more detail: 100 101* First, we determine the prefix: a Protocol Buffers version "3.0.0-alpha-2" 102 becomes "3.0.0.alpha.2". When we release 3.0.0, this prefix will be simply 103 "3.0.0". 104* We then append the upload version: "3.0.0.alpha.2.0" or "3.0.0.0". If we need 105 to upload a new version of the gem to fix an issue, the version becomes 106 "3.0.0.alpha.2.1" or "3.0.0.1". 107* If we are working on a prerelease version, we append a prerelease tag: 108 "3.0.0.alpha.3.0.pre". The prerelease tag comes at the end so that when 109 version numbers are sorted, any prerelease builds are ordered between the 110 prior version and current version. 111 112These rules are designed to work with the sorting rules for 113[Gem::Version](http://ruby-doc.org/stdlib-2.0/libdoc/rubygems/rdoc/Gem/Version.html): 114release numbers should sort in actual release order. 115