Distributing and Releasing Ruby Libraries As Gems

(The text below is adapted from Peter Cooper's book - Beginning Ruby.)

To solve various problems with Ruby, you might develop your own libraries. Also, you might want to open-source your libraries to get community input and a larger developer base.

RubyGems, is a library installation and management system for Ruby. With RubyGems it is easy to create "gems" of your own from your own code.

Creating a Gem

Let's first create a simple library that extends the String class and puts it in a file called string_extend.rb:

This code adds a writesize method to the String class, which returns the size of the string.

As a local library within the scope of a larger application, it could be loaded with require:

However, you want to turn it into a gem that you can use anywhere. Building a gem involves three steps.

  • The first is to organize your code and other files into a structure that can be turned into a gem.
  • The second is to create a specification file that lists information about the gem.
  • The third is to use the gem program to build the gem from the source files and the specification.

Structuring Your Files

First, it's necessary to create a folder to contain all the gem's folders, so you create a folder called string_extend. Under this folder you create several other folders as follows:

  • lib: This directory will contain the Ruby code related to the library.
  • pkg: This is a temporary directory where the gem will be generated.
  • test: This directory will contain any unit tests or other testing scripts related to the library.
  • doc: This is an optional directory that could contain documentation about the library, particularly documentation created with or by rdoc.
  • bin: This is another optional directory that can contain system tools and command line scripts that are related to the library. For example, RubyGems itself installs the gem command line tool; such a tool would be placed into bin.

At a minimum, you should end up with string_extend/lib, string_extend/pkg, and string_extend/test.

In this example, you should place string_extend.rb within the string_extend/lib directory. If you have tests, documentation, or command line scripts, place them into the respective directories.

Creating a Specification File

Once your files are organized, it's time to create a specification file that describes the gem and provides RubyGems with enough information to create the final gem. Create a text file called string_extend.gemspec in the main string_extend folder, and fill it out like so:

This is a basic specification file. The specification file is effectively a simple Ruby script that passes information through to Gem::Specification. The information it provides is mostly simple, but let's look at a few key areas.

First you define the name of the gem, setting it to 'string_extend':

Next, you define the version number. Typically, version numbers for Ruby projects (and for Ruby itself) contain three parts in order of significance. Early versions of software, before an official release, perhaps, often begin with 0, as in 0.0.1 here:

The summary line is displayed by gem list, and can be useful to people prior to installing the gem. Simply put together a short description of your library/gem here:

The files attribute accepts an array of all the files to include within the gem. In this case you use Dir.glob to get an array of all the files under the current directory:

However, you could explicitly reference every file in an array in the preceding line.

The test_files attribute, like the files attribute, accepts an array of files, in this case associated with tests. You can leave this line intact even if you have no test folder, as Dir.glob will just return an empty array. For example:

The autorequire parameter specifies a file to be loaded automatically with require when the gem is loaded. This parameter isn't particularly important, because users will generally use require 'string_extend' in their code anyway, but if your gem contains multiple Ruby files that need to be loaded, it could come in handy:

Last, sometimes libraries rely on features in certain versions of Ruby. You can specify the required version of Ruby with the require_ruby_version parameter. If there's no required version, you can simply omit this line:

Building the Gem

Once the specifications file is complete, building the final .gem file is as simple as:

In our case:

This makes gem create the final gem file, string_extend-0.0.1.gem.

Note: In future, once you change and update your library, simply update the version numbers, rebuild, and you have a new gem ready to go that can be installed to upgrade the existing installed gem.

Distributing a Gem

Distributing a gem is easy. You can upload it to a Web site or transfer it in any way you would normally transfer a file. You can then install the gem with gem install by referring to the local file.