How to Integrate the TestFlight SDK into an iOS Project

I've started using TestFlight to release DesignScene betas to testers. The documentation is thin, so I had to futz a bit, but fortunately it's a pretty simple app, so once I figured out that I just needed to stick to one "Team", I was off and running. And let me tell you, TestFlight is a far easier way to distribute betas than the convoluted methods suggested by Apple. Much more beta user-friendly.

For us developers, the TestFlight SDK is particularly handy. Add it to your TestFlight-distributed project and get crash reports and remote logging, ask your testers for feedback, and other cool stuff. I've only just started using it, but the immediate diagnostic feedback has already proved invaluable.

Getting the TestFlight SDK to work is dead simple, but it's not supported in App Store distributions. So I wanted to set things up so that it would always be included in beta releases and never in production releases. Getting to that point took a couple of days of futzing, as it's not explicitly supposed by Xcode's UI. The solution I came up with, thanks to this StackOverflow post, is to:

  • Add a "Beta" configuration to complement the default "Release" and "Debug" configurations
  • Add a preprocessor macro to allow conditional use of the TestFlight SDK
  • Use the EXCLUDED_SOURCE_FILE_NAMES setting to exclude the TestFlight library from "Release" builds

That last step makes me a bit nervous, but EXCLUDED_SOURCE_FILE_NAMES, while undocumented, seems to be reasonably well known. At any rate, I could find no better way to tie the inclusion of a library to a specific configuration, so I'm going with it. Better solutions welcome.

At any rate, here's the step-by-step for Xcode 4.2:

  • Download the TestFlight SDK and unpack it.
  • Drag it into your project. Make sure that "Copy items into destination group's folder" is checked, as is "Create groups for any added folders". Include it in all relevant targets.
  • Create a "Beta" configuration:

    • Click on the app name in the navigator, then on the project name and then the info tab.
    • Under "Configurations", click the plus sign and select "Duplicate "Release" Configuration"
    • Type "Beta" to name the new configuration.

    You should end up with something like this:

    Configurations

  • Create configuration marcos:

    Configurations

    • Still in the project settings, go to the "Build Settings" tab.
    • Search for "preprocessor macros".
    • Double-click the value section next to the "Preprocessor Macros" label, hit the + button, and enter CONFIGURATION_$(CONFIGURATION).

    You should end up with a window like the above. Once you close it, you should see the macros names for each individual configuration, shown here:

    Configurations

  • Add the EXCLUDED_SOURCE_FILE_NAMES build setting.

    • Still in the "Build Settings" tab, click the "Add Build Setting" button in the lower-left corner and select "Add User-Defined Setting".
    • Input EXCLUDED_SOURCE_FILE_NAMES as the name of the setting.
    • Open the reveal triangle next to the setting name.
    • Double-click to the right of "Release".
    • Enter *libTestFlight.a as the value.

    You should end up with the value *libTestFlight.a only for the "Release" configuration, as shown here:

    Configurations

  • Go ahead and use the TestFlight SDK:

    • In your app delegate, add #include "testFlight.h"
    • In -application:didFinishLaunchingWithOptions:, just before returning, add these lines:

      #ifdef CONFIGURATION_Beta
          [TestFlight takeOff:@"Insert your Team Token here"];
      #endif

Now, when you build or archive with the "Beta" target, the TestFlight SDK will be included and log sessions. But when you build with the "Release" target, TestFlight will neither be bundled or referenced in the app. You can include it anywhere, though, and use any of its features, as long as you do so only within a #ifdef CONFIGURATION_Beta block. Check out the complete SDK docs for details. Then, get your beta on!

Byline: A Case Study Apple and Google Philosophical Differences

My favorite iPhone feed reading app is Byline by Phantom Fish. It syncs really well with Google Reader, so that things stay more-or-less in sync with NetNewsWire on my Mac. Unlike NetNewsWire, which added Google Reader syncing in 2009, Byline was built with Google Reader syncing from the beginning. Version 3.0 is especially good; I love the ability to swipe between posts. And the killer feature is the archiving of all content after a sync, so that everything loads fast — or on cross-country flights. News junkie that I am, Byline is one of my most-used apps.

Byline Edit Mode

Another great feature is Byline’s edit mode. When looking at a long list of new posts in a particular feed (for me it most often happens with the CPAN Uploads feed — CPAN gets a lot of uploads every day!), most of which I don’t care to read, I tap the “Edit” button to enter edit mode and then start tapping the blue dots to mark a whole bunch of items as unread. But not all of them; I leave the ones I’d like to read. But there’s a problem. At the top of the screen, directly above the top read/unread toggle button, is a button labeled “Mark All as Read.” As soon as you tap this button, Byline exits edit mode and shifts back to the main screen.

