Appendix A. Installing Ruby

Installing Ruby is a fairly trivial affair, but there are a few things worth paying attention to. You will want to use gems extensively, and not all installations include RubyGems by default. You may also want to use gems that take advantage of C extensions (for example, MySQL drivers and the Mongrel web server), which require that you have the proper development libraries and tools. In this appendix, we provide you with the simplest steps for installing a fully functional and up-to-date version of Ruby 1.8 on Windows, Mac OS X, and Linux.

Once Ruby is running, look at the A.4 section, where we provide useful tips for improving IRB (the Interactive Ruby Interpreter) and accessing documentation for all gems installed on your machine.

A.1. Installing on Windows

If you’re using Windows, you have three options. You can get the latest version of Ruby directly from the ruby-lang.org web site, with downloads for either Ruby 1.8 or 1.9. When you download the Ruby interpreter, it includes command-line tools like RDoc, IRB, and RI, but does not include RubyGems or many of the other libraries you need to get started.

In our experience, hunting down and installing libraries like RubyGems, FCGI, or OpenSSL is not fun, and we’ve got better things to do. A better alternative is to use the one-click Ruby installer, available from http://rubyinstaller.rubyforge.org. It includes many of the common libraries you need to get started, libraries for accessing various Windows APIs, a good programmer’s text editor (Scite), and a PDF copy of the first edition of Programming Ruby.

If you’re interested in building Rails applications, consider Instant Rails, available from http://instantrails.rubyforge.org. Instant Rails includes all the same libraries as the One-Click Ruby Installer, and adds recent versions of Rails, Mongrel, MySQL, and Apache. It’s the quickest way to install a working environment for developing and deploying web applications.

Before you get started, we recommend upgrading to the latest version of RubyGems, which offers important performance and usability improvements:

Now you’re all set and ready to go.

A.2. Installing on Mac OS X

Mac OS X 10.5 (Leopard) comes with Ruby 1.8.6 preinstalled and also includes Rails, Mongrel, Capistrano, and a few other gems.

It works well, but before you get started, we recommend upgrading to the latest version of RubyGems, which offers important performance and usability improvements:

The different release schedules mean that Leopard does not include the most recent versions of Rails and Mongrel, but this is not a problem, since those are safe to upgrade using sudo gem update.

Mac OS X 10.4 (Tiger) includes Ruby 1.8.2, but many of the libraries you will want to use no longer support 1.8.2. For example, Rails requires 1.8.4 or later. The easiest way to upgrade to a more recent version of Ruby is using the Ruby One-Click installer for OS X available from http://rubyosx.rubyforge.org.

Alternatively, you can install Ruby using either MacPorts or Fink. For example, to install Ruby with RubyGems using MacPorts, run this command:

Ruby support on Mac OS X is excellent, but in spite of that we did run into a couple of gotchas. Occasionally, gems that use C extensions will fail to recognize libraries installed outside the main directories (for example, libraries installed using MacPorts). These are easy to fix by passing specific compile/build options to gem install, like this:

MySQL adds another twist. By default, C extensions are built as universal binaries, but MySQL ships with per-architecture binaries. You can force Ruby to build extensions for a particular architecture by setting the ARCHFLAGS environment variable. To install MySQL on the Intel architecture:

For PowerPC, replace -arch i386 with -arch ppc.

A.3. Installing on Linux

You can compile from source on any Linux distribution, but most of them offer a binary package also. For example, installing Ruby on Red Hat Fedora couldn’t be easier. Just go into the terminal and use the package manager:

The ruby package provides the generic command-line utilities, while ruby-devel provides header files, and gcc the compiler, both of which are necessary for installing gems that use C extensions, such as Mongrel and MySQL.

Most likely, this will install an older version of RubyGems. We recommend upgrading to the latest version, which offers important performance and usability improvements:

Installing Linux on Ubuntu/Debian takes a bit more effort. For starters, the ruby package will install the Ruby interpreter but none of the command-line tools (RDoc, IRB, etc.). Use the meta-package ruby-full to install all the relevant command-line tools.

To build gems that use C extensions, you’ll need both ruby1.8-dev and, if you don’t already have them, the various build tools like GCC and Make, provided by the build-essentials package:

If you install the Debian rubygems package, you may find that it only supports installing Ruby gems using apt-get. Only a fraction of Ruby gems are available through the Debian package manager. We recommend you install a fully functional version of RubyGems by downloading it from the RubyForge project:

Remember that certain gems use C extensions, which in turn require header files to compile. For example, to install the Ruby MySQL gem, it is not enough to have MySQL installed on your machine; you must also install the MySQL developer package:

A.4. More tips

Now that you have Ruby installed, it’s time to customize your environment to use Ruby gems and IRB effectively. We’re going to cover three simple setups that we find indispensable in every environment. They’ll make it easier to run Ruby scripts, enhance the IRB, and let you access documentation for the various gems you install.

A.4.1. Requiring RubyGems with RUBYOPT

One thing we find annoying about Ruby is that it still treats RubyGems as an optional extension that you have to install separately. And since it’s optional, you also have to require 'rubygems' in any program that uses gems.

You can get around this by setting the RUBYOPT environment variable to the value rubygems. On Windows, you can set this environment variable using the Control Panel—the One-Click Ruby Installer will automatically do that for you.

On Mac OS X, Linux, and other flavors of UNIX, you can add this line to your .profile:

A.4.2. Improving IRB with Wirble

If, like us, you work from the command line and use IRB or the Rails console, which itself uses IRB, we highly recommend installing Wirble. Wirble adds tab-completion, history, a built-in ri command, and colorized output.

Note

UtilityBelt If you’re really into extending irb, a library named Utility Belt adds more extensions to irb than we could cover in this whole book. Grab it from http://github.com/gilesbowkett/utility-belt.

Once you install Wirble (gem install wirble), create a file called .irbrc in your home directory and add the following lines to it:

Don’t add the last line if you don’t like colors in your console, or if you are running from the Windows command line, which doesn’t support ANSI colors.

Once you have Wirble installed, you can use tab-completion on Ruby classes, modules, and methods. For example, begin by typing Obj and press the Tab key once to expand it to Object. Continue by typing a period (.) and press the Tab key again to reveal all the methods on the Object class.

Not sure what a class or method does? You can get help from within IRB by running the ri method with a class, module, or method name, like this:

You can also use the up and down arrow keys to go back in history.

A.4.3. Accessing Ruby’s documentation

As intuitive as Ruby is, you won’t get far without knowing the APIs, and that means looking up the documentation. Ruby comes with two tools that let you access documentation using the command line or your web browser.

You can use the command-line tool ri to request information about any class, module, or method from both the core library and any installed gem, like this:

You can use the gem server to access documentation for all installed gems from your web browser. This method makes it much easier to navigate through the documentation. In addition to class and method documentation, many gems also include a README file containing valuable information about the gem and its usage, alongside links to the official web site.

Start by running the gem server from the command line:

Then point your browser to http://localhost:8808. You now have documentation for all of your gems at your fingertips.