Jeweler: Craft the perfect RubyGem

Jeweler provides two things:

Quick Links

Installing

Install the gem:

gem install jeweler

Using in an existing project

It's easy to get up and running. Update your Rakefile to instantiate a Jeweler::Tasks, and give it a block with details about your project.

begin
  require 'jeweler'
  Jeweler::Tasks.new do |gemspec|
    gemspec.name = "the-perfect-gem"
    gemspec.summary = "One line summary of your gem"
    gemspec.description = "A different and possibly longer explanation of"
    gemspec. = "josh@technicalpickles.com"
    gemspec.homepage = "http://github.com/technicalpickles/the-perfect-gem"
    gemspec.authors = ["Josh Nichols"]
  end
rescue LoadError
  puts "Jeweler not available. Install it with: gem install jeweler"
end

The yield object here, gemspec, is a Gem::Specification object. See the Customizing your project's gem specification for more details about how you can customize your gemspec.

Using to start a new project

Jeweler provides a generator. It requires you to setup your name and email for git and your username and token for GitHub.

jeweler the-perfect-gem

This will prepare a project in the 'the-perfect-gem' directory, setup to use Jeweler.

It supports a number of options. Here's a taste, but jeweler --help will give you the most up-to-date listing:

Default options

Jeweler respects the JEWELER_OPTS environment variable. Want to always use RSpec, and you're using bash? Add this to ~/.bashrc:

export JEWELER_OPTS="--rspec"

Gemspec

Jeweler handles generating a gemspec file for your project:

rake gemspec

This creates a gemspec for your project. It's based on the info you give Jeweler::Tasks, the current version of your project, and some defaults that Jeweler provides.

Gem

Jeweler gives you tasks for building and installing your gem.

rake install

To build the gem (which will end up in pkg), run:

rake build

To install the gem (and build if necessary), i.e. using gem install, run:

rake install

Note, this does not use sudo to install it, so if your ruby setup needs that, you should prefix it with sudo:

sudo rake install

Versioning

Jeweler tracks the version of your project. It assumes you will be using a version in the format x.y.z. x is the 'major' version, y is the 'minor' version, and z is the patch version.

Initially, your project starts out at 0.0.0. Jeweler provides Rake tasks for bumping the version:

rake version:bump:major
rake version:bump:minor
rake version:bump:patch

You can also programmatically set the version if you wish. Typically, you use this to have a module with the version info so clients can access it. The only downside here is you no longer can use the version:bump tasks.

require File.dirname(__FILE__) + "/lib/my_project/version.rb"

Jeweler::Tasks.new do |gemspec|
   gemspec.version = MyProject::VERSION
   # more stuff
end

Prerelease versioning

Major, minor, and patch versions have a distant cousin: build. You can use this to add an arbitrary (or you know, regular type) version. This is particularly useful for prereleases.

You have two ways of doing this:

Jeweler does not provide a version:bump:build because the build version can really be anything, so it's hard to know what should be the next bump.

Releasing

Jeweler handles releasing your gem into the wild:

rake release

It does the following for you:

As is though, it doesn't actually get your gem anywhere. To do that, you'll need to use rubyforge or gemcutter.

Releasing to Gemcutter

Jeweler can also handle releasing to Gemcutter. There are a few steps you need to do before doing any Gemcutter releases with Jeweler:

A Rakefile setup for gemcutter would include something like this:

begin
  require 'jeweler'
  Jeweler::Tasks.new do |gemspec|
    # omitted for brevity
  end
  Jeweler::GemcutterTasks.new
rescue LoadError
  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
end

After you have configured this, rake release will now also release to Gemcutter.

If you need to release it without the rest of the release task, you can run:

$ rake gemcutter:release

Releasing to RubyForge

Jeweler can also handle releasing to RubyForge. There are a few steps you need to do before doing any RubyForge releases with Jeweler:

A Rakefile setup for rubyforge would include something like this:

begin
  require 'jeweler'
  Jeweler::Tasks.new do |gemspec|
    # ommitted for brevity
    gemspec.rubyforge_project = 'the-perfect-gem' # This line would be new
  end

  Jeweler::RubyforgeTasks.new do |rubyforge|
    rubyforge.doc_task = "rdoc"
  end
rescue LoadError
  puts "Jeweler, or a dependency, not available. Install it with: gem install jeweler"
end

Now you must initially create a 'package' for your gem in your RubyForge 'project':

$ rake rubyforge:setup

After you have configured this, rake release will now also release to RubyForge.

If you need to release it without the rest of the release task, you can run:

$ rake rubyforge:release

Development and Release Workflow