Disco Vilante

Ruby on Rails with a sprinkling of Apple and Startup dust.

Rails Install for Beginners Part 14: Ruby Gems

Part 14 in a series of articles on setting up a Ruby on Rails environment for those new to programming and Rails.

Ruby Plugin Libraries

With RVM up and running, and our selected Ruby installed, we are ready to dive into the world of RubyGems, the comprehensive plugin architecture for the Ruby Language. Together with Bundler, which provides installation and dependency management for gems, RubyGems and RVM provide all the components needed to install Rails and many of the extensions that you will come to rely on as a Rails developer.

There are tens of thousands of open source gems published by the Ruby community and your projects will likely depend on many of them. As a new developer any community knowledge that can accelerate your application development is a significant benefit. With time and experience you will hopefully contribute back to the community by getting involved with one of more of the gems that you depend on.

Configuring RubyGems is fairly easy but knowing where to find, and how to select, good gems that will make a difference to your projects is a bit more challenging. Detail on both follow in this article.

RubyGems.org

RubyGems.org provides a community hosting service for those looking to publish gems and as a result it is also one of the best places to look for interesting plugins for your applications. It provides the packaging system, which is installed automatically with Ruby 1.9 and above, for both publishing gems and installing them.

The specification and publishing components of RubyGems are not as important for the new developer, at least for now, so we will focus instead on configuration and use.

It is worth noting beforehand that with the arrival on the scene of Bundler, discussed in depth in the next article in this series, the need to use the RubyGem interface to install and update gems has greatly diminished, particularly for Rails projects. There will still be some requirements for manual installation in some situations which are touched on below.

Installing Rubygems

As RubyGems is included with Ruby 1.9 you will be able to start using the gem command as soon as Ruby is installed. For earlier Ruby versions you can easily download the latest version from the RubyGems download page. In any event it will be useful to update to the current version, which is also outlined on the download page.

Note that RVM has a built in function to download RubyGems, as outlined on the RVM RubyGems page, which I recommend using. The main benefit here is easier to remember commands to update the RubyGems system and an easier approach to install a specific version of RubyGems if required. In practice it won’t matter much which approach you use, so choose the one that works best for you.

A Note on Naming

You may see references to “Gemcutter” in articles and blog posts on the web. Gemcutter is simply an earlier name for RubyGems. You can safely use RubyGems in the place of Gemcutter in any code or config files you require.

Configuring RubyGems

The following configuration flag, set in the .gemrc file in your home directory, will improve operation of RubyGems.

1
2
install: --no-rdoc --no-ri
update: --no-rdoc --no-ri

This simply tells RubyGems not to install the internal documentation that comes with the gems when either installing or updating gems. “RDoc” is the Ruby Documentation library which generates HTML documentation from Ruby code while “RI” is the Ruby Information tool, an alternative. I have found that better documentation tends to exist on gem project pages, or on the web at large, and in any case the RDoc information for every gem is published on the RubyDoc.info website for easy access.

RDoc and RI can increase the install time for gems significantly so, given the documentation is available elsewhere, it’s worth turning them off.

Be careful in copying other config items from .gemrc files you may find online. I have found that they are generally unnecessary as they merely copy the standard RubyGems settings, or they are well out of date and include gem sources which are no longer relevant to RubyGems.

Gem Commands

RubyGems have a comprehensive command reference which outlines details of all the gem commands. For the new developer it may look a little overwhelming but there are only a few commands which are really necessary for installing and managing gems rather than building them, especially after the introduction of Bundler which now manages most of the gem environment for Rails projects.

I will outline the key commands that the new developer should understand. Each one also has more detail in the command reference.

1
$ gem install GEMNAME -v x.x

To kickstart your Rails environment you are going to need install a few gems, the least of which is Bundler. The -v flag installs a particular version of a gem rather than the most recent stable version. You don’t have to specify a version but out of all the options for the gem install command this is the one that is most likely to be used in general development.

1
$ gem list

Simply lists the currently installed gems, including versions numbers. Note that multiple versions may be installed at the same time, and all versions installed will be listed by this command.

1
$ gem env

Provides some interesting information about your gem environment.

1
$ gem search

Allows a command line search of all gems. If you provide a string then it will narrow the search. I prefer to search directly on the RubyGems website rather than the command line, but feel free to use what works best for you.

1
$ gem uninstall GEMNAME

Removes a specified gem. This command is often specified with a version to be removed with the -v option.

Gem Commands and Bundler

By using Bundler we impact how we approach the use of two specific gem commands which is worth working through.

Both RubyGems and Bundler provide commands to identify outdated gems.

1
2
$ gem outdated
$ bundle outdated

