Building Ruby and RubyGems

Many thanks to Dan Benjamin for his excellent posting on doing a custom build of Ruby & RubyGems on OS X. I was just getting started with using a Mac at the time, and it was a very straight-forward and helpful guide. For most software, I’ll use MacPorts or standard Apple packages, but for Ruby I’ll make an exception.

For starters, I just want to expand a bit on his excellent tutorial. I won’t re-iterate his whole piece, but the outline is:

• start with OS X Leopard, and XCode (from your Optional Installs DVD)
• get /usr/local and its derivatives into your path
• set aside a good long-term home for your custom build code
• pull down the source for Ruby
• run ./configure, then build and install with make
• pull down the source for RubyGems, run its setup.rb

After that you can install all of the gems that your heart desires. I initially pulled down source for the Ruby 1.9 candidate release, but there are significant enough language changes that it destabilized a lot of tried-and-true gems. Instead, I went with the latest generation of 1.8.7.

I did however run into a little issue when installing the native mysql gem. Dan’s instructions weren’t valid for my case. Fortunately, the README.html in the gem suggested building it manually as such:

$ sudo gem install mysql -- --with-mysql-config
  or
$ ruby extconf.rb --with-mysql-config

That worked well, since I’d already installed MySQL and my /etc/mysql.cnf was in its standard location. Hooray!

Configuring RadRails to use the Custom-Built Componentry

Since I switch back and forth between Ruby and Java, I chose to stick with the Eclipse IDE. Aptana has created a nice development suite called RadRails which is highly componentized, and it works rather well for script development as well. Yes, if I don’t use TextMate I’m a heretic, but at some point I’ll hunker down and pony out the bucks for it :)

The install of Eclipse 3.4 Ganymede that I started out with contained several plugins / features from rubypeople.org. As well intended as they were, I ran into several areas of conflict between them and RadRails. I thus chose to remove these plugins from Eclipse, and stability ensued.

However, even after removed, I still have two Eclipse sections for ‘Ruby’. The one for RadRails is the one with fewer sub-sections (also known as ‘the one that looks less like the Java language configuration section’).

Since you’ve custom built your install of Ruby, you’ll want to make the following configuration changes to Eclipse / RadRails:

• Under Ruby | Interpreters, add a new Generic Ruby interpreter. Its executable should be /usr/bin/local/ruby, and the rest will take care of itself (I didn’t specify any arguments).
• Under Rails, set up the ‘rails’ and ‘mongrel_rails’ paths to reference the respective binaries in /usr/local/bin, since that’s where all of your installed gems will have been exposed.
• Under Java | Build Path | Classpath Variables, you’ll want to add GEM_LIB, which should reference /usr/local/lib/ruby/gems/1.8/gems. It seems out of place under ‘Java’, but the IDE was crying out for it loudly.

That should address the majority of the IDE configuration. If anything doesn’t quite work correctly, you may want to examine the steps that I describe below as being ‘optional’, particularly the one where I created a mock Ruby.framework setup.

Optional (?) Configuration

I question whether they’re mandatory or not because this configuration has been stable on my machine for a little while now, and I have a tendency to get very detail-oriented, not all of which turns out to actually be necessary. In the spirit of completeness — yep, there’s detail-oriented for you right there! — I’ll lay out what I have put into play.

I’ve injected ‘/usr/local/bin’ and ‘/usr/local/sbin’ into /etc/paths; that works like a charm.

I consistently install gems as root, or else I end up with account-specific discrepancies driven by each ~/.gems folder. I merely point that out to illustrate that such user-specific directories exists :)

I’ve added the following unnecessary env var:

export GEM_LIB=/usr/local/lib/ruby/gems/1.8/gems

It matches the Classpath Variable you set in Eclipse (above). If nothing else, it’s an easy ‘$’ substitution when I need to go spelunking into gem source code.

There’s been at least once where I have also needed the following env var. It should be configured to point at the expanded source code of your custom Ruby build.

export RUBY_SOURCE_DIR=...

I’ve created the following directory structure:

$ mkdir -p /System/Library/Frameworks/Ruby.framework/Versions/1.8-Current

Therein I have created a ‘usr’ directory structure that matches the one you’ll find in /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr . It’s all just symlinks into the appropriate /usr/local hierarchy. I then co-opted the Current symlink:

$ cd /System/Library/Frameworks/Ruby.framework/Versions
$ ls -l
1.8
1.8-Current
Current -> 1.8
$ rm Current
$ ln -s 1.8-Current Current

Consider that you may need to mimic certain aspects of the default Ruby framework configuration, which is the inverse of the mock framework setup that I just described. Specifically, /usr/local/lib/ruby takes after /System/Library/Frameworks/Ruby.framework/Versions/Current/usr/lib/ruby.

This is why I ended up with both a ‘/usr/local/lib/ruby/site_ruby’ and ‘/usr/local/lib/ruby/vendor_ruby’ subdir on my machine.

The standard location for the ruby executable is often used in a she-bang line for bash scripts. The standard location is:

#!/usr/bin/ruby

