1 This directory contains the Ruby extension that implements Protocol Buffers 2 functionality in Ruby. 3 4 The Ruby extension makes use of generated Ruby code that defines message and 5 enum types in a Ruby DSL. You may write definitions in this DSL directly, but 6 we recommend using protoc's Ruby generation support with .proto files. The 7 build process in this directory only installs the extension; you need to 8 install protoc as well to have Ruby code generation functionality. 9 10 Installation from Gem 11 --------------------- 12 13 When 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 15 install it as you would any other gem: 16 17 $ gem install [--prerelease] google-protobuf 18 19 The `--pre` flag is necessary if we have not yet made a non-alpha/beta release 20 of the Ruby extension; it allows `gem` to consider these "pre-release" 21 alpha/beta versions. 22 23 Once the gem is installed, you may or may not need `protoc`. If you write your 24 message type descriptions directly in the Ruby DSL, you do not need it. 25 However, if you wish to generate the Ruby DSL from a `.proto` file, you will 26 also want to install Protocol Buffers itself, as described in this repository's 27 main `README` file. The version of `protoc` included in the latest release 28 supports the `--ruby_out` option to generate Ruby code. 29 30 A simple example of using the Ruby extension follows. More extensive 31 documentation may be found in the RubyDoc comments (`call-seq` tags) in the 32 source, and we plan to release separate, more detailed, documentation at a 33 later date. 34 35 ```ruby 36 require 'google/protobuf' 37 38 # generated from my_proto_types.proto with protoc: 39 # $ protoc --ruby_out=. my_proto_types.proto 40 require 'my_proto_types' 41 42 mymessage = MyTestMessage.new(:field1 => 42, :field2 => ["a", "b", "c"]) 43 mymessage.field1 = 43 44 mymessage.field2.push("d") 45 mymessage.field3 = SubMessage.new(:foo => 100) 46 47 encoded_data = MyTestMessage.encode(mymessage) 48 decoded = MyTestMessage.decode(encoded_data) 49 assert decoded == mymessage 50 51 puts "JSON:" 52 puts MyTestMessage.encode_json(mymessage) 53 ``` 54 55 Installation from Source (Building Gem) 56 --------------------------------------- 57 58 To build this Ruby extension, you will need: 59 60 * Rake 61 * Bundler 62 * Ruby development headers 63 * a C compiler 64 65 To 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 71 First switch to the desired platform with rbenv or RVM. 72 73 Then install the required Ruby gems: 74 75 $ gem install bundler 76 $ bundle 77 78 Then build the Gem: 79 80 $ rake 81 $ rake clobber_package gem 82 $ gem install `ls pkg/google-protobuf-*.gem` 83 84 To run the specs: 85 86 $ rake test 87 88 This gem includes the upb parsing and serialization library as a single-file 89 amalgamation. It is up-to-date with upb git commit 90 `535bc2fe2f2b467f59347ffc9449e11e47791257`. 91 92 Version Number Scheme 93 --------------------- 94 95 We are using a version number scheme that is a hybrid of Protocol Buffers' 96 overall version number and some Ruby-specific rules. Gem does not allow 97 re-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, 99 pre, ...) 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 112 These 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): 114 release numbers should sort in actual release order. 115