Creation of a Ruby Gem

Written by | 11 minutes read | Tags ruby, programming | Comments

Everything should be made as simple as possible, but not simple.

Albert Einstein

This article describes the crafting of a Ruby gem.

The situation: For Jekyll I wanted to get an overview of how many pages, links, when the last build was, how many images I used in my blog, and when I lastly updated my Bitbucket repositories. But before we dive deep into the creation, I will explain what a gem is and how you get started with writing your own gem. Don’t be afraid if you are writing a gem that already exists, your goal is to learn how to write a gem.

Ruby Gem

A Ruby gem is a self contained Ruby application which is packed as software. It can be downloaded and then used in other programs. Gems extends the core Ruby language through functions that are commonly used and may be of usage by other programmers. Many gems provides command line operations and help to automate tasks. Not all gems needs to contain a binary, like my sweetie gem.

Basic structure of a Gem

Below is a typical structure of gem:

├── Rakefile
├── lib
│   ├── sweetie
│   │   ├── bitbucket.rb
│   │   ├── conversion.rb
│   │   └── helper.rb
│   │   ...
│   └── sweetie.rb
│   ...
├── spec
│   ├── sweetie_bitbucket_spec.rb
│   └── sweetie_conversion_spec.rb
│   ...
└── sweetie.gemspec

A typical gem consists of the main class file (like sweetie.rb). This file contains other ruby-files (normally a list of require statements). The briefly explains what the gem does, how to install it, explains the license, and should include small use cases for the gem (please checkout the README of the sweetie gem to see what I mean). The sweetie.gemspec file contains meta-information like who invented the gem, declare runtime environment dependencies, etc. A gem should have test-files, that other people can contribute to the Gem without damaging the main functionality.

Gemfile structure

First of all we create a Gemfile which defines important informations for the website. The site shows the author, the sources, the homepage, and some statistics (e.g. how often the gem was installed) - and by the way, it’s a nice place to sniff in the code of other hackers.

Here is an example sweetie.gemspec:

$:.push File.expand_path("../lib", __FILE__)
require 'sweetie/version' do |s|             = 'sweetie'
  s.version          = Sweetie::VERSION             = '2012-06-05'
  s.authors          = ['Matthias Guenther']            = ''
  s.homepage         = ''

  s.summary          = %q{Be short and precice!}
  s.description      = %q{Here you can write more and describe detailed features!}

  s.files            = `git ls-files`.split("\n")
  s.test_files       = `git ls-files -- {test,spec,features}/*`.split("\n")
  s.require_paths    = ["lib"]

  s.extra_rdoc_files = [""]

  s.add_runtime_dependency 'nokogiri', ">= 1.4.6"
  s.add_runtime_dependency 'json', ">= 1.6.1"
  s.add_development_dependency 'rake'
  s.add_development_dependency 'rspec'
  s.add_development_dependency 'yard'

Let’s explain the stuff which aren’t obvious:

Building and Installing the Gem

Once you have created some code (it doesn’t matter how small the code is, except it must be valid and tested ruby code), you should build it on your local machine before making it public:

$ gem build sweetie.gemspec
=> Successfully built RubyGem
  Name: sweetie
  Version: 1.0.0
  File: sweetie-1.0.0.gem

Now you can install the gem locally:

$ gem install sweetie-1.0.0.gem

And test the installation with:

$ gem list | grep sweetie
$ irb
>> require 'sweetie'
=> true

It’s working and you can experiment with the script locally.

Publishing your gem

First, you need to register on After that you can push the gem there with one simple command:

gem push sweetie-1.0.0.gem
Pushing gem to
Successfully registered gem: sweetie (1.0.0)

If you want to check if your gem is online, the console is your friend:

gem list -r sweetie


sweetie (1.0.0)

This will print all the gems which fit to the specified gem.


It is easy to write an gem for ruby. Start small, create a repository on GitHub get something similar to hello world running, test your code with , and create a briefly documentation (read Zach Holman documentation talk to see why) about what the gem does, and give small examples. After this test your gem, deploy it on and spread the word about your accomplished on twitter - time to drink a beer!

Further reading