Tutorial: Open Source on iOS (Part 1): Build Your Tools

This the first in a series of tutorials explaining how to compile popular open source libraries for iOS. In this tutorial you will download and compile a number of tools used in the GNU Build System used by many open source projects, specifically autoconf, automake and libtool. Since each of these tools is built with the GNU Build System it also provide a useful introduction to the system itself. It should be noted that many projects can be built without having these tools installed, but when things go wrong it is useful to have them around.

Open source builds use the command line extensively. If you are familiar with bash you can probably skip most of my commentary about commands and scripting, if not, I hope I provide enough information for you to understand what is going on. If you ever forget how to use a command you can always type man command_name where command_name is the name of the command you are trying to use. The system will provide you with a manual page for the command.

Creating the Directory Structure

To get started open the terminal application and type the following:

cd ~
mkdir idz_builds
cd idz_builds
mkdir -p autoconf/2.69
mkdir -p automake/1.12
mkdir -p libtool/2.4.2

Let’s look at this a little more closely. The command cd changes directory; the tilde ‘~’ character is a shorthand for your home directory. (If you ever lose track of the directory you are in you can type pwd to print the current working directory). The command mkdir idz_build creates a new directory named idz_build. The following command changes into this newly created directory. This directory will be the root directory containing all your source, builds and scripts for your open source builds.

The remaining commands create directories for each of the tools you are about to build. As time goes on you may need to build updated versions so a sub-directory is created for each version. The -p flag instructs mkdir to make all directories in the path.

Building autoconf

The first tool you will build is autoconf. Type the following command.

pushd autoconf/2.69

The command pushd is similar to cd in that it changes directory but it also pushes the directory you were in onto a directory stack. To pop a directory off the stack and change to it use the popd command.

Now that you are in the appropriate directory you download and decompress the source for autoconf using the following commands.

curl -O http://ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz
tar xvfz autoconf-2.69.tar.gz

The command curl is a command line equivalent of downloading a file via your web browser. The -O argument tells the command to create an output file with the basename of the URL; in this case autoconf-2.69.tar.gz.

The tar command is the command line equivalent of uncompressing an archive file. The argument xvfz means extract, verbose, file, unzip.

mkdir build
pushd build
../autoconf-2.69/configure
make

To test that the build has been successful you can run (WARNING: on my MacBook Air this took quite some time. You can skip this step):

make check

To install the results of the build you type:

sudo make install

This command will prompt you for your password. Before you type it you should understand what is going on here. Your computer has a concept of a superuser (a.k.a. root). The sudo command executes whatever follows it as if it were superuser. The make install command needs to be executes as root because it will install programs in a global directory (in this case /usr/local).

If you want to test that your install has been successful you can type (WARNING: on my MacBook Air this took quite some time. You can skip this step):

make install check

To return to the top-level idz_build directory type:

popd
popd

To make sure your system is using your newly build autoconf type:

autoconf --version

It is quite possible that your system may not find you newly installed version or no version may exist.

To correct this problem type the following commands:

echo 'export PATH=/usr/local/bin:$PATH' >> ~/.profile

The echo command simply prints its arguments, items in single quotes are printed explicitly, but the >> operator causes the output to appended to a file, in this case, a special, hidden file called .profile. The .profile file is used to set variables for your command line terminal (shell). The PATH special environment variable is used to tell the shell where to look for executable commands. The export command makes the changes to PATH globally available. The assignment PATH=/usr/local/bin:$PATH prepends /usr/local/bin to the search path /usr/local/bin first when looking for commands to execute.

Building automake

In the last section, to explain the steps involved in compiling a GNU tool, I suggested typing commands one by one. To repeat this process would be tedious, therefore I suggest gathering these commands into a shell script. A shell script is a sequence of commands gathered into a file.

Let’s review the basic steps:

curl -O $IDZ_URL
tar xvfz $IDZ_TAR_NAME
mkdir build
cd build
../$IDZ_DIR_NAME/configure
make
sudo make install

So essentially all we need to do supply suitable values for the variables, that is, the values prefixed with the $ sign.

It turns out that these values can be easily derived from the program name and version.