Bundler will only list gems which are specified for a particular project, while RubyGems will also add relevant global gems into the list. Given this behaviour they both have a role to play.

My preferred approach is to use Bundler to determine outdated project gems and use RubyGems only for checking and managing outdated global gems, of which I have relatively few. Therefore you would run bundle outdated within a project directory and gem outdated from your home folder or for projects without Bundler.

In both cases the outdated commands will simply show a list of gems with a comparison of the currently installed version against the most recently available version on RubyGems.

Bundler also impacts the approach to cleaning up old gem versions, providing its own behaviour to remove out of date gem versions for a project which we will discuss in a future article.

For global gems we can use the gem cleanup command to remove the old gem versions which are no longer required. If you run it without options it will cleanup after all gems. You can specify a gem name to only cleanup a particular gem and the -d option will use dry run mode. The cleanup process will review dependencies as it progresses, and if removing a gem would break a dependency then it will ask for confirmation. It is best in this case to keep any identified dependencies installed to ensure that your application continues to run.

It is worth noting that, due to the way Bundler works, there will be very few global gems besides bundler itself. So using gem install, gem outdated, gem cleanup and gem uninstall will not be required all that often.

Gem Selection

With a clearer understanding of the role gems play, and how to interact with them, the next important question is how to find and select them. Before we find them let’s take a short detour into making a selection.

I tend to consider these main components when deciding on a gem:

Is it actively maintained? RubyGems.org provides dates of the most recent versions, the older the date the more likely there may be support and dependency issues for the gem.

How clear is the documentation? No matter how good the gem, if you find it difficult to understand how to use it then it won’t provide the functionality that you need.

How many downloads are there? Although not always the case, gems with higher download counts, that are therefore popular, tend to have more community involvement and are therefore more likely to be maintained well in the future.

Are people writing guides and articles about how to use a gem? A great indicator of both popularity and support for a gem, and more information makes it easier to find answers to the inevitable challenges.

How well does the gem integrate with your other selections? Occasionally gems look promising but they don’t work well with other important components of your application. Trying to get them to work, particularly if no one else is writing about it, can devour significant time.

Don’t just blindly install every gem you find interesting, you need to make a positive decision on each one and how it fits well within your project.

Finding Gems

In terms of finding gems, apart from the stumble upon them approach which tends to happen while searching the web for an answer to an unrelated question, there are a few good sources to choose from.

RubyGems.org

RubyGems is the obvious starting point given they host the gems. The search interface is simple but tends to provide a good selection of relevant gems, along with versions, dependencies and how many downloads have been made so that you can see popularity.

Ruby Toolbox

The Ruby Toolbox provides a great gem catalogue, free for the community. Gems are well categorised and the builders of the site have made an attempt to provide a measure of gem popularity which is more than just the number of downloads. Each gem has links back to documentation and source code in additional to a wealth of other information.

Github

Although we haven’t discussed GitHub in depth, it has generally become the default site for hosting Ruby and Rails related projects. As a result it holds the source code for the majority of the gems that projects use. Direct searching in GitHub can yield some success in finding gems for your projects.

Railscasts

I mentioned Railscasts in the article on TextMate and it is a treasure trove of information and education on Rails - well worth reading and subscribing to. Many of the screencasts that Ryan Bates publishes cover gems and it is a great source of ideas about what could be appropriate for a project.

Ruby Weekly

Ruby Weekly is a free weekly email newsletter, curated by Peter Cooper, which has a great selection of news, articles and libraries/gems.

Ruby 5

Ruby 5 is a short twice weekly podcast, produced by Envylabs, which covers interesting Ruby news and gems.

A Fresh Cup

Mike Gunderloy writes the Double Shot series on A Fresh Cup every day, the amount of interesting articles and code libraries he finds is staggering.

The Changelog

Although not specifically focused on Ruby, The Changelog provides a regular podcast on the open source community, often with comments on interesting code libraries.

Specific Web Searches

Some writers in the Rails community publish their thoughts on gems. Searching may yield some good information to base decisions on.

Installing Gems in Rails

Once we find and choose from all the great gems out there we need to get them installed in our project, and that’s where Bundler comes in. The next article will introduce Bundler and describe how gems are specified and controlled for a Rails project.

I will also be writing an article series on gems in the future which will outline my suggestions for a Gemfile and the reasoning behind each gem within it. Until then you can find plenty of examples online.

Updates

This article was updated: 28th April 2012 - Addition of gem list and gem uninstall commands.


If you have a comment find me on twitter, @nicholasmott, or send me an email, nick@discovilante.com. If you have specific development questions I highly recommend you post them on stackoverflow to both maximise receiving a quick answer and to add to the pool of knowledge for the community. Send me a tweet and I’ll have a look.