Installing and Using a Gem

Problem

You want to install a gem, then use the code it provides in your programs.

Solution

You can install the latest version of a gem with the gem install command. This command looks for an uninstalled gem file on your local system; if it can find one, it calls out to an external source (gems.rubyforge.org, unless you specify otherwise) asking for a gem file. Since gem install changes the system-wide Ruby installation, youll need to have superuser access to run it.

	$ gem install RedCloth
	Attempting local installation of RedCloth
	Local gem file not found: RedCloth*.gem
	Attempting remote installation of RedCloth
	Successfully installed RedCloth-3.0.4

A gem contains standard Ruby code files, and once you install the gem, you can require those files normally and use the classes and modules they define. However, gems are not installed in the same path as the standard Ruby libraries, so youll need to tell Ruby to supplement its normal library path with the path to the gems. The simplest way is to require ubygems in any program that uses a gem, before you write any require statements for libraries installed via gems. This is the solution we use throughout this book.

	# This code assumes the "redcloth" gem has been installed, as in the
	# code above.
	require 
edcloth
	# LoadError: no such file to load -- redcloth

	require  
rubygems
	require 
edcloth
	parser = RedCloth::CommandParser.new
	# …

For a solution that works across Ruby scripts, youll need to change your Ruby runtime environment, either by setting the RUBYOPT environment variable to rubygems, or by aliasing your ruby command so that it always passes in a -rubygems option to the interpreter.

	$ ruby -e "require 
edcloth; puts Success"
	-e:1:in `require: no such file to load -- redcloth (LoadError)
	 from -e:1

	$ ruby -rubygems -e "require 
edcloth; puts Success"
	Success

	# On Unix:
	$ export RUBYOPT=rubygems
	$ ruby -e "require 
edcloth; puts Success"
	Success

	# On Windows:
	$ set RUBYOPT=rubygems
	$ ruby -e "require 
edcloth; puts Success"
	Success

Discussion

Once youve installed a gem, you can upgrade it to the latest version with the gem update command. Even if youve already got the latest version, youll see output like this:

	$ gem update RedCloth
	# 
Upgrading installed gems…
	# Attempting remote upgrade of RedCloth
	# Attempting remote 
installation of RedCloth
	# Successfully installed RedCloth-3.0.4
	# Gems: [redcloth] updated

You might install a gem for your own use, or because its required by a program you want to run. If you want to use a gem in your own programs, theres no reason not to always use the latest version. Some programs, though, impose version constraints that force you to install a particular version of a gem.

Rubys gem system can keep multiple versions of the same gem installed at once. You can satisfy one programs archaic dependencies while still being able to use the latest version of a gem in your own programs. To install a specific version of a gem, append the version number to the name, or specify a --version argument to gem install.

	$ gem install RedCloth-3.0.4
	$ gem install RedCloth --version "3.0.4"

Use the technique described in Recipe 18.3 to require the one thats right for your program.

A program that imposes a version constraint doesn usually tell you which specific version of a gem you need to install. Instead, it crashes with an error that tells you which contraint string you need to meet. Again, you can see Recipe 18.3 for more on constraint strings, but they look like >2.0 or <= 1.6. You can install a version of a gem that satisfies a constraint string by passing the contraint as a --version argument to gem install. The gem command will find and install the latest version that meets that constraint.

	$ ruby -e "require  
rubygems; require_gem units, ~>1.0 puts Units"
	/usr/local/lib/site_ruby/1.8/rubygems.rb:204:in `report_activate_error:
	Could not find RubyGem units (~> 1.0) (Gem::LoadError)

	$ gem install units --version "~> 1.0"
	Attempting remote 
installation of units
	Successfully installed units-1.0.1
	Installing RDoc documentation for units-1.0.1…

	$ ruby -e "require 
ubygems; require_gem units, ~>1.0; puts Units"
	Units!

Whether you run the gem install command, or install a gem from Ruby code that you write, youll need to have the proper permissions to write to your gem directory.

When you install a gem from the command line, the gem command will offer you a chance to install all other gems on which it depends. You can have gem install the dependencies without prompting by passing in the --include-dependencies flag. This invocation installs the rubyful_soup gem and the htmltools gem on which it depends:

	$ gem install rubyful_soup --include-dependencies
	Attempting local installation of 
ubyful_soup
	Local gem file not found: rubyful_soup*.gem
	Attempting remote installation of 
ubyful_soup
	Successfully installed rubyful_soup-1.0.4
	Successfully installed htmltools-1.09
	Installing RDoc documentation for rubyful_soup-1.0.4…
	Installing RDoc documentation for htmltools-1.09…

You can install a gem from Ruby code by creating a Gem::Installer or Gem::RemoteInstaller object, and calling its install method. The install method will return an array containing a Gem::Specification object for the gem that was installed.

Heres a simple method that mimics the behavior of the gem install command, looking for a local copy of a gem before going out to the network:

	require  
rubygems/installer
	require 
ubygems/remote_installer

	def install_gem(gem_name)
	 if File.file? gem_name:
	 Gem::Installer.new(gem_name).install
	 else
	 Gem::RemoteInstaller.new.install(gem_name)
	 end
	end

	install_gem(
edcloth)
	# Updating Gem source index for: http://gems.rubyforge.org
	# => [#


To install a gem from Ruby code, you must first go through all of its dependencies and install them, too.


See Also
Recipe 18.3, "Requiring a Specific Version of a Gem"