The NDA that was part of the agreement between Apple and registered iPhone developers
was lifted yesterday. Not an hour had gone by before other developers started to
share tips,
code or even
full frameworks. Like them, we'd also like to contribute some of the learnings we've found during our work with Apple's SDK.
We've decided, therefore, to write a
second piece in our internationally acclaimed iPhone Programming Tips series. Our first article, devoted to
image orientation techniques, was written during our jailbreak apprenticeship, before the NDA even existed - how's that for anticipation?
This time we'll explore a very different area: how to build a Unix source package in such a way it can be used as part of your iPhone project.
The Problem
So you've found this wonderful open source Unix package that perfectly handles one of the areas you need in your application. Being a publicly scrutinized, well-maintained library, you decide you would waste your time if you tried to do something similar, so you try to use it in your project and concentrate on your own features. Or maybe you simply want to test how this thing would work in the iPhone. Whatever your reasons are, you download the distribution and read the
INSTALL file. This package is so well designed it compiles under a zillion Unix variants, including many evolutionary dead ends. It includes a fancy
"configure" script that guesses everything it needs to know to configure itself properly. Apple's Developer Tools include a full gcc/make toolchain, so you perform the sacred ritual
"./configure; make" and presto, you obtain an Intel dynamic library ready for use!
Wait a minute, that's not what you need. You want to cross-compile for ARM so that it runs on the device, of course. And you need it to run in the simulator, too.
Being a resourceful, tough programmer, you drop the source code on your Xcode project, alongside the rest of your code. You build your project and get like 148 errors and 57 warnings. Naturally, there are lots of definitions that
./configure should have defined, and the source defaults must be those of a PDP-11, or something. You try to tweak the settings manually for 10 minutes before you give up.
Your next step is to tell the configure script to cross-compile for a different platform. But you don't know exactly how to tell it your platform is like Mac OS X, only running on an arm chipset, what's the problem about that. After reading the scripts and template files and googling your way around, you use something like
./configure --host=arm-apple-darwin. This doesn't work, either, because configure insists on using your standard Mac OS X system libraries and headers instead of the ARM ones for the iPhone. You then try to tell configure to use the gcc compiler in your
/Developer distribution, and this still doesn't work. Oh, well. You know what you need to do - investigate compilation options and library locations - but it's painful.
Wouldn't it be nice to have some notes on how to set up your environment to compile an Unix package from the command-line, but using Xcode's development libraries for the iPhone?
The Solution
If you have read the introduction above, you will have noticed that it is just a feeble attempt to disguise the fact that this article is only going to tell you how to configure your environment variables to compile a Unix library using Xcode's toolchain from the command line. That's it. It is admittedly not a very glamourous or innovative task; however, we still had to devote a few lenghty hours to set everything up properly, following the embarrassing steps outlined above, one after the other.
So, without further circumlocutions, let us show the damned variables. I'll dissect one of the build scripts I have actually used, accompanying the definitions with some comments or caveats.
The following two definitions point to the root of the command line developer tools and iPhone SDK. You may need to modify them to update the location in your own system, or if you are using a newer version of the SDK:
export DEVROOT=/Developer/Platforms/iPhoneOS.platform/Developer
export SDKROOT=$DEVROOT/SDKs/iPhoneOS2.0.sdk
Next, let's save the current build environment - we'll use it later to build the i386 version of the library which will run in the simulator.
# Save relevant environment
U_CC=$CC
U_CFLAGS=$CFLAGS
U_LD=$LD
U_LDFLAGS=$LDFLAGS
U_CPP=$CPP
U_CPPFLAGS=$CPPFLAGS
We'll now define the values we need to use to target the ARM architecture. Compilation flags in my case look something like this:
export CPPFLAGS="-I$SDKROOT/usr/lib/gcc/arm-apple-darwin9/4.0.1/include/ -I$SDKROOT/usr/include/"
export CFLAGS="$CPPFLAGS -arch armv6 -pipe -no-cpp-precomp -isysroot $SDKROOT"
export CPP="/usr/bin/cpp $CPPFLAGS"
Linking flags are a bit more tricky. You need to ensure the output of the compilation process is a static library, and not a dynamic library or an executable file. Dynamic libraries can in fact be produced, but the iPhone sandbox will sadly refuse to load them at runtime - only dynamic libraries and frameworks in predefined system locations can be used. There's a mention about this limitation somewhere in the Development Agreement.
Even though you won't be using dynamic libraries in your project, some packages are configured in such a way that it is easier to let them compile the dylib then ignore it, rather than trying to convince them not to create the dynamic code. If you encounter such a case, you should configure your linker in a way similar to this:
# dynamic library location generated by the Unix package
LIBPATH=src/.libs/<libname>.dylib
LIBNAME=`basename $LIBPATH`
export LDFLAGS="-L$SDKROOT/usr/lib/ -Wl,-dylib_install_name,@executable_path/$LIBNAME"
This will create a valid dylib file that you will be able to use within Xcode; however, it won't run in the iPhone as described above.
Therefore, you will actually be interested in using the static library version, so we'll store its location:
# static library that will be generated
LIBPATH_static=src/.libs/<libname>.a
LIBNAME_static=`basename $LIBPATH_static`
Now we are ready to run the configure script and build the libraries.
./configure CC=$DEVROOT/usr/bin/arm-apple-darwin9-gcc-4.0.1 LD=$DEVROOT/usr/bin/ld --host=arm-apple-darwin
make
Depending on the package you are trying to compile, you might need to supply additional arguments to the configure script. Some packages, for example, will accept arguments indicating whether a static library or a dynamic one should be built. It is also frequent to disable features or modules you know you won't use in your project. You need to refer to your package documentation for fine tuning details.
After make finishes (hopefully without errors), we'll move away the generated libraries to a safe location:
mkdir -p lnsout
cp $LIBPATH_static lnsout/$LIBNAME_static.arm
We repeat now the same steps, but targetting the i386 architecture. This will allow us to build libraries compatible with our iPhone simulator environment.
make distclean
# Use default environment
export CC=$U_CC
export CFLAGS=$U_CFLAGS
export LD=$U_LD
export LDFLAGS=$U_LDFLAGS
export CPP=$U_CPP
export CPPFLAGS=$U_CPPFLAGS
# Overwrite LDFLAGS
# Dynamic linking, relative to executable_path
# Use otool -D to check the install name
export LDFLAGS="-Wl,-dylib_install_name,@executable_path/$LIBNAME"
# ToDo - error checking
./configure
make
# Save generated binaries
cp $LIBPATH_static lnsout/$LIBNAME_static.i386
After we have produced the i386 and arm versions of our library, we will create a fat Universal Binary enclosure containing both of them:
# Create fat lib
$DEVROOT/usr/bin/lipo -arch arm lnsout/$LIBNAME_static.arm -arch i386 lnsout/$LIBNAME_static.i386 -create -output lnsout/$LIBNAME_static
Finally, you can add the generated library and any necessary development header files to your project and build it. If everything went well, your application will be linked with the library and will run correctly in both the simulator and the device.
As explained above, this is mostly basic Unix tinkering, but it took us a while to get the right configuration. Maybe we were just rusty, so if you know a better way to achieve this, please do let us know!
