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