Encap is a Unix tool that doesn't get the attention it deserves. I've used it on Linux servers for years, and is a staple in my OS X tool belt. To borrow from the Encap FAQ, Encap is a package management system for handling third-party packages on a Unix system. Through the magic of symbolic links, it allows you to install each package in its own directory, but still have everything accessible via the traditional location in /usr/local. This means you that you can upgrade Ruby or LightTPD while keeping older versions to fall back on, or you can even remove these packages without having to remember all the files they scattered throughout /usr/local. This article provides instructions for manually building and installing Ruby, Ruby on Rails, and LightTPD on Mac OS X 10.4 (Tiger) using epkg, an Encap package manager. This is a somewhat advanced topic, and you should be fairly familiar with Unix and the Terminal application.

These instructions build upon the instructions from Hivelogic, so you might want to read those first. I'm going to start by showing you the end result. Your goal is to add the following directories to /usr/local:



  1. Mac OS X 10.4 (Tiger)
  2. Xcode 2.2 (Note: I've had problems with gcc 4.0.0. I've had better success with gcc 4.0.1. There's even speculation Ruby is incompatible with gcc 4.0, so you may want to back down to gcc 3.3.)
  3. A willingness to type commands into the Terminal application exactly as they appear here
  4. A tasty beverage to enjoy while things compile
  5. </ol>

    Setting Up the Environment

    This step is very important, so don't skip it!

    You need to make sure that your path is set to look for files in /usr/local. Even though packages are installed into /usr/local/encap/*, they still run from /usr/local. You also need to make sure Ruby gems are installed in a separate directory from Ruby, so that you do not need to re-install them when you decide to upgrade Ruby. So add these two lines to your environment in your shell's start up file (e.g. ~/.bash_login or ~/.zshenv):

    export PATH="/usr/local/bin:/usr/local/sbin:$PATH"
    export GEM_HOME=/usr/local/encap/gem-repository-1.8


    Before installing any other package, you need to install epkg, an Encap package manager. This creates the /usr/local/encap directory, and installs itself as an Encap package.

    curl -O ftp://ftp.encap.org/pub/encap/epkg/epkg-2.3.9.tar.gz
    tar xzvf epkg-2.3.9.tar.gz
    cd epkg-2.3.9
    sudo make install
    cd ..

    You should now use Encap and epkg for all programs that you compile manually and install into /usr/local. Read the man page, epkg(1), for more information. Once you start using it, you'll wonder how you ever lived without it.


    You’ll start by installing Readline, a prerequisite for Ruby on OS X systems:

    curl -O ftp://ftp.gnu.org/gnu/readline/readline-5.1.tar.gz
    tar xzvf readline-5.1.tar.gz
    cd readline-5.1
    ./configure --prefix=/usr/local/encap/readline-5.1
    sudo make install
    sudo epkg readline
    cd ..

    You can see from the --prefix option, you are installing Readline into its own directory. The sudo epkg readline command is what creates the symbolic links from /usr/local to /usr/local/encap/readline-5.1. These two extra steps are usually all that is required to install packages with Encap. Some packages use non-standard build environments, but all packages described here follow this same pattern.

    Now, you'll intsall Ruby:

    curl -O ftp://ftp.ruby-lang.org/pub/ruby/1.8/ruby-1.8.2.tar.gz
    tar xzvf ruby-1.8.2.tar.gz 
    cd ruby-1.8.2
    ./configure --prefix=/usr/local/encap/ruby-1.8.2 --with-readline-dir=/usr/local
    sudo make install
    sudo epkg ruby
    cd ..

    You'll noticed that you use /usr/local as the Readline directory. This is the magic of Encap. It allows the Readline Encap package can be updated without affecting Ruby.


    RubyGems is a Ruby package manager. You'll need this to install the non-standard Ruby packages.

    curl -O http://rubyforge.org/frs/download.php/5207/rubygems-0.8.11.tgz
    tar xzvf rubygems-0.8.11.tgz
    cd rubygems-0.8.11
    sudo /usr/local/bin/ruby setup.rb
    sudo epkg ruby
    sudo epkg gem-repository
    cd ..

    You notice that you run sudo epkg ruby, again. This is because RubyGems installs itself in /usr/local/encap/ruby-1.8.2, and running epkg adds the new symbolic links. I tried installing RubyGems as its own Encap package, but I had trouble getting Ruby and RubyGems to work together this way. I suggest installing them in the same directory to circumvent any difficulties.

    Every time you install a Ruby gem, you need to re-run sudo epkg gem-repository. If you decide to uninstall a gem, be sure to remove the Encap package first, using sudo epkg -r gem-repository, otherwise you'll end up with dangling symbolic links in /usr/local. epkg does allow you to clean up dangling links using the epkg -c, but it is better to get into the habit of removing the Encap package first.

    Ruby on Rails

    Since Ruby on Rails is available as a Ruby gem, installing it is quite simple:

    sudo gem install rails --include-dependencies
    sudo epkg gem-repository


    You'll need to install FastCGI itself:

    curl -O http://www.fastcgi.com/dist/fcgi-2.4.0.tar.gz
    tar xzvf fcgi-2.4.0.tar.gz
    cd fcgi-2.4.0
    ./configure --prefix=/usr/local/encap/fcgi-2.4.0
    sudo make install
    sudo epkg fcgi
    cd ..

    And then, the Ruby FCGI gem:

    sudo gem install fcgi
    sudo epkg gem-repository


    LightTPD requires the Perl compatible regular expression (PCRE) library, so install that first:

    curl -O ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-6.4.tar.gz
    tar xzvf pcre-6.4.tar.gz
    cd pcre-6.4
    ./configure --prefix=/usr/local/encap/pcre-6.4
    sudo make install
    sudo epkg pcre
    cd ..

    Now install LightTPD itself:

    curl -O http://lighttpd.net/download/lighttpd-1.4.8.tar.gz
    tar xzvf lighttpd-1.4.8.tar.gz
    cd lighttpd-1.4.8
    ./configure --prefix=/usr/local/encap/lighttpd-1.4.8 --with-pcre=/usr/local
    sudo make install
    sudo epkg lighttpd
    cd ..

    That's All Folks!

    You've now compiled all the prerequisites to use and develop Rails applications, and you've done it in such a way that you can upgrade or remove each package independently. You can now install other Ruby packages, like bindings to databases (such as MySQL, PostgreSQL, and SQLite), Red Cloth, and Blue Cloth. Follow similar procedures for compiling those packages to use Encap to manage those, too.