Using and Installing RubyGems

You may be familiar with software packages from other programming languages like CPAN modules, or Python packages, or Pear for PHP. Ruby has its own version, known as Gems. A Ruby Gem may have a library or another command inside of it.

Every gem has:

  • A name

  • A version

  • A platform

For example:

Nokogiri is currently in version 1.4.4.2 and a platform of java. Note that if the RubyGem’s site doesn’t have a platform name after the version, then the platform is ruby meaning the gem can be used anywhere that Ruby can run.

While its possible to host gems anywhere and have them be downloadable, RubyGems is the de facto standard for Gem hosting. So much so that the RubyGems program gem is now distributed with Ruby. This change was made in Ruby 1.9, and now that Ruby 1.8.7 has been put to rest you really shouldn’t be using it anyways, but upgrading is another article

If you managed to get Ruby without installing RubyGems, here’s a quick how to. If you already have it (which you should!) feel free to skip ahead.

Because this will make Rubygems attempt a system wide install (as opposed to installing for a single user) you may not preface the command with sudo. A system wide install is the most common and the easiest install to perform (assuming you have root privileges, you are a system administrator aren’t you?). If you do find yourself in need of other install options you can always take a look at: ruby setup.rb --help

Note that many Linux distributions will offer Rubygems in their flavor of packet management system (apt-get for Debian, yum for CentOS and RedHat, ports for BSD), but as with any packages be aware that you may not be getting the current version. Install RubyGems from the current version on the site isn’t a complex issue so I would suggest sticking to it unless you have some compelling reason not to.

If you already have RubyGems (and I would expect you do if you use Ruby at all), you can make sure that you have the newest version by:

$ gem update --system

Now that you have gem installed you’re ready to work with gems. Installing a gem with a known name is as simple as gem my_gem. It is usually pretty quick for a gem to be installed, the longest process is usually generating the various documentation for ri and RDoc. If you don’t use these or see yourself using them, you can keep them from being installed by editing your gemrc file which is in ~/.gemrc if you’d like to edit for your user only, or /etc/gemrc if you’d like to make it a global setting. Simply add the following line: gem: --no-rdoc --no-ri

There are so many cool and useful gems out now that its easy to get a bit carried away installing them all. If you’d like to see which gems you currently have installed you can use the list command. $ gem list

This will give you the gem name and the currently installed version. Here is a truncated sample from my system:

actionmailer (3.2.12)
actionpack (3.2.12)
activemodel (3.2.12)
activerecord (3.2.12)
activeresource (3.2.12)
activesupport (3.2.12)
arel (3.0.2)
arrayfields (4.9.0)
bigdecimal (1.1.0)
builder (3.0.4)
bundler (1.3.5, 1.3.2)
capybara (1.1.2)
cheat (1.3.3)
chef (11.4.4)

As you may imagine, gem not only handles the install of gems, but also the uninstall: gem uninstall gem_name

So now that you know how to add and remove gems, lets go search for them. You can search for gems on the command line with gem search gemname such as gem search rails. This will give you a result such as:

rails (4.0.0)
rails-3-settings (0.1.1)
rails-action-args (0.1.1)
rails-admin (0.0.0)
rails-ajax (0.1.2.20130211)
rails-alertify (0.3.2)
rails-alpha_numeric_validator (0.1.2)
rails-and-solid (0.9.1)

With long lists this can be a bit of a pain, though you can of course grep through it. Another option is to search using the RubyGems website. The search results will give you not only gem and version info, but also the link to the projects homepage (if there is one) as well as author info and the correct install command.

Those are the most basic operations with gems, search, install, uninstall. How does it work though? Essentially all RubyGems does is modify Ruby’s $LOAD_PATH so that the require statement can find the needed code. That’s it. You may still see code about that has require 'rubygem'. This is a hold over from Ruby 1.8.7 where RubyGems was not included in Ruby automatically, but you’re not using it right?

But if you want to delve a little deeper here are a few more things you can do with RubyGems:

Want to see what a gem actually installed? gem contents <gemname> will list out all the files that an installed gem has created. This can be especially helpful for those gems that have a different require than their gem name. For example:

$ gem list memcache-client

*** LOCAL GEMS ***

memcache-client (1.8.5)

So we know its there, but:

$ ruby -e 'require "memcache-client"'
/opt/local/lib/ruby1.9/site_ruby/1.9.1/rubygems/core_ext/kernel_require.rb:45:in `require': cannot load such file -- memcache-client (LoadError)
from /opt/local/lib/ruby1.9/site_ruby/1.9.1/rubygems/core_ext/kernel_require.rb:45:in `require'
from -e:1:in `<main>'

No go requiring the gem name as is common in most gem. That’s because there is no official standard for the require statement matching the gem name. Usually its something sensical, but we can find out:

$ gem contents memcache-client
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/FAQ.rdoc
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/History.rdoc
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/LICENSE.txt
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/README.rdoc
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/Rakefile
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/bin/memcached_top
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/lib/continuum_native.rb
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/lib/memcache.rb
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/lib/memcache/event_machine.rb
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/lib/memcache/version.rb
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/lib/memcache_util.rb
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/performance.txt
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/test/test_benchmark.rb
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/test/test_event_machine.rb
/opt/local/lib/ruby1.9/gems/1.9.1/gems/memcache-client-1.8.5/test/test_mem_cache.rb

Usually the needed file is the only .rb file inside the lib/ directory of the gem as it is in this case. Since we see memcache.rb here we can be fairly certain that we need to require 'memcache'.

$ ruby -rubygems -e 'require "memcache"'
$ # It worked!!

Chances are that unless you’re developing your own gems, most of your interaction with RubyGems has already been covered. Day to day usage for most people is install, use, uninstall as needed. If however you’re interested in hosting your own gem server or making your own gems send me an email and watch here for future posts or even check out the RubyGems guide.