README.md
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