This guide walks you through setup instructions for preparing a Mac OS X 10.4 (aka Tiger) development machine to be used for general Ruby on Rails coding. This baseline setup is what we use for our LearningRails online course.
You will end up with a development machine with the following baseline components:
- Ruby and all basic Ruby utilities
- Ruby Gems package manager
- Subversion client
- Git client
- Native development tools (Xcode, C compiler)
- MacPorts native code package manager
- MySQL database client utilities and server
- Gems for Ruby on Rails, Capistrano, Mongrel, Mongrel Cluster, and MySQL
- Programmer’s editor or IDE
Note: In the command sequences we illustrate here, command line prompts are shown as a dollar sign ($).
Prerequisites
This guide assumes you have a Macintosh computer running the current Tiger operating system with up-to-date System Update patches applied. It also assumes you have not set up alternate Ruby on Rails tools prior to running through this guide. If you have, then small adjustments may be required as you walk through the following instructions.
You will need to have access to an Internet connection to complete various download steps.
You will need to have administrator access to your computer to complete this guide. We will be using the sudo command to run various command line programs and some of the Mac OS X native installers will also ask you for your password.
It is helpful if you have access to your operating system installation discs.
The Recipe
Follow this recipe in sequence. If you have previously installed a particular component, you can usually skip the associated step.
If you are planning on upgrading to Mac OS X 10.5 (Leopard), you should do so now and save some time setting up the Ruby environment. Leopard comes with a current version of Ruby and it makes setting things up much easier. If you follow this guide and then upgrade to Leopard later, it is pretty simple to deactivate (or remove) the redundant components that are no longer needed.
Native Development Tools (X11 and Xcode 2.5)
MacPorts will use native development tools when installing many of the utilities listed in this guide. You will also need a native compiler to build many of the gems’ native libraries you are going to use. Apple provides a free native compiler tool set called Xcode. If you have your Tiger installation DVD, load it now. If you don’t have an installation DVD, you can download the Xcode 2.5 tools at Apple’s Developer Web Site. (Note: Apple developer accounts are free.)
Open the Xcode Tools folder (or DMG file if you downloaded the package). Double click on the XcodeTools.mpkg installer and select a standard install. This will take a few minutes to run:
As an optional step, some tools require that the X11 window manager application be installed. Under Tiger, this is an optional install. You can find X11 on your Tiger installation DVD or download it from Apple.
MacPorts
MacPorts is a native code package manager for Macintosh software. This guide uses MacPorts to setup the Ruby tools, MySQL, and the Git distributed version control system. There are many other tools available in the MacPorts library, so it is well worth checking out.
Download the Tiger Universal version (1.6.0 at the time of this writing) and double click the MacPorts DMG file to open it up. Double click on “MacPorts-1.6.0.pkg” to start the installer and select the default options.
After MacPorts completes installation, you need to adjust your command line PATH environment variable so you can run the port command.
Fire up the Terminal program and enter the command:
$ open .bash_profile
Note that there is a period in front of “bash_profile”. The bash shell configuration file should open in the TextEdit program. If you don’t have a .bash_profile, you can create a new one in your text editor and save it in your home directory.
(By the way, we recommend iTerm as a nice open source replacement to the Apple Terminal program.)
Inside of .bash_profile, find the line that starts with export PATH=, if present. You are going to insert the new directories used by MacPorts into your path:
export PATH="/opt/local/bin:/opt/local/sbin:$PATH"
If you don’t have a line that exports your PATH, use the text exactly as above. If you do already have such a line, add the /opt/local/bin:/opt/local/sbin: (note colons) after the first quote, but before any other paths. Here is an example:
export PATH="/opt/local/bin:/opt/local/sbin:/usr/local/bin:/usr/local/sbin:$PATH"
Save the file and close TextEdit. Open a new terminal window and have MacPorts update itself with the command:
$ sudo port selfupdate
Ruby and Ruby Utilities (irb, ri, rdoc)
Tiger comes pre-installed with a version of Ruby that is out of date for day to day use. You will use MacPorts to upgrade to the latest production version of the Ruby toolset. In a terminal window type:
$ sudo port install ruby Password: ---> Fetching ncursesw ---> Attempting to fetch ncurses-5.6.tar.gz from http://ftp.gnu.org/gnu/ncurses ---> Verifying checksum(s) for ncursesw ---> Extracting ncursesw ---> Applying patches to ncursesw ---> Configuring ncursesw ---> Building ncursesw with target all ---> Staging ncursesw into destroot ... ---> Installing ncurses 5.6_0+darwin_8 ---> Activating ncurses 5.6_0+darwin_8 ---> Cleaning ncurses ---> Fetching openssl ---> Attempting to fetch openssl-0.9.8e.tar.gz from http://www.openssl.org/source/ ... ---> Fetching ruby ---> Attempting to fetch ruby-1.8.6.tar.gz from http://www.ibiblio.org/pub/languages/ruby/1.8 ---> Attempting to fetch ruby-1.8.6.tar.gz from http://mirrors.sunsite.dk/ruby/1.8 ---> Verifying checksum(s) for ruby ---> Extracting ruby ---> Applying patches to ruby ---> Configuring ruby ---> Building ruby with target all ---> Staging ruby into destroot ---> Packaging tgz archive for ruby 1.8.6_0+thread_hooks ---> Installing ruby 1.8.6_0+thread_hooks ---> Activating ruby 1.8.6_0+thread_hooks ---> Cleaning ruby
Your output may be slightly different depending on the versions of software at the time you run these commands. The listing here was edited for brevity.
You can check that Ruby is installed with:
$ which ruby /opt/local/bin/ruby $ ruby -v ruby 1.8.6 (2007-03-13 patchlevel 0) [powerpc-darwin8.11]
You should seem similar responses. The important one is the first one which reports back the path of the program. If you are using the MacPorts Ruby, it will be located in /opt/local/bin/.
Ruby Gems Package Manager
You next need to install the latest version of gem.
$ sudo port install rb-rubygems rb-termios
Check the version that gets installed:
$ gem -v 0.9.4
You need 1.0.1 or newer. If you have an older version, you can update with the command line: sudo gem update --system.
Installing a Subversion client
Subversion will be used to access your source code repository during development and deployments. You will need a current version of the Subversion client and you can use MacPorts to install it:
$ sudo port install subversion +tools
Installing Git via MacPorts
Git is all the rage in the Rails world now and has pretty much replaced Subversion as the version control system of choice. That said, both are in common use. Currently Leopard doesn’t install git by default, so we’ll use MacPorts to quickly install git:
$ sudo port install git-core +doc +svn
This command installs the core git tools, the man page documentation, and integration with Subversion. This last is useful if you plan on migrating from or need to work with a legacy Subversion repository. The installation will take a while; it has a lot to load.
Besides your own project version control, you’ll typically use git when loading Rails 2.1 and various 3rd party plugins.
Installing MySQL via MacPorts
By leveraging MacPorts to install MySQL, maintenance of the software is slightly easier, especially when you want to upgrade over time. We are using MySQL on our development machine as we prefer to have identical software across our environments. Rails 2.0.2, 2.1, and newer uses SQLite by default, which is fine for development and experimentation, but not appropriate for production code.
To get started, type into your terminal window:
$ sudo port install mysql5 +server
This command downloads and installs the baseline MySQL client programs and server software. Next, you want to configure MySQL’s server so it launches when your computer boots up:
$ sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plist
launchctl is an Apple tool that administers the system daemon that controls the boot process and background programs. Here you are loading the instructions for how to manage MySQL.
A fresh MySQL installation requires its database storage area to be initialized, so you do that next:
$ sudo mysql_install_db5 --user=mysql
When you configure the storage area with this command, you’re making sure it is owned by the user “mysql”.
MySQL creates a special system file used for program to program communication, called the “socket” file. By default, the MacPorts installation of MySQL server creates this in the directory “/opt/local/var/run/mysql5/mysqld.sock”. Ruby on Rails applications can deal with this just fine if you change the settings in your database.yml file to include a socket entry that points to the correct place. However, we are going to tweak things so all applications can find the file in a fairly standard place: /tmp/mysql.sock with little or no modification.
First, you need to move the default configuration file, my.cnf, to the correct place:
$ sudo mv /opt/local/etc/my.cnf /opt/local/etc/mysql5/my.cnf
If the installation program didn’t put a file into /opt/local/etc/, try this instead:
$ sudo mv /opt/local/share/mysql5/mysql/my-medium.cnf /opt/local/etc/mysql5/my.cnf
Now, you need to edit the configuration file to change where the socket file is stored:
$ sudo pico /opt/local/etc/mysql5/my.cnf
If you aren’t familiar with the pico command line editor, we explain the few commands you will need here.
Inside of pico, use your arrow keys to move down to the line where you first see “[client]” and make the following changes (this is just a small part of the whole file):
... # In this file, you can use all long options that a program supports. # If you want to know which options a program supports, run the program # with the "--help" option. [mysqld_safe] socket = /tmp/mysql.sock # The following options will be passed to all MySQL clients [client] #password = your_password port = 3306 socket = /tmp/mysql.sock # Here follows entries for some specific programs # The MySQL server [mysqld] port = 3306 socket = /tmp/mysql.sock ...
You are adding the “[mysqld_safe]” section (2 lines) just above “[client]” and then changing the two instances of the "socket = " lines in the “[client]” and “[mysqld]” sections to be /tmp/mysql.sock. Once done, press Control-X, answer Y when asked to save, and press return to accept the default file name (“my.cnf”).
Now you start the server up manually:
$ cd /opt/local ; sudo /opt/local/lib/mysql5/bin/mysqld_safe &
You can confirm that MySQL is running by trying to fire it up:
$ mysql5 -p -u root Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 1 Server version: 5.0.45 Source distribution Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> exit
When you reboot your computer, MySQL should start automatically in the future.
Gems
Tiger requires that you install the base collection of gems you will be using:
$ sudo gem install rake rails capistrano mongrel mongrel_cluster
All installed gems (including Ruby on Rails and its dependencies, Rake, Capistrano, Mongrel, and Mongrel_Cluster) will get installed at their latest versions.
The MySQL adapter gem needs to be installed, and it is a little finicky due to our use of MacPorts.
If you are running Tiger on an Intel processor, use this command (on one line):
$ ARCHFLAGS="-arch i386" sudo gem install mysql -- --with-mysql-config=/opt/local/bin/mysql_config5
and if you are on a PowerPC processor, use this command:
ARCHFLAGS="-arch ppc" sudo gem install mysql -- --with-mysql-config=/opt/local/bin/mysql_config5
Once the command completes, you should be all set with the baseline gems you will need for the LearningRails courses.
Code Editing Tools
While you can get by with using a plain text editor like TextEdit, or even Apples Xcode IDE, you will have much high productivity if you use a programming editor that is highly tuned to Ruby on Rails development.
We use the commercial TextMate programmer’s editor for much of our day to day work. TextMate is highly extensible through a collection of community supplied “bundles”. Many add-ons accelerate development by enhancing the editor (for example, adding language specific short cuts to reduce your typing) or by tying in to other utilities, such as Subversion or Rake, to allow you to quickly get tasks done without leaving the editor’s environment.
There are a variety of good open source or free programmer editors available too. On the open source side, Leopard comes pre-installed with both vim and emacs. jEdit is a very extensible open source editor written in Java. TextWrangler is a free programmer’s editor from BareBones.
Whatever editor you choose, be certain that it provides easy navigation among a large number of open files. Working with Rails applications generally involves dealing with a lot of small files, and that process needs to be efficient.
If you prefer an all-in-one tool, you should look at one of several integrated development environments that exist for Ruby. We use Netbeans in our LearningRails courses, but you should check out the numerous other options listed at BuildingWebApps.com.