It’s a handy shortcut if you actually want to mark all as read. But what if you accidentally hit it, as I’ve done, oh, 20 or 30 times? Well, easy, right? Just go back into that feed, enter edit mode again, and then go over the list again and mark those you still want to read as unread, right? Yes, except for one thing: if Byline syncs before you’ve had a chance to read those posts you’ve just marked as unread, they automatically get marked as unread again. If you’ve elected to include unread items in Byline (it’s a setting), you can’t tell which ones were magically marked as unread by the sync. And if you don’t have unread items included in Byline, those items are just gone.

This has annoyed me many times.

In fairness, it’s not entirely Byline’s fault. One of its design philosophies is to use the Google API eagerly. So as soon as you’re done reading something, it’s marked as read, whether or not the app is actively syncing to Google Reader. This is handy because it means as soon as I’ve read something, if I sync NetNewsWire on my desktop, it’s marked as read there, too. It minimizes the appearance of duplication.

@phfish: “@theory I think they do it for performance reasons. It is a bit of an irritation, though.”

One of the APIs it calls ASAP is Google Reader’s “Mark All as Read API call”, and as Phantom Fish has said, Google provides no way to un-do that call. The result, for me at least, and certainly other users, is the loss of unread items.

I’ve had an interesting Twitter conversation with Phantom Fish about this issue this morning, trying to brainstorm ways to work around it. For me, I’d like to see either a confirmation button when I hit “Mark All as Read,” or have it not immediately leave edit mode but turn the “Mark All as Read” button into an “Undo” button, so that I have a chance to undo the marking all as read while still in edit mode, before the API call gets sent to Google. Phantom Fish is understandably reluctant to make a change such as this, however, because so many people like and have requested the single-tap to mark all as read. There are users who want both things. And Phantom Fish is reluctant to add a setting for such a feature, and indeed, I also tend to favor convention over configuration.

It’s a bit of a thorny issue, but one that I think nicely highlights the philosophical difference between Apple and Google. On iOS, I’m used to nothing I do while in an edit mode being committed until I hit the “Done” button. Byline’s “Mark All as Read” button short-circuits this behavior by ending the editing without me hitting “Done,” and instantly calls the Reader API. This is very convenient for power users (who never hit the “Mark All as Read” button accidentally, I guess), and strongly reminds me of how Geek-oriented Google applications like Reader are. I’m guessing such power users are Google Reader users. I’m not, I just use it for syncing.

The emphasis of “Mark all as Read” and its underlying API is ro “get things done in as few steps as possible.” This contrasts with the Apple philosophy exhibited in iOS, where things should of course be done as efficiently as possible, but where, I think, the principle of least surprise is emphasized. It’s handy to mark all as read with one tap, unless you didn’t want to, in which case it’s surprising that you can’t get the unread items back—specially since you never told the app you were done editing. Google Reader power-user types want the convenience of one tap. Folks like me, used to the relatively low levels of the unexpected on iOS, want things to change only when we say we’re ready for the change.

Anyway, I expect that Phantom Fish will work out some way to deal with this issue. (Frankly, I’d welcome the ability to exclude certain feeds from Byine, as NetNewsWire for iOS does, so that I don’t have to bother with some feeds on my iPhone, but that’s a different feature request.) But I thought it was interesting, in discussing the issue, how UI philosophical interests can conflict. Frankly, I think that iOS apps should be more iOSy in this respect (in all other ways Byline is very iOSy), but others disagree, and it makes for an interesting conversation.

Mac OS X CD-ROM File Systems WTF?

Didn't it used to be the case that when you used the Mac OS X Finder to burn a CD-ROM that you could then mount that CD-ROM on a Windows box? In the last few months, I'm suddenly finding that this is no longer the case. So now I have to use hdiutil to convert a .dmg file to the Joliet and ISO9660 file systems:

hdiutil makehybrid -o image.iso -joliet -iso image.dmg

And then I could burn a CD readable on Windows. What the fuck? I burned three CDs that were then useless to me before I finally dug up this hint. And I had this problem with CDs burned by Tiger, too, last summer, so it's not just Leopard. It seems to me that Mac OS X should always default to building a hybrid CD that's then readable by Windows, Linux, and everything else. Why doesn't it?

Where iCal Keeps Invitations

I was fiddling with iCalendar invitations yesterday, trying to get Sandy's .ics files to import into Outlook. I got that figured out (yes!), but in the meantime iCal started crashing on me. I was reasonable sure that it was due to a bogus invitation file, but could not for the life of me figure out where iCal was keeping such files. It just kept crashing on me as second or so after starting up, every time.

