I recently decided to make the leap from Yellow Dog Linux to Mac OS X on my
Titanium PowerBook. Getting everything to work the way I wanted proved to be a
challenge, but well worth it. This document outlines all that I learned, so that
neither you nor I will have to experience such pain again. The overall goal was
to get Bricolage up and running, figuring that if it worked, then just about
any mod_perl based solution would run. I’m happy to say that I was ultimately
successful. You can be, too.
In the descriptions below, I provide links to download the software you’ll need,
as well as the shell commands I used to compile and install each package. In all
cases (except for the installation of the Developer Tools), I saved each
package’s sources to /usr/local/src and gunzipped and untarred them there. I
also carried out each step as root, by running
sudo -s. If you’re not
comfortable using a Unix shell, you might want to read up on it, first. All of
my examples also assume a sh-compatible shell, such as bash or zsh. Fortunately,
zsh comes with OS X, so you can just enable it for yourself in NetInfo Manager
by setting users -> <username> -> shell to “/bin/zsh”, where <username> is
your user name.
All of the software that I describe installing below must be compiled. To
compile software on Mac OS X, you need to install the Mac OS X Developer Tools.
These provide the cc compiler and many required libraries. Conveniently, these
come on a CD-ROM with the Mac OS X Version 10.1 upgrade kit. I just popped in
the CD and installed them like you’d install any other OS X software. I needed
administrative access to OS X to install the Developer Tools (or, indeed, to
install any of the other software I describe below), but otherwise it posed no
The best time to install the Developer Tools is immediately after upgrading to
OS X version 10.1. Then run the Software Update applet in the System preferences
to get your system completely up-to-date. By the time I was done, I had the
system updated to version 10.1.3.
The first step I took in the process of moving to OS X was to get working the
tools I needed most. Essentially, what this meant was GNU Emacs. Now I happen
to be a fan of the X version of Emacs – not XEmacs, but GNU Emacs with X
support built in. I wasn’t relishing the idea of having to install X on OS X
(although there are XFree86 ports that do this), so I was really pleased to
discover the Mac-Emacs project. All I had to do was patch the GNU Emacs 21.1
sources and compile them, and I was ready to go! GNU Emacs works beautifully
with the OS X Aqua interface.
There were a few configuration issues for me to work out, however. I have become
addicted to the green background that an old RedHat .XConfig file had set, and I
wanted this feature in OS X, too. Plus, the default font was really ugly (well,
too big, really – anyone know how to make it smaller in Emacs?) and the Mac
command key was working as the Emacs META key, rather than the option key. So I
poked around the net until I found the settings I needed and put them into my
'(default ((t (:stipple nil
:family "apple-andale mono"))))
'(cursor ((t (:background "Wheat"))))
; Use option for the meta key.
(setq mac-command-key-is-meta nil)
Installing Emacs is not required for installing any of the other packages
described below – it just happens to be my favorite text editor and IDE. So I
don’t provide the instructions here; the Mac-Emacs project does a plenty good
job. If you’re not comfortable with Unix editors, you can use whatever editor
you like. BBEdit is a good choice.
Mac OS X doesn’t come with a DBM! But since mod_ssl needs it, we have to
install it. Fortunately, I found this PDF detailing someone else’s adventures
with mod_ssl on OS X, and it provided decent instructions for installing GDBM.
First, I created a new user for GDBM. In NetInfoManager, I created a duplicate
of the “unknown” user and named it “bin”. Then, I downloaded GDBM from the
FSF, and installed it like this:
cp /usr/libexec/config* .
ln -s /usr/local/lib/libgdbm.a /usr/local/lib/libdbm.a
That did the trick. Nothing else was involved, fortunately.
Who doesn’t do something with XML these days? If your answer is, “not me!”, then
you’ll need to install the Expat library in order to work with XML::Parser in
Perl. Fortunately it’s relatively easy to install, although support for the
-static flag appears to be broken in cc on OS X, so it needs to be stripped out.
I downloaded it from its project bpage, and then did this:
perl -i.bak -p -e \
perl -i.bak -p -e \
Although Mac OS X ships with Perl (Yay!), it’s the older 5.6.0 version.
There have been many bug fixes included in 5.6.1, so I wanted to make sure I got
the latest stable version before I built anything else around it (mod_perl,
Being a Unix program, Perl doesn’t expect to run into the problems associated
with a case-insensitive file system like that Mac OS X’s HFS Plus. So there are
a couple of tweaks to the install process that make it slightly more complicated
than you would typically expect. Fortunately, many have preceded us in doing
this, and the work-arounds are well-known. Basically, it comes down to this:
perl -i.bak -p -e 's|Local/Library|Library|g' hints/darwin.sh
sh Configure -des -Dfirstmakefile=GNUmakefile -Dldflags="-flat_namespace"
There were a few errors during
make test, but none of them seems to be
significant. Hopefully, in the next version of Perl, the build will work just as
it does on other platforms.
Before installing Open SSL, mod_ssl, mod_perl, and Apache, I needed to get all
the right pieces in place. The mod_ssl and mod_perl configure processes patch
the Apache sources, so the Apache sources have to be downloaded and gunzipped
and untarred into an adjacent directory. Furthermore, the mod_ssl version
number corresponds to the Apache version number, so you have to be sure that
they match up. Normally, I would just download the latest versions of all of
these pieces and run with it.
However, Bricolage requires the libapreq library and its supporting Perl
modules to run, and these libraries have not yet been successfully ported to
Mac OS X. But worry not; fearless mod_perl hackers are working on the problem
even as we speak, and there is an interim solution to get everything working.
As of this writing, the latest version of Apache is 1.3.24. But because I needed
libapreq, I had to use an experimental version of Apache modified to
statically compile in libapreq. Currently, only version 1.3.23 has been patched
for libapreq, so that’s what I had to use. I discovered this experimental path
thanks to a discussion on the Mac OS X Perl mail list.
So essentially what I did was download the experimental apache.tar.gz and the
experimental lightweight apreq.tar.gz packages and gunzip and untar them into
/usr/local/src. Then I was ready to move on to Open SSL, mod_ssl, and
Compiling Open SSL was pretty painless. One of the tests fails, but it all seems
to work out, anyway. I download the sources from the Open SSL site, and did
The mod_ssl Apache module poses no problems whatsoever. I simply downloaded
mod_ssl-2.8.7-1.3.23 from the mod_ssl site (note that the “1.3.23” at the
end matches the version of Apache I downloaded) and gunzipped and untarred it
into /usr/local/src/. Then I simply excuted:
Configuring and installing mod_ssl was, fortunately, a relatively
straight-forward process. Getting Apache compiled with mod_perl and mod_ssl,
however, was quite tricky, as you’ll see below. A number of braver folks than I
have preceded me in installing mod_perl, so I was able to rely on their
hard-earned knowledge to get the job done. For example, Randal Schwartz posted
instructions to the mod_perl mail list, and his instructions worked well for
me. So I downloaded the sources from the mod_perl site, and did this:
perl Makefile.PL \
Getting Apache compiled just right was the most time-consuming part of this
process for me. Although many had gone before me in this task, everybody seems
to do it differently. I had become accustomed to just allowing Apache to use
most of its defaults when I compiled under Linux, but now I was getting all
kinds of errors while following different instructions from different
authorities from around the web. Sometimes Apache wouldn’t compile at all, and
I’d get strange errors. Other times it would compile, pass all of its tests, and
install, only to offer up errors such as
dyld: /usr/local/apache/bin/httpd Undefined symbols: _log_config_module
when I tried to start it. It turns out that the problem there was that I had a
number of modules compiled as DSOs – that is, libraries that can be loaded into
Apache dynamically – but wasn’t loading them properly in my httpd.conf. This
was mainly because I’ve grown accustomed to Apache having all the libraries I
needed compiled in statically, so I simply didn’t have to worry about them.
But I finally hit on the right incantation to get Apache to compile with
everything I need added statically, but still with support for DSOs by compiling
in mod_so. I present it here for your viewing pleasure:
make certificate TYPE=custom
This series of commands successfully compiled Apache with mod_perl and mod_ssl
support statically compiled in, along with most of the other default modules
that come with Apache. In short, everything is there that you need to run a
major application with security such as Bricolage.
make certificate will lead you through the process of creating an
SSL certificate. I like to use the “custom” type so that it reflects the name of
my organization. But you can use whatever approach you’re most comfortable with.
Consult the mod_ssl INSTALL file for more information.
Once Apache is installed with mod_perl and mod_ssl, the rest is gravy! The
experimental libapreq library I downloaded installed without a hitch:
PostgreSQL is a sophisticated open-source Object-Relational DBMS. I use it a
lot in my application development, and it, too, is required by Bricolage. I was
a bit concerned about how well it would compile and work on Mac OS X, but I
needn’t have worried. First of all, Apple has provided some pretty decent
instructions. Although they mainly document how to install MySQL, a
competing open-source RDBMS, many of the same concepts apply to PostgreSQL.
The first thing I had to do was to create the “postgres” user. This is the
system user that PostgreSQL typically runs as. I followed Apple’s instructions,
using NetInfo Manager to duplicate the default “www” group and “www” user and
give the copies the name “postgres” and a new gid and uid, respectively.
Next I downloaded the PostgreSQL version 7.2.1 sources. Version 7.2 is the first
to specifically support Mac OS X, so going about the install was as simple as it
is on any Unix system:
That was it! PostgreSQL was now installed. Next I had to initialize the
PostgreSQL database directory. Again, this works much the same as it does on any
sudo -u postgres /usr/local/pgsql/bin/initdb \
The final step was to start PostgreSQL and try to connect to it:
sudo -u postgres /usr/local/pgsql/bin/pg_ctl start \
-D /usr/local/pgsql/data /usr/local/pgsql/bin/psql -U postgres template1
If you follow the above steps and find yourself at a psql prompt, you’re in
business! Because I tend to use PostgreSQL over TCP, I also enabled TCP
connectivity by enabling the “tcpip_socket” option in the postgresql.conf file
in the data directory created by initdb:
tcpip_socket = true
If you’re like me, you like to have servers such as PostgreSQL start when your
computer starts. I enabled this by creating a Mac OS X PostgreSQL startup
bundle. It may or may not be included in a future version of PostgreSQL, but in
the meantime, you can download it from here. Simply download it, gunzip and
untar it into /Library/StartupItems, restart OS X, and you’ll see it start up
during the normal Mac OS X startup sequence. I built this startup bundle by
borrowing from the existing FreeBSD PostgreSQL startup script, the Apache
startup script that ships with OS X, and by reading the Creating SystemStarter
Startup Item Bundles HOWTO.
At this point, I had most
of the major pieces in place, and it was time for me to install the Perl modules
I needed. First up was XML::Parser. For some reason, XML::Parser can’t find
the expat libraries, even though the location in which I installed them is
pretty common. I got around this by installing XML::Parser like this:
perl Makefile.PL EXPATLIBPATH=/usr/local/lib \
In Bricolage, Text::Iconv does all the work of converting text between
character sets. This is because all of the data is stored in the database in
Unicode, but we wanted to allow users to use the character set with which
they’re accustomed in the UI. So I needed to install Text::Iconv. Naturally, Mac
OS X doesn’t come with libiconv – a library on which Text::Iconv depends – so
I had to install it. Fortunately, it was a simple process to download it and
do a normal build:
Now, Text::Iconv itself was a little more problematic. You have to tell it to
look for libiconv by adding the -liconv option to the LIBS key in Makefile.PL.
I’ve simplified doing this with the usual Perl magic:
perl -i.bak -p -e \
"s/'LIBS'\s*=>\s*\[''\]/'LIBS' => \['-liconv'\]/" \
Although the DBI installed via the CPAN module without problem, DBD::Pg
wanted to play a little less nice. Of course I specified the proper environment
variables to install it (anyone know why DBD::Pg’s Makefile.PL script can’t try
to figure those out on its own?), but still I got this error during
/usr/bin/ld: table of contents for archive:
/usr/local/pgsql/lib/libpq.a is out of date;
rerun ranlib(1) (can't load from it)
But this was one of those unusual situations in which the error message was
helpful. So I took the error message’s advice, and successfully compiled and
installed DBD::Pg like this:
The last piece I needed to worry about customizing when I installed it was
LWP. Before installing, back up /usr/bin/head. The reason for this is that LWP
will install /usr/bin/HEAD, and because HFS Plus is a case-insensitive file
system, it’ll overwrite /usr/bin/head! This is a pretty significant issue, since
many configure scripts use /usr/bin/head. So after installing LWP, move
/usr/bin/HEAD, GET, & POST to /usr/local/bin. Also move /usr/bin/lwp* to
/usr/local/bin. Then move your backed-up copy of head back to /usr/bin.
Naturally, I didn’t realize that this was necessary until it was too late. I
installed LWP with the CPAN module, and it wiped out /usr/bin/head. Fortunately,
all was not lost (though it took me a while to figure out why my Apache compiles
were failing!): I was able to restore head by copying it from the Mac OS X
installer CD. I Just popped it in an executed the command:
cp "/Volumes/Mac OS X Install CD/usr/bin/head" /usr/bin
And then everything was happy again.
And finally, the pièce de résistance: Bricolage! All of the other
required Perl modules installed fine from Bundle::Bricolage:
perl -MCPAN -e 'install Bundle::Bricolage'
Then I simply followed the directions in Bricolage’s INSTALL file, and started
‘er up! I would document those steps here, but the install process is currently
in flux and likely to change soon. The INSTALL file should always be current,
however – check it out!
To Be Continued
No doubt my adventures with Unix tools on Mac OS X are far from over. I’ve
reported to various authors on the issues I’ve described above, and most will
soon be releasing new versions to address those issues. As they do, I’ll
endeavor to keep this page up-to-date. In the meantime, I am thoroughly enjoying
working with the first really solid OS that Apple has released in years, and
thrilled that I can finally have the best of both worlds: a good, reliable, and
elegant UI, and all the Unix power tools I can stand! I hope you do, too.
Looking for the comments? Try the old layout.