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: 

/usr/local/encap/epkg-2.3.9
/usr/local/encap/ruby-1.8.2
/usr/local/encap/gem-repository-1.8
/usr/local/encap/fcgi-2.4.0
/usr/local/encap/pcre-6.4
/usr/local/encap/lighttpd-1.4.8

Prerequisites

  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

    epkg

    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
./configure
make
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.

    Ruby

    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
make
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
make
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

    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

    FastCGI

    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
make
sudo make install
sudo epkg fcgi
cd ..

    And then, the Ruby FCGI gem: 

    sudo gem install fcgi
sudo epkg gem-repository

    LightTPD

    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
make
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
make
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.