I finally figured it out by quitting all my apps, moving all of the folders in ~/Library to a temporary folder, and firing up iCal to see what folds it would create. And there it was: ~/Library/Caches/com.apple.iCal. I quit iCal, deleted the new folders in ~/Library, moved the originals back, and looked inside the iCal caches folder to find a bunch of invitation files in the incoming folder. I deleted them all and iCal fired up again without a hitch. W00t!

So if you're having problems with iCal crashing and have a few invitations in it and you're wondering how to get iCal to ignore them, just quit iCal, delete all of the files in /Users/yourusername/Library/Caches/com.apple.iCal/incoming, and start iCal back up again.

And now I'll be able to find this information again when next I need it. :-)

Configuring rsnapshot and launchd on Mac OS X

Just a few quick notes on how I set up launchd to run rsnapshot to backup my new iMac. The configurations I made are based on Kenn Christ's blog entry.

  1. Installed the rsnapshot port:

    sudo port install rsnapshot
  2. Changed /opt/local/etc/rsnapshot.conf as follows:

    snapshot_root	/Volumes/Demiterra/Backup/
    #interval	hourly	6
    rsync_long_args	--delete --numeric-ids --relative --delete-excluded -extended-attributes
    exclude	*.cpan*
    link_dest	1
    #backup	/home/		localhost/
    #backup	/etc/		localhost/
    #backup	/usr/local/	localhost/
    backup	/Users/		
    

    Note that I've commented out hourly backups and the default backup directories. I'm using the Backups subdirectory on a My Book half terrabyte drive that I picked up at Costco for $220. Your configuration may of course differ.

  3. Tested it by manually running:

    sudo /opt/local/bin/rsnapshot daily
  4. Created hourly, daily, weekly, and monthly launchd plist files for rsnapshot. The hourly one runs every six hours and I threw it in just for completeness. You can download them all from here. Just put them into /Library/LaunchDaemons and run:

    sudo launchctl load -w /Library/LaunchDaemons/org.rsnapshot.periodic-*.plist

And that's it. Enjoy!

No UTF-8 Support on Windows?

This just blows. It will be a while before Bricolage runs on Windows, then. The PostgreSQL team is understandably reluctant to simply include the whole ICU library in PostgreSQL. Maybe it could be compiled into the binaries, though?

Compiling libreadline on Mac OS X

I just realized that I never posted my recipe for configuring and installing libreadline on Mac OS X. I need it for use with PostgreSQL, and don't fully understand why Apple has not yet included it with Mac OS X. Maybe it'll be in Tiger?

In the meantime, it turns out to be pretty easy to configure it and build it yourself, assuming you have the developer tools (Xcode) installed. The only thing that's different from any other Unix is that the support/shobj-conf must be modified to be able to find other libraries installed on Mac OS X. Here's a shell script I whipped up that can do the whole thing for you, soup-to-nuts.

#!/usr/bin/sh
export VERSION=4.3
curl -O ftp://ftp.gnu.org/pub/gnu/readline/readline-$VERSION.tar.gz
tar zxvf readline-$VERSION.tar.gz
cd readline-$VERSION
perl -i.bak -p -e \
  "s/SHLIB_LIBS=.*/SHLIB_LIBS='-lSystem -lncurses -lcc_dynamic'/g" \
  support/shobj-conf
./configure
make
sudo make install

Hope that this helps others!

How Do I Know Whether NTPD is Working?

Well, after figuring out how to configure NTPD, it appears to be working well: there are two processes running, and there's a drift file. However, the drift file just has 0.000 in it, and ntpq doesn't seem to know much:

% ntpq -p
127.0.0.1: timed out, nothing received
***Request timed out

So, how do I know if it's working? Is it working? Shouldn't ntpq -p be more informative?

NTPD Configuration on FreeBSD and Red Hat Linux

Well, I got no responses to my request for assistance setting up NTPD on FreeBSD, but today I must've just been Googling better, because I found the resources I needed.

The most important site I found was the NTP configuration page from Computer Facilities Management at the University of Washington. It was valuable because it provided some simple ntpd.conf file samples that set up ntpd to run only as a client. So no I'm confident that no one will try to connect to my servers and cause any mischief. The CFM NTP page also helpfully pointed out that I could easily enable ntpd on my Red Hat box by typing chkconfig ntpd on.

Another interesting site I found is www.pool.ntp.org. The cool thing about using pool.ntp.org as the time server to synchronize my servers to is that it distributes the load to lots of time servers. So I set up my ntpd.conf files to point first to pool.ntp.org, and then to two geographically close servers.

