One of my favourite plugins for Vim is command-t:

An extremely fast, intuitive mechanism for opening files with a minimal number of keystrokes. It's named "Command-T" because it is inspired by the "Go to File" window bound to Command-T in TextMate.

Sadly, the default installation of Vim on Snow Leopard does not have support for the ruby interpreter compiled in, which is a pre-requisite for using the plugin. Luckily, that's easy enough to remedy, and in the process we'll learn a thing or two about compiling your own custom Vim binary.

Let's start off by getting the source code from the official Mercurial repository:

$ hg clone https://vim.googlecode.com/hg/ vim
$ cd vim

Note: You don't need to use the Mercurial repository - there are mirror sources for Subversion, CVS, as well as good ol' tarballs with patches.

The default branch for the mercurial repository contains the code for Vim 7.2 at the time of this writing. There is also a vim73 branch available for those feeling a bit more adventurous and wishing to compile the beta release of the next version. For this article, we'll be sticking to the stable 7.2 release in the default branch.

Now, let's take a look at the possible configuration options:

./configure --help

There are quite a few, and I suggest that you take the time to read through them - most are quite self-explanatory. For Command-T, the one that we are interested in is the --enable-rubyinterp

So let's take a shot at the simplest installation for terminal-based Vim usage, one without the GUI interface and (Linux) mouse daemon support:

$ ./configure --prefix=/my/install/prefix --enable-rubyinterp --enable-gui=no --disable-gpm
$ make

After the compilation process finishes (presumably with no errors), the first thing you'll want to do is ensure that the binary you just built functions as expected:

$ ./src/vim --version | grep ruby
# you should see a `+ruby` line entry
$ ./src/vim

If you see the +ruby entry in the --version output and the binary launches without any errors, rejoice in your own awesomeness. That's all there is to it.

If, however, you see something similar to this:

Vim: Caught deadly signal SEGV
Vim: Finished.
zsh: segmentation fault  ./src/vim

you've probably fallen prey to a (currently) not very well documented issue: Vim 7.2 does not support the integration of Ruby 1.9.x on Snow Leopard.

This means that if you've used a package manager such as Homebrew, MacPorts or Fink (shudder) to install the latest version of Ruby, Vim will link to that latest version instead of the system default installation of ruby 1.8.7.

Let's fix that.

We're going to edit the src/auto/config.mk generated by configure that was run earlier. Note that if you re-run configure at a later time, your changes to config.mk will be lost.

Find the lines that look like this:

RUBY            = /usr/local/bin/ruby
RUBY_SRC        = if_ruby.c
RUBY_OBJ        = objects/if_ruby.o
RUBY_PRO        = if_ruby.pro
RUBY_CFLAGS     = -I/usr/local/Cellar/ruby/1.9.1-p378/include/ruby-1.9.1 -I/usr/local/Cellar/ruby/1.9.1-p378/include/ruby-1.9.1/i386-darwin10.4.0 -DRUBY_VERSION=19
RUBY_LIBS       = -lruby -lpthread -ldl -lobjc

(Your specific paths and/or versions may differ depending on the package manager that you are using. The above paths are actually not important, however, since we actually want to reset them to the system defaults.)

and replace them with the following:

RUBY            = /usr/bin/ruby
RUBY_SRC        = if_ruby.c
RUBY_OBJ        = objects/if_ruby.o
RUBY_PRO        = if_ruby.pro
RUBY_CFLAGS     = -I/System/Library/Frameworks/Ruby.framework/Versions/1.8 -I/usr/lib/ruby/1.8/universal-darwin10.0
RUBY_LIBS       = -framework Ruby

Alright, let's see if this worked.

$ make clean && make

Before we check the binary as we did before, let's see if we linked to the correct ruby libraries:

$ otool -L src/vim
src/vim:
    /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 125.2.0)
    /usr/lib/libncurses.5.4.dylib (compatibility version 5.4.0, current version 5.4.0)
    /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/lib/libruby.1.dylib (compatibility version 1.8.0, current version 1.8.7)
    /System/Library/Frameworks/CoreServices.framework/Versions/A/CoreServices (compatibility version 1.0.0, current version 44.0.0)
    /System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation (compatibility version 150.0.0, current version 550.29.0)

Looking good so far - the binary is linked to the framework version of Ruby that comes as a default on Snow Leopard.

Let's do a version check:

$ ./src/vim --version | grep ruby
# you should see a `+ruby` line entry
$ ./src/vim

And voilà: A custom-built Vim with ruby integration that will happily run the Command-T plugin.

All that's left is to install it:

$ make install

Assuming your PATH is setup to correctly find the new Vim binary, you should be all set.