How To: Cross compiling libraries for iOS (armv6/armv7/i386)

Update

• If you wanna compile and use Tesseract  3.01 on Xcode 4.2 with iOS SDK 5, check my new post “How To: Compile and Use Tesseract (3.01) on iOS (SDK 5)”.

So, if you’re a smart programmer, when you get asked to solve some new problem (“new” in the “I’ve never done this before” sense) you head over to Chrome (not Opera/Firefox, as I stated earlier, you’re SMART, not FASHION or OUTDATED), hit “CTRL + L” and start typing some keywords related to your problem, hit ENTER and wait for the amazing amount of resources Google (not Bing, because, as I stated earlier, you’re a programmer, not a no-brains) will hand you.

Among those resources, if you’re lucky enough, you’ll find out an OpenSource library that claims to solve exactly, or at least a piece of, your problem. This Library has binary downloadable packages for almost every OS you can imagine and even for OpenSolaris BUT, if you’re a mobile App developer (Android/iOS), they won’t give a fck!ng d@mn $h!t binary for your target OS.

Well, at this point, if you’re in a good day and helped that old lady cross the street a couple of hours earlier, this Library will be ready to compile through one configure script named, ehrm… “configure”.

If you’ve made it through here, maybe I can save your day. I’ve prepared one Bash script that is able to cross-compile one (or more) Static Library in different architectures (armv6/armv7/i386) and pack all different lib*.a into one single FAT FILE (or Universal Binary) so you can link against the same file when compiling for iPhone3G/3GS/4/Simulator.

Before we get our hands dirty, I’d like to clarify that:

• Armv6 binaries are needed if you’re targeting iPhone3G (yes, they still exist, my co-worker uses one, can u believe it?);
• Armv7 binaries are desirable if you’re targeting iPhone3GS/4 or iPad, since these new toys have Armv7 processors and, besides being able to rum Armv6 binaries, they probably will have a better performance using the better Armv7 architecture;
• i386 binares are needed if you intent to run your code at the Simulator (ok, it is needed, right?!).

Let’s get this party started! (or: Compiling)

Basically, for each architecture, we’ll be:

1. Pre-configuring the environment: setting some environment variables to values related to our current arch;
2. Configuring the library through its own “configure” script;
3. Compiling the library, hell yeah!

For explanation, I’ll be compiling the Leptonica and Tesseract-OCR libraries. My folder structure for this script is the following:

• ./ – root dir
• ./dependencies/ – folder where the final binary and headers will be placed;
• ./leptonlib-1.67 – folder with the sources of the first library I wanna compile;
• ./opencv/ – folder with the sources of the second library (that depends on the first one) I wanna compile;
• ./build_dependencies.sh – the bash script I’m explaining you.

Initially we’ll be setting some globals:

GLOBAL_OUTDIR="`pwd`/dependencies"
mkdir -p $GLOBAL_OUTDIR/include $GLOBAL_OUTDIR/lib
OUTDIR="./outdir"
LEPTON_LIB="`pwd`/leptonlib-1.67"
TESSERACT_LIB="`pwd`/tesseract_ocr"

IOS_BASE_SDK="4.2"
IOS_DEPLOY_TGT="3.2"

• $GLOBAL_OUTDIR is a common folder where includes and lib files from every library will be put into;
• $OUTDIR is a folder name where, inside each lib dir, we’ll be putting the lib files that library generates, before moving them to the global one;
• $LEPTON_LIB and $TESSERACT_LIB are the libraries I’m compiling;
• $IOS_BASE_SDK is the iOS SDK version you’re compiling against;
• $IOS_DEPLOY_TGT the iOS SDK minimum version you’ll allow your App to run.

Then, we’ll define a common function to be used for all architectures:

setenv_all()
{
        # Add internal libs
        export CFLAGS="$CFLAGS -I$GLOBAL_OUTDIR/include -L$GLOBAL_OUTDIR/lib"

        export CPP="$DEVROOT/usr/bin/cpp-4.2"
        export CXX="$DEVROOT/usr/bin/g++-4.2"
        export CXXCPP="$DEVROOT/usr/bin/cpp-4.2"
        export CC="$DEVROOT/usr/bin/gcc-4.2"
        export LD=$DEVROOT/usr/bin/ld
        export AR=$DEVROOT/usr/bin/ar
        export AS=$DEVROOT/usr/bin/as
        export NM=$DEVROOT/usr/bin/nm
        export RANLIB=$DEVROOT/usr/bin/ranlib
        export LDFLAGS="-L$SDKROOT/usr/lib/"

        export CPPFLAGS=$CFLAGS
        export CXXFLAGS=$CFLAGS
}

Note that $GLOBAL_OUTDIR is used as an include path (include sub-directory) and library path (lib sub-directory) so that if one of the libraries you’re compiling depend on each other (which is my case), they can link against each other.

And, finally a setenv function for each architecture:

setenv_arm6()
{
        unset DEVROOT SDKROOT CFLAGS CC LD CPP CXX AR AS NM CXXCPP RANLIB LDFLAGS CPPFLAGS CXXFLAGS

        export DEVROOT=/Developer/Platforms/iPhoneOS.platform/Developer
        export SDKROOT=$DEVROOT/SDKs/iPhoneOS$IOS_BASE_SDK.sdk

        export CFLAGS="-arch armv6 -pipe -no-cpp-precomp -isysroot $SDKROOT -miphoneos-version-min=$IOS_DEPLOY_TGT -I$SDKROOT/usr/include/"

        setenv_all
}

setenv_arm7()
{
        unset DEVROOT SDKROOT CFLAGS CC LD CPP CXX AR AS NM CXXCPP RANLIB LDFLAGS CPPFLAGS CXXFLAGS

        export DEVROOT=/Developer/Platforms/iPhoneOS.platform/Developer
        export SDKROOT=$DEVROOT/SDKs/iPhoneOS$IOS_BASE_SDK.sdk

        export CFLAGS="-arch armv7 -pipe -no-cpp-precomp -isysroot $SDKROOT -miphoneos-version-min=$IOS_DEPLOY_TGT -I$SDKROOT/usr/include/"

        setenv_all
}

setenv_i386()
{
        unset DEVROOT SDKROOT CFLAGS CC LD CPP CXX AR AS NM CXXCPP RANLIB LDFLAGS CPPFLAGS CXXFLAGS

        export DEVROOT=/Developer/Platforms/iPhoneSimulator.platform/Developer
        export SDKROOT=$DEVROOT/SDKs/iPhoneSimulator$IOS_BASE_SDK.sdk

        export CFLAGS="-arch i386 -pipe -no-cpp-precomp -isysroot $SDKROOT -miphoneos-version-min=$IOS_DEPLOY_TGT"

        setenv_all
}

Just to follow the file structure, I’ll be dropping these functions now, they are responsible for merging lib*.a files from different architectures into a single one (using lipo) and merging lib*.a files from the same architecture into a single one (this one was particularly useful for my case, so you can skip it):

create_outdir_lipo()
{
        for lib_i386 in `find $OUTDIR/i386 -name "lib*\.a"`; do
                lib_arm6=`echo $lib_i386 | sed "s/i386/arm6/g"`
                lib_arm7=`echo $lib_i386 | sed "s/i386/arm7/g"`
                lib=`echo $lib_i386 | sed "s/i386\///g"`
                lipo -arch armv6 $lib_arm6 -arch armv7 $lib_arm7 -arch i386 $lib_i386 -create -output $lib
        done
}

merge_libfiles()
{
        DIR=$1
        LIBNAME=$2

        cd $DIR
        for i in `find . -name "lib*.a"`; do
                $AR -x $i
        done
        $AR -r $LIBNAME *.o
        rm -rf *.o __*
        cd -
}

Now that we’ve defined all the functions we’ll need, let’s compile the first library!

Leptonica

#######################
# LEPTONLIB
#######################
cd $LEPTON_LIB
rm -rf $OUTDIR
mkdir -p $OUTDIR/arm6 $OUTDIR/arm7 $OUTDIR/i386

Enter the library subdir, remove any old built files and re-create the $OUTDIR dir structure.

make clean 2> /dev/null
make distclean 2> /dev/null

Clean anything that might have happened earlier.

setenv_arm6
./configure --host=arm-apple-darwin6 --enable-shared=no --disable-programs --without-zlib --without-libpng --without-jpeg --without-giflib --without-libtiff

Configure the environment for Armv6 architecture and call the library configure script. The following parameters are very important:

• –host=arm-apple-darwin6: Defines the architecture;
• –enable-shared=no: Builds the library as a statical one, since we can’t use dynamically linked libraries on iOS Applications;
• The other ones are specific for this project and suited to my preferences.

make -j4
cp -rvf src/.libs/lib*.a $OUTDIR/arm6

Compiles the library in 4 separated tasks (faster and recommended on Core2Duo processors) and copies the generates lib*.a files to the architecture specific $OUTDIR subfolder.

It is very important to notice that your library may generate the Library files (lib*.a) in a different folder, so it is advisable that, after “make -j4”, you issue the following command to find your lib*.a files:

find . -name "lib*.a"

If your lib*.a files are in a different location, change the cp command argument “src/.libs/lib*.a” to your different location.

After this, we repeat the commands (with the appropriated different arguments) for the other architectures:

make clean 2> /dev/null
make distclean 2> /dev/null
setenv_arm7
./configure --host=arm-apple-darwin7 --enable-shared=no --disable-programs --without-zlib --without-libpng --without-jpeg --without-giflib --without-libtiff
make -j4
cp -rvf src/.libs/lib*.a $OUTDIR/arm7

make clean 2> /dev/null
make distclean 2> /dev/null
setenv_i386
./configure --enable-shared=no --disable-programs --without-zlib --without-libpng --without-jpeg --without-giflib --without-libtiff
make -j4
cp -rvf src/.libs/lib*.a $OUTDIR/i386

And now, let’s get to what we want: get the library files!