And finally, this DynDNS page gave me the instruction I needed to get ntpd running on FreeBSD. All I had to do was add xntpd_enable="YES" to /etc/rc.conf. I restarted my box, and now I'm in business!

How do I Configure NTPD?

So I need simple instructions to get NTPD running on FreeBSD. It should function solely as a client, and not accept connections from other servers. I could also use the corresponding instructions for Linux (and don't say RPM!). I've found an awful lot of information online about NTPD, but the simple instructions for setting up a secure NTPD to start when the system starts up are sorely lacking. Part of the problem with regards to BSD may be my not yet fully understanding how FreeBSD startup stuff is supposed to work, but I also can't find simple instructions for how to configure ntptd to operate only as a client.

Links and instructions gladly accepted.

My Adventures with Mac OS X

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.

Developer Tools

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

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.

Emacs

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 beautfully 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 .emacs file:

(custom-set-faces
'(default ((t (:stipple nil
  :background "DarkSlateGrey"
  :foreground "Wheat"
  :inverse-video nil
  :box nil
  :strike-through nil
  :overline nil
  :underline nil
  :slant normal
  :weight normal
  :height 116
  :width normal
  :family "apple-andale mono"))))
'(cursor ((t (:background "Wheat"))))
; Use option for the meta key.
(setq mac-command-key-is-meta nil)

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

GDBM

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:

cd /usr/local/src/gdbm-1.8.0
cp /usr/libexec/config* .
./configure
make
make install
ln -s /usr/local/lib/libgdbm.a \
  /usr/local/lib/libdbm.a

That did the trick. Nothing else was involved, fortunately.

Expat

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 page, and then did this:

cd /usr/local/src/expat-1.95.2
./configure
perl -i.bak -p -e \
  's/LDFLAGS\s*=\s*-static/LDFLAGS=/' \
  examples/Makefile
perl -i.bak -p -e \
  's/LDFLAGS\s*=\s*-static/LDFLAGS=/' \
  xmlwf/Makefile
make
make install

Perl

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, modules, etc.).

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:

cd /usr/local/src/perl-5.6.1/
export LC_ALL=C
export LANG=en_US
perl -i.bak -p -e \
  's|Local/Library|Library|g' hints/darwin.sh
sh Configure -des -Dfirstmakefile=GNUmakefile \
  -Dldflags="-flat_namespace"
make
make test
make install

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.

Downloads

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

Open SSL

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 this:

cd /usr/local/src/openssl-0.9.6c
./config
make
make test

mod_ssl

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:

./configure \
  --with-apache=/usr/local/src/apache_1.3.23

mod_perl

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 preceeded 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:

cd /usr/local/src/mod_perl-1.26
perl Makefile.PL \
  APACHE_SRC=/usr/local/src/apache_1.3.23/src \
  NO_HTTPD=1 \
  USE_APACI=1 \
  PREP_HTTPD=1 \
  EVERYTHING=1
make
make install

Apache

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:

SSL_BASE=/usr/local/src/openssl-0.9.6c/ \
    ./configure \
    --with-layout=Apache \
    --enable-module=ssl \
    --enable-module=rewrite \
    --enable-module=so \
    --activate-module=src/modules/perl/libperl.a \
    --disable-shared=perl \
    --without-execstrip
  make
  make certificate TYPE=custom 
  make install

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.

Note that 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.

libapreq

Once Apache is installed with mod_perl and mod_ssl, the rest is gravy! The experimental libapreq library I downloaded installed without a hitch:

cd /usr/local/src/httpd-apreq
perl Makefile.PL
make
make install

PostgreSQL

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 sytem 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:

./configure --enable-multibyte=UNICODE
make
make install

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 Unix system:

sudo -u postgres /usr/local/pgsql/bin/initdb \
  -D /usr/local/pgsql/data

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

XML::Parser

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 \
  EXPATINCPATH=/usr/local/include
make
make test
make install

Text::Iconv

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:

cd /usr/local/src/libiconv-1.7
./configure
make
make install

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'\]/" \
  Makefile.PL
perl Makefile.PL
make
make test
make install

DBD::Pg

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 varibles to install it (anyone know why DBD::Pg's Makefil.PL script can't try to figure those out on its own?), but still I got this error during make:

/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:

ranlib /usr/local/pgsql/lib/libpq.a
export POSTGRES_INCLUDE=/usr/local/pgsql/include
export POSTGRES_LIB=/usr/local/pgsql/lib
perl Makefile.PL
make
make test
make install

LWP

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 afert 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 poped it in an executed the command:

cp "/Volumes/Mac OS X Install CD/usr/bin/head" \
  /usr/bin

And then everything was happy again.

Bricolage

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.