IDZ_DIR_NAME=$IDZ_PROGRAM-$IDZ_VERSION
IDZ_TAR_NAME=$IDZ_DIR_NAME.tar.gz
IDZ_URL=http://ftp.gnu.org/gnu/$IDZ_PROGRAM/$IDZ_TAR_NAME

Putting all this together we can create the following minimal script:

#!/bin/bash
IDZ_PROGRAM=$1
IDZ_VERSION=$2

IDZ_DIR_NAME=$IDZ_PROGRAM-$IDZ_VERSION
IDZ_TAR_NAME=$xiIDZ_DIR_NAME.tar.gz
IDZ_URL=http://ftp.gnu.org/gnu/$IDZ_PROGRAM/$IDZ_TAR_NAME

curl -O $IDZ_URL
tar xvfz $IDZ_TAR_NAME
mkdir build
cd build
../$IDZ_DIR_NAME/configure
make
sudo make install

In this script that #!/bin/bash is just some magic to make a script run as a program and the $1 and $2 refer to the first and second arguments given to the program. So, executed in the correct directory, idz_gnu_tool automake 1.12 should download, build and install automake version 1.12.

This is a minimal script because it does not error checking. The following is a more complete script:

#!/bin/bash

# We need a program_name and a version_number
if [ $# -lt 2 ] ; then
  echo "usage: $0 <program_name> <version_number>"
  exit 1
fi

IDZ_PROGRAM=$1
IDZ_VERSION=$2

IDZ_DIR_NAME=$PROGRAM-$VERSION
IDZ_TAR_NAME=$DIR_NAME.tar.gz
IDZ_URL=http://ftp.gnu.org/gnu/$PROGRAM/$TAR_NAME

IDZ_SAVE_DIR=`pwd`

idz_check_error()
{
  if [ $? -ne 0 ] ; then
    echo $1
    cd $IDZ_SAVE_DIR
    exit 1
  fi
}

curl -O $URL
idz_check_error "Failed to download from $URL"

tar xvfz $TAR_NAME
idz_check_error "Failed to extract $TAR_NAME"

mkdir build
cd build

../$DIR_NAME/configure
idz_check_error "Configuration failed."

make
idz_check_error "Build failed."

echo "Enter password to allow installation."
sudo make install
idz_check_error "Configuration failed."

cd $IDZ_SAVE_DIR

This is the first of a number of scripts you will be creating to avoid repetitive tasks. Create a directory to hold scripts and change into it:

cd ~/idz_builds
mkdir bin
pushd bin

You can now either download and decompress the above script:

curl -O https://iosdeveloperzone.com/tutorials/idz_gnu_build.gz
gunzip idz_gnu_build.gz

or if you prefer copy and paste the script using your favorite text editor. If you do not have a favorite text editor the following will create and empty file and open it in the TextEdit app:

touch idz_gnu_build
open -a TextEdit idz_gnu_build

The script file needs to be made executable to allow it to run. Issue the following command:

chmod u+x idz_gnu_build

This command adds (+) execute permission for the user that owns the file.

Finally you need to make sure that shell can find this file. Modify the last lines of your ~/.profile as follows:

export IDZ_BUILD_ROOT=~/idz_builds
export PATH=/usr/local/bin:$IDZ_BUILD_ROOT/bin:$PATH

Line 1 creates a new environment variable IDZ_BUILD_ROOT which you will use in later scripts. Line 2 is a modification of the change you made after compiling autoconf that adds you new script directory to places the shell searches for executables.

If all has gone well you should now be able to type the following commands:

pushd $IDZ_BUILD_ROOT/automake/1.12
idz_gnu_build automake 1.12
popd

This will download, build and install automake.

Compiling libtool

Compiling libtool is now trivial:

pushd $IDZ_BUILD_ROOT/libtool/2.4.2
idz_gnu_build libtool 2.4.2
popd

Verifying Tool Versions

You can check all the tools are successfully installed and that the shell is finding the correct versions by typing:

autoconf --version
automake --version
libtool --version

You will need all of these tools to be correctly installed before continuing to the next tutorial “Compiling libogg for iOS”.