Tutorial: Open Source on iOS (Part 2): Compiling libogg on iOS

In this tutorial you will learn how to compile open source libraries that use the GNU Build System (GBS) for iOS. I’ll be using the open source libogg library as an example, but the techniques you use should be useful for any source that uses GBS. Make sure you complete the previous tutorial “Open Source on iOS (Part 1): Gathering Your Tools” before attempting this one; it won’t work otherwise!

Preliminaries

The scripts in this tutorial will use the xcode-select command to locate the active Xcode installation. This is part of the Command Line Tools package. This package is not installed by default when installing from the App Store. To see if this is installed on your system, start Xcode and choose Xcode > Preferences…. Click the Downloads icon in the dialog. If Command Line Tools is not installed, click the install button.

To test that xcode-select is correctly installed and is pointing to your preferred Xcode installation type:
[code]
xcode-select -print-path
[/code]
you should see something like:

Your output may be slightly different. I modify the name of my Xcode directory to include the version number to allow multiple versions to co-exist.

If the output of xcode-select does not point to your preferred Xcode installation you can change it using something like:
[code]
xcode-select -switch /path/to/your/Xcode
[/code]

Cross-Compiling with configure

Cross-compiling refers to compiling a binary on one system for use on another. In your case this refers to compiling on a Mac for either the iOS simulator or an iOS device.

With the GNU Build System, a successful cross-compile depends on the value of a few environment variables and some command line options to the configure script. In most cases, setting the following environment variables:

• CC the path to the C compiler,
• CXX the path to the C++ compiler,
• CFLAGS the flags to pass to the C compiler,
• CXXFLAGS the flags to pass to the C++ compiler,
• LDFLAGS the flags to pass to the linker

and the following command line arguments:

• --host the system the binaries will run on,
• --prefix the installation location,
• --disable-shared only build static libraries

is sufficient to obtain working static libraries.

The Environment Variable Values

All of the flags (CFLAGS, CXXFLAGS, LDFLAGS) variables must include -isysroot and -arch command line arguments. The -isysroot command line argument specifies the SDK being used for compilation, while the -arch flag specifies the architecture; the arch flag should be one of: i386 (for the simulator), armv6, armv7 or armv7s.

These paths are rather long and tedious to type, so I will describe how they are related in script terms (and from that you will derive a script).

If we assume:
[code]
IDZ_XCODE_ROOT=xcode-select -print-path
[/code]
that is, the value of IDZ_XCODE_ROOT is the result of executing xcode-select, then the path to given platform directory is:
[code]
IDZ_PLATFORM_PATH=$IDZ_XCODE_ROOT/Platforms/$IDZ_PLATFORM.platform/Developer
[/code]
where IDZ_PLATFORM is one of: iPhoneSimulator or iPhoneOS.

The above result can be used to determine the platform binary (bin) directory needed for CC and CXX.
[code]
IDZ_PLATFORM_BIN_PATH=$IDZ_PLATFORM_PATH/usr/bin
[/code]
and the IDZ_PLATFORM_PATH the SDK path (needed for -sysroot) can be determined as follows:
[code]
IDZ_SDK_PATH=$IDZ_PLATFORM_PATH/SDKs/$IDZ_PLATFORM$IDZ_SDK_VERSION.sdk
[/code]
where IDZ_SDK_VERSION is, for example, 5.1 or 6.0.

With these variables in hand, the required environment variables for the configure script can be derived as follows:
[code]
# Cross-compile environment variables
IDZ_FLAGS="-isysroot $IDZ_SDK_PATH -arch $IDZ_ARCH"
CC=$IDZ_PLATFORM_BIN_PATH/llvm-gcc
CXX=$IDZ_PLATFORM_BIN_PATH/g++
CFLAGS=$IDZ_FLAGS
CXXFLAGS=$IDZ_FLAGS
LDFLAGS=$IDZ_FLAGS
export CC CXX CFLAGS CXXFLAGS LDFLAGS
[/code]
provided the values of IDZ_ARCH, IDZ_PLATFORM and IDZ_SDK_VERSION are known.

The Command Line arguments

The --host command line argument is either i386-apple-darwin10 for the simulator or arm-apple-darwin10 for a device. Notice that these values depend only on the value of IDZ_ARCH.

The --prefix command line argument is used to determine where the project will be installed. To ensure that distinct architecture have their own directories I will use install-$IDZ_PLATFORM-$IDZ_ARCH.

Putting It All Together

Putting all the above together and adding a little bit of error checking we obtain the following script. I have not covered all the syntax used in this script. I will come back and add more explanation when I have time.

Using your favorite text editor, copy and paste the following script into $IDZ_BUILD_ROOT/bin/idz_configure:

Remember to make it executable using:

Downloading the Source Code

Many open source projects provide stable releases available via download and “cutting edge” releases via source code control. The stable release of libogg, 1.3.0, available via download was not possible to adapt to cross-compilation so for this tutorial you will use the source control version.

Make sure you are in the idz_build directory:

Make a directory for libogg

Check out the code from source code control

The download distribution normally has the configure script pre-made. In this case you will need to create it.

The result of this process is a configure script that has been run for a Mac. This will interfere with your iOS build. To remove this configuration information issue the following command:

You will also need to make a correction to the configuration script. Open the configure script in a text editor and locate the section near line 11669:

Change the -O4 to -O3 to make it look like this:

For some reason gcc seems to generate invalid arm object files when optimization level 4 is used. Changing the optimization level to 3 seems to solve this problem.

You should now pop back to parent directory:

Using The idz_configure Script

This script will only work if you are in the correct directory. So as a precaution execute the command:

To attempt to build the library issue the following command (if you are not using the 6.0 SDK you should change this):

It will fail!

But why did it fail? Checking the error messages we see:
[code]
libtool: link: /Applications/Xcode-4.5.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/usr/bin/llvm-gcc -D_V_SELFTEST -fno-common -O4 -Wall -fsigned-char -ffast-math -isysroot /Applications/Xcode-4.5.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS6.0.sdk -arch armv7 -isysroot /Applications/Xcode-4.5.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS6.0.sdk -arch armv7 -o test_bitwise test_bitwise-bitwise.o
ld: warning: ignoring file test_bitwise-bitwise.o, file was built for unsupported file format ( 0x42 0x43 0xc0 0xde 0x21 0x c 0x 0 0x 0 0xf4 0x18 0x 0 0x 0 0x 1 0x10 0x 0 0x 0 ) which is not the architecture being linked (armv7): test_bitwise-bitwise.o
Undefined symbols for architecture armv7:
"_main", referenced from:
start in crt1.o
ld: symbol(s) not found for architecture armv7
[/code]

There is a lot of noise in this message but basically what it means is that, in the course of the build, it tried to run some executable that was not compiled for the build system’s architecture. Of course, since this was a cross-compile it should never have tried to run anything so where was the problem?

It turns out the problem is in the libogg-1.3.0/src/Makefile.am.

If you change the ‘noinst_PROGRAMS’ to ‘check_PROGRAMS’ this will solve the problem. What this change does is that it specifies that some programs were test or check programs and could only be run on the host system.

After making this change you must:

before running

this time the build should complete.

The previous step created the static library for use on a device (running a pre-iOS 6 OS, for iOS 6 and later use armv7s). To create a version for the simulator you need to use:

In the next tutorial you will learn how to combine multiple static libraries into a pseudo-framework.