How to Build a Ruby Gem
January 2nd, 2010 » No Comments »
“How to build a ruby Gem” tutorial by our Scrum Master Chris Young.
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 library
2. Use the echoe gem to create a rake file that will generate your gem spec
3. Use rake to create the manifest and gemspec
4. Install your gem locally
5. Create a self-signed certificate
6. Update the gemspec with the certificate information
7. Use ‘gem build’ to create the gem
8. Add your project to github
9. Use the gemcutter gem to host your gem on gemcutter
Create the library
Our library will have one method HelloWorld.say_hello that will write out ‘hello world’ when called. We’ll store the method in a module called “HelloWorld”, as suggested in the screencast.
1. > mkdir -p hello_world/lib
2. > touch hello_world/lib/hello_world.rb
2. 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.
1. > gem install echoe
2. > touch hello_world/Rakefile
3. 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.
1. > cd hello_world
2. > rake manifest
3. > rake build_gemspec
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.
1. > rake install helloworld.gemspec
2. start irb and test
>> irb > require 'rubygems' > require 'hello_world' > HelloWorld.say_hello hello world
It works!
Create a certificate
We’ll sign the gem with a self-signed certificate.
For some reason, the install moved the gemspec to the pkg directory. Let’s create it again.
1. > rake build_gemspec
2. > gem cert –build youremail@example.com
3. Important! Move the gem-private_key.pem file to a secure location
Update the gemspec with the certificate information
Add this code to hello_world.gemspec (use your own paths, of course):
s.signing_key = '/Volumes/Secure/Certificates/gem-private_key.pem' s.cert_chain = ['gem-public_cert.pem']
Create the gem
Now we’re getting close. This command will build the gem with your certificate.
> gem build hello_world.gemspec
Add the project to git
1. create the repository on github
2. > git init
3. > git add .
4. > git commit -m “initial commit”
5. > git remote add origin git@github.com:tombombadil/hello_world_gem.git
6. > git push origin master
Host your gem on gemcutter
1. Create a gemcutter account
2. > gem install gemcutter
3. > gem push hello_world-0.0.1.gem
