Wed Dec 30 03:49:15 2015 Zachary Scott firstname.lastname@example.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:
ridocumentation to end-users
This gem is designed to install Ruby's documentation for any version of Ruby 1.8+ for
If you haven't used
ri before.. it's a great tool!
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.
Now, I was aware this was one of @drbrain's projects..
So after installing
hoe, I started reading the
It seemed that this project used another tool called
multiruby to build the ri data.
From what I could gather,
multiruby was something like
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:
srcdirand install to the
datafolder in the gem package
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
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.
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:
rdocon the source
In doing this, I encountered two problems..
rdoccommand on rubies 2.0+ was corrupting data
Since 1.8.7 ships with an older RDoc, it actually wasn't being included when building the gem with the new system.
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.
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.
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.
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.
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.
After testing each supported version of Ruby with the packaged gem, I merged the pull request. and pushed 4.1.0 to RubyGems.org.
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.