Navigation
Voterbox
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:
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:
./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:
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:
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:
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_user='test_user'
db_password='test_password'
db_db='test_database'
sample.rb:
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:
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