Announcing Foundry

A new generation of vector illustrations and infinite possibility for the interactive web.

Install Ruby on Rails on Mac OS X Mavericks

March 14, 2014

Installing Ruby on Rails 4.0 on Mac OS X Mavericks. This in-depth installation guide is used by professional developers to configure their working environment for real-world Rails development. To use Rails on Mac OS X, you’ll need Ruby (an interpreter for the Ruby programming language) plus gems (software libraries) containing the Rails web application development framework.

If you want to install Ruby on Rails on Ubuntu, you can see this guide: Install Ruby on Rails on Ubuntu Linux

Ruby on Rails for Mac OS X Mavericks

Mac OS X comes with a “system Ruby” pre-installed. Mac OS X Mavericks includes Ruby 2.0.0p247 which has a known security vulnerability. You should update to Ruby 2.1.0 by using RVM. If you are maintaining older Rails applications, you will likely need to install Ruby 1.9.3. And in the future, you will need to install newer Ruby versions as they are released. Even if you are a student only building new Rails applications, you should be prepared to manage multiple versions of Ruby.

If You Updated to Mac OS X Mavericks

This guide covers installing Ruby and Rails on a Mac with no previous installation of a Rails development environment. If you updated to Mavericks from an earlier version of Mac OS X, and you previously installed a Rails development environment, your earlier installation remains intact. You will need to install the new version of Xcode Command Line Tools. If you previously installed the full Xcode package, you will need to update Xcode to the newest version (Xcode 5.01 or newer).

Use a Ruby Version Manager (RVM)

You’ll need an easy way to switch between Ruby versions. Just as important, you’ll have a dependency mess if you install gems into the system environment. I recommend RVM to manage Ruby versions and gems because it is popular, well-supported, and full-featured. If you are an experienced Unix administrator, you can consider alternatives such as Chruby, Sam Stephenson’s rbenv, or others on this list. You can use RVM to install Ruby too.

Don’t Use a One-Click Installer

You may hear about one-click installation programs such as RailsInstaller, Cinderella, and BitNami RubyStack. These installation programs are often outdated and they are no longer needed as RVM will set up almost everything needed to install Ruby. In particular, I don’t recommend RailsInstaller for experienced developers as it installs RVM at the system level creating potential conflicts.

A Hosted Development Alternative

You can use Ruby on Rails without actually installing it on your computer. Hosted development, using a service such as Nitrous.io, means you get a computer “in the cloud” that you use from your web browser. Any computer can access the hosted development environment, though you’ll need a broadband connection. Nitrous.io is free for small projects.

Using a hosted environment means you are no longer dependent on the physical presence of a computer that stores all your files. If your computer crashes or is stolen, you can continue to use your hosted environment from any other computer. Likewise, if you frequently work on more than one computer, a hosted environment eliminates the difficulty of maintaining duplicate development environments. For these reasons some developers prefer to “work in the cloud” using Nitrous.io. For more on Nitrous.io, see the article Ruby on Rails with Nitrous.io. Nitrous.io is a good option if you have trouble installing Ruby on Rails on your Mac.

Prepare Your Computer

Upgrade Mac OS X to 10.9

Make sure you have the latest version of Mac OS X. Under the Apple menu, check “About This Mac.” It should show “Version 10.9” or newer. If you’ve owned your Mac for several years and haven’t updated Mac OS X, be prepared to spend several hours updating the operating system. If you need to upgrade, see Apple’s instructions How to upgrade to OS X Mavericks. You can install Mac OS X 10.9 (Mavericks) from the Mac App Store for free. Allow plenty of time for the download and installation (it may take several hours).

Terminal Application

You’ll need to use the Terminal application to install Ruby and develop Rails applications. The Terminal application or console gives us access to the Unix command line, or shell. We call the command line the shell because it is the outer layer of the operating system’s internal mechanisms (which we call the kernel). Find the Mac OS X Terminal application by using the Command-Spacebar combination and searching for “Terminal.” It’s in the Applications/Utilities/ folder.

