Section 21.2. Using Rake

21.1. Using RubyGems

RubyGems is not the "official" package management system for Ruby, but it is the one with the most community support. As of July 2006, it is not part of the standard distribution, but it may be in the future. We had a good overview of the mechanics of gem creation in Chapter 17. In this chapter we're concerned with using gems created by others.

The RubyGems concept exists to solve a few basic problems: ease of installation, centralized repositories, library version management, dependency management, and more. Gems give you easy access to your documentation and easy control over what libraries are installed.

You may not have RubyGems installed on your system. If not, go to http://rubyforge.org/projects/rubygems and follow the simple instructions for download and installation. After the first install, RubyGems can of course update itself.

The actual executable is called gem. It has a command structure similar to that of cvs or similar tools; that is, there are subcommands and options that make sense for each subcommand. The usage information is as follows:

RubyGems is a sophisticated package manager for Ruby.  This is a basic help message containing pointers to more information.   Usage:     gem -h/--help     gem -v/--version     gem command [arguments...] [options...]   Examples:     gem install rake     gem list --local     gem build package.gemspec     gem help install   Further help:     gem help commands            list all 'gem' commands     gem help examples            show some examples of usage     gem help            show help on COMMAND                                    (e.g. 'gem help install')   Further information:     http://rubygems.rubyforge.org

The most basic usage is simple. If (for example) you want to install the feedtools library, you can issue this command:

gem install feedtools

This will first look for a local gem file; if it doesn't find one, it will look on the RubyForge server. By default, it gives you the latest version (though in some cases it may prompt you to clarify which gem you want). You can also specify a version with -v or --version if necessary. There are several other options for controlling the installation; issue the command gem help install for more information.

Sometimes a gem will have dependencies on other gems. In such a case, you will be prompted as to whether you want to install each dependency. Obviously, if you don't install them, the gem you were after can't be installed.

How do you know what to install in the first place? Well, if the item is on RubyForge, it normally has a gem there named with the "UNIX name" of the project. For example, the rake tool can be accessed through http://rubyforge.org/projects/rake or simply http://rake.rubyforge.org; therefore gem install rake will install it.

If you don't even know that much, the gem search command may be useful to you. Specify a fragment of the name of a gem, and it will search for all related gems. By default it will search locally; use the --remote flag to search the repository. For example, when I issue gem search xml --remote on my system, I get 12 results.

To get information on an installed gem, use the gem specification command; it dumps all the available metadata (basically the gemspec itself) to output. There is a --remote flag, but at the time of this writing it is not yet implemented.

There is also an uninstall subcommand that is convenient, and the query and list commands seem to overlap with each other a little (and with search). Many other commands also are available; consult the built-in documentation or the online documentation for more details.

It's useful to run a gem server on your systemnot in the sense of a repository from which other people can install but in the sense of a centralized location where you can view all your local gems (and their documentation) via a web browser.

To run the gem server, simply invoke the gem_server executable. (Normally you would run it in the background.) When you then open your browser to the URL localhost:8808, you will see a page titled "RubyGems Documentation Index." All your installed gems are listed alphabetically, with links to the rdoc documentation and to the gem's home page on the Web.

There is more to RubyGems, and the system is still changing. Refer to http://rubygems.rubyforge.org for the latest information.