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

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.

Answer 2

The simplest way it's to use bundler:

bundle gem <gem_name>

You may even use it in an existing project from the parent directory.

Answer 3

This rubygems guide provides information about the structure of a gem and then goes into detail about what should be included in your gemspec

You may find it easier to use bundler to create the folder structure of the gem for you:

bundle gem <gem_name>

my_gem$ bundle gem my_gem create my_gem/Gemfile create my_gem/Rakefile create my_gem/LICENSE.txt create my_gem/README.md create my_gem/.gitignore create my_gem/my_gem.gemspec create my_gem/lib/my_gem.rb create my_gem/lib/my_gem/version.rb Initializing git repo in /Users/keith/projects/my_gem/my_gem

Answer 4

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 5

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

Edit (2012-01-10): An excellent all-around guide to gem best practices is RubyGems Guides. I would highly recommend starting here now.

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 test 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 $LOAD_PATH.
• If you find yourself writing require File.join(__FILE__, 'foo', 'bar'), you're doing it wrong.