Try out the terminal application by entering a shell command:

$ whoami

Don’t type the $ character. The $ character is a cue that you should enter a shell command. This is a longtime convention that indicates you should enter a command in the terminal application. The Unix shell command whoami returns your username.

Is Xcode Already Installed?

You don’t need the full Xcode package to get the Xcode Command Line Tools. You only need the full Xcode package if you are doing development of applications for the Apple operating systems. However, you may have previously installed the full Xcode package. Check if the full Xcode package is already installed:

$ xcode-select -p

If you see:

/Applications/Xcode.app/Contents/Developer

the full Xcode package is already installed.

You will need to update Xcode to the newest version (Xcode 5.01 or newer). Go to the App Store application and check “Updates.” After updating Xcode, be sure to launch the Xcode application and accept the Apple license terms.

If you see a file location that contains spaces in the path:

/Applications/Apple Dev Tools/Xcode.app/Contents/Developer

You must delete Xcode. RVM cannot accommodate spaces in a path so RVM will fail when you attempt to install Ruby. You can either install only the Xcode Command Line Tools (instructions below) or reinstall the full Xcode package.

Install Xcode Command Line Tools

The Xcode Command Line Tools provide a C language compiler needed to install Ruby. For many Rails projects, you will need the C language compiler to install gems that use native extensions.

Mac OS X Mavericks will alert you when you enter a command in the terminal that requires Xcode Command Line Tools. For example, you can enter gcc, git, or make.

Try it. Enter:

$ gcc

You’ll see an alert box:

Click “Install” to download and install Xcode Command Line Tools. You don’t need to “Get Xcode” from the App Store. Just click “Install” for the Xcode Command Line Tools.

Verify that you’ve successfully installed Xcode Command Line Tools:

$ xcode-select -p
/Library/Developer/CommandLineTools

Just to be certain, verify that gcc is installed:

$ gcc --version
Configured with: --prefix=/Library/Developer/CommandLineTools/usr --with-gxx-include-dir=/usr/include/c++/4.2.1
Apple LLVM version 5.0 (clang-500.2.79) (based on LLVM 3.3svn)
Target: x86_64-apple-darwin13.0.0
Thread model: posix

On earlier versions of Mac OS X, it was more difficult to install Xcode Command Line Tools. It required a huge download of the full Xcode package from the Mac App Store or registration as an Apple developer for a smaller Command Line Tools package. Mac OS X Mavericks makes installation of Xcode Command Line Tools much simpler.

Configure Git

Before installing Ruby on Rails, you should configure Git. Git provides a source control repository. Developers use Git to roll back code changes as needed, to collaborate with others, and deploy applications for hosting with a service such as Heroku. As a Rails developer, you’ll use Git with a GitHub account for remote backup and collaboration. See the article Rails with Git and GitHub for more background.

Check that Git is installed:

$ git version
git version 1.8.3.4 (Apple Git-47)

Git is automatically installed as part of the Xcode Command Line Tools. Or, if you updated from a previous version of Mac OS X, you may have installed Git previously.

Configure Git if you haven’t used it before. First, list the current settings with the git config -l --global command. Then set user.name and user.email if necessary:

$ git config -l --global
fatal: unable to read config file '/Users/.../.gitconfig': No such file or directory
$ git config --global user.name "Your Real Name"
$ git config --global user.email me@example.com
$ git config -l --global
user.name=Your Real Name
user.email=me@example.com
Now you’ll be ready to use Git when you need it.

Install Ruby Using RVM

Use RVM, the Ruby Version Manager, to install Ruby and manage your Rails versions.

RVM will leave your “system Ruby” untouched and use your shell to intercept any calls to Ruby. There’s no need to remove it. The “system Ruby” will remain on your system and the RVM version will take precedence.

Ruby 2.1.0 was current when this was written. You can check for the current recommended version of Ruby. RVM will install the newest stable Ruby version.

