Creating a RubyGem Package

Summary:

Ruby Gems are the standard way of distributing Ruby applications and library classes. Information on RubyGems can be found at http://www.rubygems.org.

Packaging a Ruby application or library class into a Gem package is not a difficult task by any means. That said, finding straight forward documentation on it was. The Gem Spec Reference was a helpful read, but didn't really put all the pieces together to provide a gem.

Shall we get started?

The Code:

Of course, before we can create a Gem we need a Ruby application or library class. It just so happens that I have one laying around here somewhere...

begin shameless self promotion scheme

ParseConfig is a Ruby class written to parse simple configuration files in the format of 'param = value'. The key benefit is that your ruby scripts can use the same configuration files of most unix/linux applications.

Basic usage:

require('parseconfig')
config = ParseConfig.new('/path/to/my/config/file')
param1 = config.get_value('param1') => value1
param2 = config.get_value('param2') => value2
...

Taking a look at the ParseConfig project we can see the following [basic] file manifest:

./Changelog
./README
./LICENSE
./demo.rb
./demo.conf
./lib/parseconfig.rb

Without packaging into a gem, I could simply copy ./lib/parseconfig.rb to /usr/lib/site_ruby (or wherever the site_ruby directory is) and then do require('parseconfig'). But most people don't find that too fun... and more people probably don't know where that site_ruby directory is... and so on and so forth.

Regardless, we are here to talk about RubyGems so why wouldn't we package it into a gem?

The Gem Spec File

The Gem Specification File does just that... it specifies the who/what/where/when/how for this Gem package. I simply grabbed a spec from another package called Choice, and modified it to my liking:

parseconfig.gemspec:

Gem::Specification.new do |s|
  s.name = %q{parseconfig}
  s.version = "0.4.1"
  s.date = %q{2007-09-03}
  s.authors = ["BJ Dierkes"]
  s.email = %q{wdierkes@5dollarwhitebox.org}
  s.summary = %q{ParseConfig provides simple parsing of standard *nix style config files.}
  s.homepage = %q{http://www.5dollarwhitebox.org/}
  s.description = %q{ParseConfig provides simple parsing of standard *nix style config files.}
  s.files = [ "README", "Changelog", "LICENSE", "demo.rb", "demo.conf", "lib/parseconfig.rb"]
end

Building Our Gem:

Now that we have a gemspec created (mine is called parseconfig.gemspec) we can issue the following command:

wdierkes$ gem build parseconfig.gemspec 
    Successfully built RubyGem
    Name: parseconfig
    Version: 0.4.1
    File: parseconfig-0.4.1.gem

If I do say myself... that was pretty easy.

Installing Our Gem:

We all are familiar with this, but to complete the process we can now install our new gem package:

wdierkes$ sudo gem install parseconfig-0.4.1.gem 
 
Successfully installed parseconfig, version 0.4.1

Using Our Gem:

Since we are using this library via rubygems, we need to require that before our package. The following is a little bit of fun with ParseConfig:

sample.config:

db_host='localhost'
db_user='test_user'
db_password='test_password'
db_db='test_database'

sample.rb:

#!/usr/bin/env ruby
require('rubygems')
require('parseconfig')
 
config = ParseConfig.new('sample.config')
my_real_config = Hash.new()
 
my_real_config['db_host'] = config.get_value('db_host')
my_real_config['db_user'] = config.get_value('db_user')
my_real_config['db_password'] = config.get_value('db_password')
my_real_config['db_db'] = config.get_value('db_db')
 
puts """
connecting to #{my_real_config['db_host']}
using the database #{my_real_config['db_db']}
with user #{my_real_config['db_user']}
and password #{my_real_config['db_password']}
"""

And we get:

wdierkes$ ruby sample.rb 
 
connecting to localhost
using the database test_database
with user test_user
and password test_password

Conclusion:

So, as you can see getting a gem built and ready for distribution is not a big deal. Keep in mind however there are a number of different ways to do this, as well as many more options that can be added to the gemspec. Please look over the Gem Spec Reference for more info.

Additionally, there is this hot new thing called Hoe (no.. not like that). Some may want to play around with that as it has some really cool features.

Reference:

Gem Spec Reference: http://rubygems.org/.../page85