Shipping rdoc-data 4.1.0

Wed Dec 30 03:49:15 2015 Zachary Scott zzak@ruby-lang.org

I've just finished the release of rdoc-data version 4.1.0!

In case you're not familiar with rdoc-data, here's a quick summary:

This gem is designed to install Ruby's documentation for any version of Ruby 1.8+ for ri.

If you haven't used ri before.. it's a great tool!

Let me tell you a story

It started when I was doing issue triage for the latest RDoc bugfix release.

When I came across an issue that was over a year-and-a-half old..

You see, the rdoc-data gem hasn't been released in over a year since that ticket was open.. so it was missing all of the data for newer versions of Ruby!

In order to fix this, we need to repackage the gem with the data for these newer rubies.

So I started looking into the rdoc-data project, and I found almost the exact same ticket created just after the last release.. created by none other than yours truly.

How do we package the gem?

Now, I was aware this was one of @drbrain's projects..

So after installing hoe, I started reading the Rakefile. *rimshot*

It seemed that this project used another tool called multiruby to build the ri data.

From what I could gather, multiruby was something like rvm or chruby that lets you switch between versions and keeps the srcdir around; which is useful for generating the ri data later.

However, I didn't want to learn how to use this new tool -- so I just used Ruby.

Before that, I had to learn about how this tool packages the data.

It basically comes down to this:

Then after the gem is installed, you can run rdoc-data --install to get the docs. This does two things:

When copying data, it actually used RUBY_VERSION directly..

Since Ruby has switched to a "SemVer"-like scheme, this means patchlevels actually matter.

So we would have to include data for every patchlevel, but the problem is the size of this gem is already +30mb with only 6 versions of Ruby supported.. if we wanted to support every patchlevel of the 2.x-series we're talking more like +100mb of ri data.

Let's make it better

Going forward, here were my goals for this release:

Without going into too much detail, because you can simply read the Rakefile if it interests you..

I've outlined the essentials that made rdoc-data's packaging system better.

After creating an array of supported versions of Ruby, we create a task for each one that does the following:

In doing this, I encountered two problems..

  1. Using the rdoc command on rubies 2.0+ was corrupting data
  2. Ruby 1.8.7 doesn't ship with RubyGems OR an RDoc that can create ri data

Since 1.8.7 ships with an older RDoc, it actually wasn't being included when building the gem with the new system.

Fixing Number One

In order to fix the first problem, I found that it actually worked if you use RDoc directly from ruby.

So I wrote a script with the same options we passed the command-line and made the target ruby call it for me.

Take a look at generate.rb in the source tree of rdoc-data to see how I used it.

And Number Two

The second problem was a bit harder..

First we actually have to install a working version of RubyGems. This means fetching a tarball, unpacking, running setup.rb from the target version of Ruby, and then running gem update --system.

Then once our target 1.8.7 has a working RubyGems, we can install a modern version of RDoc. I've chosen to go with version 3.12 because it was a solid release for the Ruby 1.8.x-series.

Finally, we can run the rdoc command on target 1.8.7 source tree and generate our ri data.

At Last!

Wooo! Now that is out of the way, the gem can be packaged with the rake gem command.

This will go through and compile 6 different versions of Ruby, and generate the ri data for each of them.

Once this is done we can install the gem and test it.

Testing the gem

On my local machine, I actually went through the trouble of installing all versions of Ruby 1.8+, along with JRuby 1.7 and 9k for testing.

After installing each version, I had to make sure no ri data was installed on the system. So for each version I had to delete the system dir used by ri.

Something like rm ~/.rubies/VERSION/share/ri/system, followed by gem install pkg/rdoc-data-4.1.0.gem to install the gem.

Then I could run rdoc-data --install and check that ri Object actually retrieved the correct documentation instead of a message like Nothing known about Object.

Ship it

After testing each supported version of Ruby with the packaged gem, I merged the pull request. and pushed 4.1.0 to RubyGems.org.

Happy Holidays!

I hope this gem finds you well.

During your holiday travels as you journey from airport to airport with barely a wifi connection, so that you can still find the method you're looking for as you happily hack across the skies.