How to build a ruby gem and host it on gemcutter

3 January 2010 in Ruby

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: , , , ,

3 January 2010 Ruby

11 Comments to How to build a ruby gem and host it on gemcutter

  1. [...] “How to build a ruby Gem” tutorial by our Scrum Master Chris Young. [...]

    2. How to Build a Ruby Gem | Integrum on 3 January 2010

  2. [...] Chris Young, our resident Scrum Master, in quest for excellence created a gem (NetRecorder) to help ease the pain of API testing.  This is his first gem and so he would love your feedback.  He also wrote a tutorial based on his experience building a gem. [...]

    3. Netrecoder to Help with API Testing | Integrum on 3 January 2010

  3. I’ve found the Jeweler to be pretty simple to use, http://github.com/technicalpickles/jeweler .

    How come you went with manual over Jeweler?

    Cheers,

    Nick

    4. Nicholas Orr on 5 January 2010

  4. @Nicholas, I didn’t go manual, I used ‘echoe’ - maybe jeweler is better?

    5. Chris Young on 5 January 2010

  5. One problem I ran into using this guide is that you missed the part where you add the public cert that was created using gem cert –build.

    You need to run gem cert –add /secret/path/to/gem-public_cert.pem or else installing the gem the first time from the gemspec fails.

    6. Clayton on 9 January 2010

  6. Thanks Clayton,

    I updated the post.

    7. Chris Young on 9 January 2010

  7. Oh I see. I’ve read it a bit closer and there are a few steps taken care of in jeweler that you’ve done by typing extra stuff and pasting code :)

    8. Nicholas Orr on 11 January 2010

  8. Oh I see . . .

    Maybe I should check out this so-called ‘Jeweler’ and see what all the hubub is about!

    9. Chris Young on 11 January 2010

  9. Thanks for this great writeup!

    btw. you missed/typo another dash (-) for installing it must be:

    gem cert –add /secret/path/to/gem-public_cert.pem

    cheer Tobi

    10. Tobi on 8 April 2010

  10. ^^ shit, ok now I see it’s not your fault, its (my) font type. The line should read (double dash add) or just:

    gem cert -a /secret/path/to/gem-public_cert.pem

    11. Tobi on 8 April 2010

  11. [...] http://buzaz.com/index.php/2010/01/03/how-to-build-a-ruby-gem/ [...]

    12. Thinking In Rails » Blog Archive » Anatomy of A Ruby Gem on 7 May 2010

Leave a comment



Tweets

  • Tobi:
    ^^ shit, ok now I see it's not your fault, its (my...
  • Tobi:
    Thanks for this great writeup! btw. you missed...
  • Chris Young:
    Thanks for letting me know. I updated the link....
  • maxjgon:
    The link of the project in Github is broken!...
  • Chris Young:
    Oh I see . . . Maybe I should check out this so-c...

Archive

Links