This weekend I built my first ruby gem. The stuff out there on the internet is pretty confusing so hopefully this post will make it exceedingly clear. The most complete source I found was the Railscast, “Making a gem”.

Here are the steps I took:

1. Create the hello world library
2. Use the echoe gem to create a rake file that will generate your “gem spec”
yikes! That’s a mouth full.
3. Use rake to create the manifest and gemspec
4. Install the hello world gem locally
5. Create and install a self-signed certificate.
6. Update your bash profile with the certificate information.
7. Use ‘rake gem’ to create the gem
8. Add your project to github
9. Use the gemcutter gem to host your gem on gemcutter
10. The holy grail - gem install hello_world

Create the library

The hello world gem will have one method

HelloWorld.say_hello

This will write out ‘hello world’ when called. We’ll store the method in a module called “HelloWorld”, as suggested in the screencast.

  mkdir -p hello_world/lib
  touch hello_world/lib/hello_world.rb

Add this code to hello_world/lib/hello_world.rb:

  module HelloWorld
    def self.say_hello
      puts 'hello world'
    end
  end

Create a rake file using echoe

There are a lot of gems out there that are made to make gem building easy. I went with what was recommended in the screencast and tried out the “echoe” gem.

gem install echoe
touch hello_world/Rakefile

Add this code to hello_world/Rakefile:

require 'rubygems'
require 'rake'
require 'echoe'

Echoe.new('helloworld', '0.0.1') do |p|
  p.description    = "A gem that illustrates how to build a gem"
  p.url            = "http://github.com/tombombadil/hello_world"
  p.author         = "Chris Young"
  p.email          = "beesucker @nospam@ gmail.com"
  p.ignore_pattern = ["tmp/*", "script/*"]
  p.development_dependencies = []
end

Now you can type

rake -T

and get a bunch of tasks to help you manage your gem.

Create a manifest and gemspec

A manifest just lists which files should be included in your gem and the gemspec has everything gem needs to manage versioning. Echoe is partial to rubyforge, but this didn’t keep me from being able to use it with github.

cd hello_world
rake manifest
rake build_gemspec

Create a certificate

We’ll sign the gem with a self-signed certificate.

  gem cert --build youremail@example.com
  gem cert –add /secret/path/to/gem-public_cert.pem

Important! Move the gem-private_key.pem file to a secure location

Edit your bash_profile

Add these lines to your bash_profile:

export GEM_PRIVATE_KEY='/secret/path/to/gem-private_key.pem'
export GEM_CERTIFICATE_CHAIN='/secret/path/to/gem-public_cert.pem'

And type this:

source ~/.bash_profile

Install your gem locally

Let’s make sure the gem works. Running this command will install your gem on your computer so you can test it.

rake install helloworld.gemspec

start irb and test

  irb
  require 'rubygems'
  require 'hello_world'
  HelloWorld.say_hello
  # => hello world

It works!

Create the gem

Now we’re getting close. This command will build the gem with your certificate.

rake gem

Add the project to git

Create the repository on github

  git init
  git add .
  git commit -m "initial commit"
  git remote add origin git@github.com:tombombadil/hello_world_gem.git
  git push origin master

Host your gem on gemcutter

Create a gemcutter account

gem install gemcutter
gem push hello_world-0.0.1.gem

The Holy Grail

gem install hello_world

Tags: Echoe, Gem, Gemcutter, Github, Tutorial