The RVM website explains how to install RVM. Here’s the simplest way:

$ \curl -L https://get.rvm.io | bash -s stable --ruby

Note the backslash before “curl” (this avoids potential version conflicts).

The “—ruby” flag will install the newest version of Ruby.

RVM includes an “autolibs” option to identify and install components needed for your operating system. See the article RVM Autolibs: Automatic Dependency Handling and Ruby 2.0 for more information.

On a new, clean version of Mac OS X, RVM will check requirements and install MacPorts (you may need to enter your user password). RVM will update your system and install dependencies required for installing Ruby on Mac OS X. You may be prompted to install a Java SE 6 runtime (for the javac Java compiler).

If You Already Have RVM Installed

If you already have RVM installed, update it to the latest version and install Ruby:

$ rvm get stable --autolibs=enable
$ rvm install ruby
$ rvm --default use ruby-2.1.0

Installation Troubleshooting and Advice
If you have trouble installing Ruby with RVM, see the article “Installing Ruby” for Installation Troubleshooting and Advice. If you have problems installing RVM, use Nitrous.io.

Check the Gem Manager

RubyGems is the gem manager in Ruby. Check the installed gem manager version:

$ gem -v
2.2.0

Use gem update --system to upgrade the Ruby gem manager if necessary.

RVM Gemsets

Not all Rails developers use RVM to manage gems, but many recommend it.

Display a list of gemsets:

$ rvm gemset list

gemsets for ruby-2.1.0
=> (default)
global

Only the “default” and “global” gemsets are pre-installed. If you get an error “rvm is not a function,” close your console and open it again.

RVM’s Global Gemset

See what gems are installed in the “global” gemset:

$ rvm gemset use global
$ gem list

A trouble-free development environment requires the newest versions of the default gems.

Several gems are installed with Ruby or the RVM default gemset:

bundler (1.5.1) check for newer version
bundler-unload (1.0.2) check for newer version
rake (10.0.1) check for newer version
rubygems-bundler (1.4.2) check for newer version
rvm (1.11.3.8) check for newer version

To get a list of gems that are outdated:

$ gem outdated
### list not shown for brevity

To update all stale gems:

$ gem update
### list not shown for brevity

In particular, rake should be updated to version 10.1.1 or newer.

Faster Gem Installation

By default, when you install gems, documentation files will be installed. Developers seldom use gem documentation files (they’ll browse the web instead). Installing gem documentation files takes time, so many developers like to toggle the default so no documentation is installed.

Here’s how to speed up gem installation by disabling the documentation step:

$ echo "gem: --no-document" >> ~/.gemrc

This adds the line gem: --no-document to the hidden .gemrc file in your home directory.

Staying Informed

You can stay informed of new gem versions by creating an account at RubyGems.org and visiting your dashboard. Search for each gem you use and “subscribe” to see a feed of updates in the dashboard (an RSS feed is available from the dashboard).

After you’ve built an application and set up a GitHub repository, you can stay informed with Gemnasium or VersionEye. These services survey your GitHub repo and send email notifications when gem versions change. Gemnasium and VersionEye are free for public repositories with a premium plan for private repositories.

Rails Installation Options

Check for the current version of Rails. Rails 4.1.0.beta1 is the newest pre-release version of Rails. Rails 4.0.2 is the current stable release.

You can install Rails directly into the global gemset. However, many developers prefer to keep the global gemset sparse and install Rails into project-specific gemsets, so each project has the appropriate version of Rails.

If you install Rails at this point, you will install it into the global gemset.

Instead, make a gemset just for the current version of Rails:

$ rvm use ruby-2.1.0@rails4.0 --create

Here are the options you have for installing Rails. If you want the most recent stable release:

$ gem install rails
$ rails -v

Or you can get a specific version. For example, if you want the Rails 3.2.16 release:

$ gem install rails --version=3.2.16
$ rails -v

Reblogged from http://railsapps.github.io/

[…]

The Ruby Rails Aggregator