What is the modern way to structure a ruby gem?

Question

Has much changed with the release of Bundler? Is there a template that can be used as a base? What are the best practices?

Answer 1

Some posts that I have found useful:

• http://chneukirchen.github.com/rps/
• http://tomayko.com/writings/require-rubygems-antipattern
• http://yehudakatz.com/2009/07/24/rubygems-good-practice/
• http://weblog.rubyonrails.org/2009/9/1/gem-packaging-best-practices

To summarize the key points:

• Use the basic lib/gem.rb and lib/gem/ structure for code.
• Put any executables in bin, any data files in data and tests in tests or spec.
• Don't require or depend upon files outside of the load path. (VERSION files often seem to live in odd places in gems.)
• Do not require 'rubygems'.
• Do not tamper with the $LOADPATH.
• If you find yourself writing require File.join(__FILE__, 'foo', 'bar'), you're doing it wrong.

Having said all that, none of these tips deals with Bundler, and three out of the four links are from 2009 - which in Ruby years is like a decade ago. So I may not be answering your actual question.

Answer 2

When writing fat (binary) gems the structure is usually this:

lib/1.8/binary.so

lib/1.9/binary.so

lib/my_gem.rb (this file simply chooses which binary.so to load depending on ruby version)

And for native extensions:

lib/ext/my_gem/my_sources.*

lib/my_gem.rb

I also usually put a version.rb file here:

lib/my_gem/version.rb

and it simply contains something like:

module MyGem
    VERSION = "0.1.0"
end

Also, IMO, don't put any .rb files except the file you want people to use to load the gem, in the lib/ directory. Instead put all auxiliary files in lib/my_gem/

Answer 3

Telemachus's advice is good. If you follow it your gem will be setup to play nicely with bundler.

You might also try using jeweler. It's a gem that generates skeletons for gems. The default skeleton that it spits out complies with all of the conventions Telemachus mentioned and it will also do some nice things like add your favorite test framework or create a GitHub repository.