In Depth Ruby Gem Development Resources (Book, Video, Sites)

In depth Ruby Gem development resources (book, video, sites)

Rubygems aren't related to distributed programming.

Can you please provide more details about what you're after, if you aren't asking a duplicate question? Related questions within Stack Overflow include:

• Gotchas for writing rubygems
• Ruby : How to write a gem ?
• What are the steps needed to create and publish a rubygem of your own?
• What is the modern way to structure a ruby gem?

(I know this is more of a comment than an answer, but it's too big to fit in the comments section)

Ruby : How to write a gem?

Rubygems.org's Guides is one of the best resources for writing your own gem.

If you're using Bundler in your app, you might want to look at Ryan Bigg's guide to Developing a RubyGem using Bundler and the Railscast on creating gems with Bundler.

If you're interested in tools to help you write gems:

• Jeweler - Opinionated tool for creating and managing Rubygem projects. There's also a Gemcutter and Jeweler Railscast.
• Hoe - From the guys at seattlrb.
• gem-this adds a bunch of helpful rake tasks.

Some tutorials/guides:

• Creating Your First Gem
• Using bundler and rvm to build a rubygem - Using bundler and rvm to create a gem
• Gem Packaging: Best Practices
• Ruby Gem Recipe - Intro guide to creating a gem using bundler and jeweler
• How to build a ruby gem and host it on gemcutter - tutorial using echoe and gemcutter
• The Truth About Gemspecs - goes over gemspecs and tips for dealing with them
• Packaging with RubyGems - a quickstart guide for Jeweler
• gem that - James Adam - reviews tools that help build gems (hoe, newgem, echoe, gemhub, jeweler, gem this)
• Using Gemcutter's Api from the Commandline
• New Gem with Bundler – Sample Rakefile - Useful rakefile for deploying and publishing a gem
• Let's Write a Gem
• How To Build A Ruby Gem With Bundler, Test-Driven Development, Travis CI And Coveralls, Oh My!

What are the steps needed to create and publish a rubygem of your own?

There are several tools to help you build your own gems. hoe and newgem are the best-known, and have a lot of good qualities. However, hoe adds itself as a dependency to your gem, and newgem has become a very large tool, one that I find unwieldy when I want to create and deploy a gem quickly.

My favorite tool is Mr Bones by Tim Pease. It’s lightweight, featureful, and does not add dependencies to your project. To create a project with it, you just run bones <my_project_name> on the command line, and a skeleton is built for you, complete with a lib directory for your code, a bin directory for your tools, and a test directory. The configuration is in a Rakefile, and it’s clear and concise. Here's the configuration for a project I did a few months ago:

load 'tasks/setup.rb'

ensure_in_path 'lib'
require 'friend-feed'

task :default => 'test'

PROJ.name = 'friend-feed'
PROJ.authors = 'Clinton R. Nixon'
PROJ.email = 'crnixon@gmail.com'
PROJ.url = 'friend-feed.rubyforge.org'
PROJ.rubyforge_name = 'friend-feed'
PROJ.dependencies = ['json']
PROJ.version = FriendFeed::VERSION
PROJ.exclude = %w(.git pkg)

Mr Bones has the standard set of features you’d expect: you can use it to package up gems and tarfiles of your library, as well as release it on RubyForge and deploy your documentation there. Its killer feature, though, is its ability to freeze its skeleton in your home directory. When you run bones --freeze, a directory named .mrbones is copied into your home directory. You can edit the files in there to make a skeleton for your gems that works the way you work, and from then on, when you run bones to create a new gem, it will use your personal gem skeleton. You can unfreeze Mr Bones by running bones --unfreeze and your skeleton will be backed up, and the default skeleton will be used again.

(Editorial note: I wrote a blog post about this several months ago, and most of this is copied from it.)

Gotchas for writing rubygems

Gem Packaging: Best Practices gives a lot of advice, some of which include

• Don't pollute the global load path. Ideally, only have foo.rb in your lib directory, and put all your other files in lib/foo.

• Don't require files using __FILE__.

• Don't rely on anything outside the load path. Folders may not have the same structure as in your original version. For example, don't use something like

  VERSION = ::File.read(::File.join(::File.dirname(FILE), "..", "..", "VERSION")).strip

• Don't manage $LOAD_PATH within lib.

• Provide a VERSION constant.

• Don't depend on rubygems. The person using your code may not be using rubygems, but some other packaging system (or no packaging system). Similarly, don't mention version dependencies in the code itself, or rescue Gem::LoadError.

Rubygems dependencies. Please... argues that you shouldn't list optional runtime dependencies, and should separate developer from runtime dependencies.

From my own experience: if nothing else, try building and installing your gem locally before releasing it into the wild. It avoids brown paper bag releases.

What is the modern way to structure a ruby gem?

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.

---

Related Topics