A Better Approach for Creating Ruby Libraries as Gems

There are several tools out there meant to help you create and manage gems—Ruby packages—for your Ruby libraries. I take issue with most of them and I’ll explain why. These are the tools under consideration:

The aspect that I take issue with in all of these tools (except RakeGem) is an extension of Josh Peek’s thoughts on best practices for library development: I don’t want my gem packaging tool to force itself on all other developers who wish to use and develop with my gem.

While Josh limits his recommendations to the runtime behavior of a library not depending on RubyGems and respecting load paths, I want to push that back to include even the development behavior of a library. If a developer wants to enhance my library while manually taking care of bundling, releasing, et cetera, then who am I to get in her way?

There’s a bootstrapping problem with the first four of these libraries: using them to create a gem includes a dependency on the tool itself for anyone who wants to interact with the gem in a development environment (e.g. use rake). Let’s look at the beginning of each Rakefile generated by each tool to see what I’m talking about.

jeweler:

begin
  require 'jeweler'
  #...
rescue LoadError
  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
end

hoe:

require 'hoe'

New Gem:

require 'hoe'

Bones:

begin
  require 'bones'
rescue LoadError
  abort '### Please install the "bones" gem ###'
end

So there you have it: each environment generated by one of the tools depends on the tool itself, thus restricting all future developers of that library to use precisely the same tools as the original author. What about RakeGem?

Well, Tom Preston-Werner may have had my concerns in mind when he created RakeGem: its created gems don’t depend on the tool itself, but I think he could have taken his tool further. It’s a bit of a stretch to call RakeGem a tool, though: it’s just a template for creating new gems, along with a Rakefile containing tasks to enforce a couple of gem packaging best practices and do simple gem creation and releasing. It’s a great start, but it doesn’t give us all of the boilerplate benefits that the other tools do, like file and directory creation.

My Solution

So my solution is to use one of these tools—Bones—but with a custom gem bootstrapping template. Both Hoe and Bones allow for custom templates, but Bones has the ability to use a git repository for its template, and allows you to keep multiple templates around for creating different types of gems.

Here’s what I use now to create my gems. First, I install bones:

$ gem install bones

Then I create a new template (or skeleton, as bones calls it) with bones freeze, passing it the URL to my git repo containing the template I want to use, and giving the skeleton a name; in this case, rspec2:

$ bones freeze -r git://github.com/h3h/bones-skeleton-rspec2.git rspec2

Now I can create as many gems as I want using that skeleton with bones create, passing the name of the skeleton:

$ bones create -s rspec2 mynewlib

The particular skeleton that I’ve created includes a barebones file structure for a basic library, including the use of RSpec 2.x for unit tests. I hope others find this useful. I encourage you to shoot me a quick note if you know of improvements that we could benefit from.