Which of course was still pointing at the default OS X Ruby framework. I renamed the existing symlink and replaced it with one to /usr/local/bin/ruby. I did not do this for gem, irb, rdoc (etc.) since I don’t have she-bang needs for them.

In Summary

I hope some of this information is useful to you. I was sitting at Cafe International and setting up RadRails when the HD on my two-week-old MacBook Pro 2008 went into beachball-of-death mode. I had to pick back up from there 2+ weeks later on a fresh laptop, which at least allowed me to keep these copious notes.

When you unpack the installer .dmg, it’s simply going to install the package. It will not automatically assume that you want to use it (not such a bad assumption, as it turns out). So there are a few caveats you need to deal with. I’m taking the approach of addressing all the details I know of, regardless of how obvious this may all seem :)

Post-install, Java 5 will still be in active use:

$ ls -l /usr/bin/java
/usr/bin/java -> /System/Library/Frameworks/JavaVM.framework/Versions/Current/Commands/java
$ Lunditer:~ root# java -version
java version "1.5.0_16"

You’ll see something much like this under /System/Library/Frameworks/JavaVM.framework/Versions :

1.3 -> 1.3.1
1.3.1
1.4 -> 1.4.2
1.4.1 -> 1.4
1.4.2
1.5 -> 1.5.0
1.5.0
1.6.0
A
Current -> A
CurrentJDK -> 1.5

Initially, I went and modified the symlink for CurrentJDK. Modifying the symlink for Current brought me nothing but pain. You can get the results you want by making the following change:

CurrentJDK -> 1.6.0

I’d had it set up that way until I wrote this post. But Apple highly discourages this practice. Instead, they recommend that you use the Java Preferences pane. Get rid of all your symlink shenanigans, and simply drag the ‘Java SE 6′ option to the top of the applet and application listings. It works like a charm. Start a new Terminal shell and you can confirm:

$ /usr/bin/java -version
java version "1.6.0_07"
$ /usr/bin/javac -version
javac 1.6.0_07

However … from my experience, this is a user-specific setting. Which means if you run Java as root, you’ll still get Java SE 1.5. Not a problem. We’ll stick with the Apple-sanctioned solution here.

Hooray, Java SE 6! Now let’s start Eclipse 3.4! Hooray … oops? Startup failure dialog:

JVM terminated.
Exit code=-1
...
-vm /System/Library/Frameworks/JavaVM.framework
...

This is a well documented issue. Both the Rob Kischuk and Stack Overflow blogs are very helpful in explaining that; Eclipse uses 32-bit SWT-Cocoa / Carbon, and Mac OS Java SE 6 only comes in a 64-bit flavor. I have not looked into the SoyLatte option, as suggested above, though that may prove to be an alternative approach.

I had some struggles getting their approach to work (until now, that is). Easiest way to start config testing is to run Eclipse from the command line:

$ cd /Applications/eclipse/Eclipse.app/Contents/MacOS/
$ ./eclipse -vm /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Commands/java

You can also provide /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0, which I extrapolated from the -vm setting in the failure message. If you still get an error dialog, you may see multiple instances of -vm, but that’s a red herring; it will work once properly configured.

Great. Once that’s working for you, let’s apply it to the App shortcut. There’s two ways you can go about this:

The blogs above recommend that you modify the Info.plist:

• edit /Applications/eclipse/Eclipse.app/Contents/Info.plist
• uncomment the following line:

  <string>-vm</string><string>/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Commands/java</string>

Alternately, you can modify eclipse.ini, where you might also configure your JVM memory configuration:

• edit /Applications/eclipse/Eclipse.app/Contents/MacOS/eclipse.ini
• add the following line:

  -vm /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Commands/java

Either dab will do ya. But if you didn’t know before, now you know where eclipse.ini lives :)

Things should be grand now. If they aren’t, I suggest trying some variations while running Eclipse from the command line. It took me a while to get the right combination, even though this post and (the ones it references) may seem very cookie-cutter. It will eventually work for you!

Now, I mentioned that the Apple-sanctioned approach seems to be user-specific. And I run Tomcat as root. So you will probably still want to add the traditional environment settings.

You can either make these changes to /etc/profile, or to the ~/.bashrc of each relevant account. No surprises here:

export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home
PATH="$JAVA_HOME/bin:$PATH"

My experiments to get /etc/paths to inject something into the path before ‘/usr/bin’ weren’t so useful, so I chose the brute force method.

If you’re going to use sudo to run Tomcat, you’ll want to make sure to load the bash environment.

sudo su -

to guarantee that root’s environment includes the custom /etc/profile overrides. No dash, and it no work. Tomcat Java 5 + App Java 6 =

SEVERE: Error deploying web application directory ...
java.lang.UnsupportedClassVersionError: Bad version number in .class file

With the environment in place, you should be good to go.

The writing of this post drove me to (a) drop the symlinks, (b) use Java Preferences pane and (c) get the right -vm config set up (since I’d been leaning entirely on the environment settings up to this point). So there are definitely a few ways to skin this cat.