create_outdir_lipo
mkdir -p $GLOBAL_OUTDIR/include/leptonica && cp -rvf src/*.h $GLOBAL_OUTDIR/include/leptonica
mkdir -p $GLOBAL_OUTDIR/lib && cp -rvf $OUTDIR/lib*.a $GLOBAL_OUTDIR/lib
cd -

Create a FAT file (by the “lipo” tool… interesting) containing the binaries for the 3 archs, copy the desired Header files (.h) to the leptonica include folder inside $GLOBAL_OUTDIR and copy the generated FAT file to $GLOBAL_OUTDIR/lib.

Well, if you’re interested in compiling a single library, this is it! But, OpenSource libraries often are using another OpenSource libraries… what happened to be my case. So let’s get to the second one:

Tesseract-OCR

This is the library I REALLY want compiled.

#######################
# TESSERACT-OCR (v3)
#######################
cd $TESSERACT_LIB
rm -rf $OUTDIR
mkdir -p $OUTDIR/arm6 $OUTDIR/arm7 $OUTDIR/i386

make clean 2> /dev/null
make distclean 2> /dev/null
setenv_arm6
./configure --host=arm-apple-darwin6 --enable-shared=no --without-libtiff --with-liblepto="$GLOBAL_OUTDIR/include/leptonica"
make -j4
for i in `find . -name "lib*.a"`; do cp -rvf $i $OUTDIR/arm6; done
merge_libfiles $OUTDIR/arm6 libtesseract_all.a

make clean 2> /dev/null
make distclean 2> /dev/null
setenv_arm7
./configure --host=arm-apple-darwin7 --enable-shared=no --without-libtiff --with-liblepto="$GLOBAL_OUTDIR/include/leptonica"
make -j4
for i in `find . -name "lib*.a" | grep -v arm`; do cp -rvf $i $OUTDIR/arm7; done
merge_libfiles $OUTDIR/arm7 libtesseract_all.a
make clean 2> /dev/null
make distclean 2> /dev/null
setenv_i386
./configure --enable-shared=no --without-libtiff --with-liblepto="$GLOBAL_OUTDIR/include/leptonica"
make -j4
for i in `find . -name "lib*.a" | grep -v arm`; do cp -rvf $i $OUTDIR/i386; done
merge_libfiles $OUTDIR/i386 libtesseract_all.a

create_outdir_lipo
mkdir -p $GLOBAL_OUTDIR/include/tesseract && cp -rvf api/apitypes.h api/baseapi.h ccmain/thresholder.h ccstruct/publictypes.h ccutil/ocrclass.h ccutil/unichar.h
 $GLOBAL_OUTDIR/include/tesseract
mkdir -p $GLOBAL_OUTDIR/lib && cp -rvf $OUTDIR/lib*.a $GLOBAL_OUTDIR/lib
cd -

Note that here I use “merge_libfiles”. The reason is that tesseract generates 15 (FIFTEEN!!!) libtesseract_*.a files, so I merge them into a single libtesseract_all.a.

It is also worthy to note that I’m using the custom configure argument:

--with-liblepto="$GLOBAL_OUTDIR/include/leptonica"

I had to modify the original configure script for tesseract v3.01 since it requires leptonica BUT would only check if it was present on your machine library paths and, since we’re not compiling for our machine, but to iOS architectures, it wouldn’t find a suitable leptonica to link against. The changes I’ve made are fairly simple and I’m making the modified file available as well.

Project Configuration

Now you have the include .h files and the libraries .a files, what about including ’em at your project? Open Xcode and do as explained:

1. Add the .h files as you would include any other source files: right-click your project at ” Groups and Files” -> Add -> Existing Files… -> Select the .h files (or the containing folder). I like to keep headers/sources I add this way organized within an “External Classes” group;
2. Add the .a files so your application will link against them: at “Groups and Files”, expand Targets -> Expand {YOUR_PROJECT_NAME} ->Right-click Link With Binaries -> Add -> Existing Files… -> Select the .a files;
3. Also, our pre-compiled libraries are generated with the better LLVM compiler, so we’ll set our application project to use LLVM and GCC so we can use libraries compiled with both compilers: at “Groups and Files”, double-click your project -> At Tab Build -> At Section Compiler Version -> Change C/C++ Compiler Version to: LLVM GCC 4.2.

That’s it, now you should be able to compile and run your own application.

Files for Download!

I really hope to be helping someone out there (let me know if so…) (really, I can get motivated to help out MORE):

• build_dependencies.sh: Cross compiling script that I’ve created – http://goo.gl/OuP7f
• configure: Modified script for compiling Tesseract v3.01 for iOS – http://goo.gl/iLOeR
• opencv_leptonica_tesseract_ios_42.zip: Headers and Libraries files for OpenCV, Leptonica and Tesseract (iOS 4.2)

Acknowledgements

• Quentin Liedtke: For the ‘mkdir -p’ correction
• Benjamin Ng: For the binaries providing hint
• venusbai: For the ‘leptonlib/-1.67’ correction (how did you find that?!)

• How To
• iOS
• Programming