How to Use RubyGems

Failure in using RubyGems seems to be a common problem in #ruby-lang and the documentation is clearly lacking¹. Let’s go through how you are supposed to load a gem called foobar. First of all, the rubygems library has to be loaded. This can be done in three ways:

Passing -rubygems to the Ruby interpreter.
export RUBYOPT="rubygems"
Putting a require "rubygems" in the application².

All three ways are equivalent. Loading the rubygems library does two important things:

It changes the behaviour of require so that it starts looking inside gems if the file isn’t found in the load path. If the library is found in a gem, the load path is changed and the library is loaded.
It adds a require_gem method that looks for a gem with the given name, alters the load path and loads whatever files the packager has specified to be loaded. This way is deprecated, but very useful when you need to load a certain version. (Like this: require_gem("web", "=2.0"))

¹ Yes, I or somebody else should do something about it.

² Not recommended, since not everybody likes or uses RubyGems.