iosgdalogr

Incorporating GDAL/OGR into an iOS project - A quick guide

Here is the problem: GDAL is a fantastic open source library designed to manage complex GIS data, both raster as well as vector. It is fully compiled for the Mac OS (courtesy of William Kyngesburye) and other platforms but not for iOS.

Browsing the net you can find bits and pieces of (relatively old) information on the topic of creating an iOS library, starting with the famous script from pseudogreen which was written over 3 years ago. There are also bits and pieces on stack-overflow such as GDAL / OGR on the iPhone which provide additional information.

This article is meant to cover all the steps I took which led me to a fully functional integration of GDAL/OGR in a simple iOS app using iOS6 and XCode 4.5.5

Solution

  • Note

    This response was written some time ago and mo longer works with Xcode 6 and up. Please check this link for a more current answer to this problem.

    Introduction

    Incorporating GDAL into your iOS app is a 5 steps process:

    1. Download the GDAL source code from the GDAL website
    2. Run the configure/build/install script given below
    3. Add the resulting static library into your iOS project along with the include files
    4. Link with additional libraries in your iOS project
    5. Start coding... the GDAL and OGR tutorials are good starting points

    Downloading GDAL

    GDAL is a C++ open source library which can be downloaded from the www.gdal.org web site. At the time of writing the latest version is 1.9.0. You should download the latest stable version if possible.

    Run the script to compile GDAL for iOS and the simulator

    In order to use GDAL in your iOS project you need to compile the source code as a static library (.a). With the latest iOS6-supported architecture you should create the static library for the following architectures:

    Base script to build for 1 architecture

    The following script, which is adapted from pseudogreen's does the trick of compiling the source code for a single architecture.

    Copy paste this code into a text editor and save it as file with .sh extension: for instance build_gdal_ios.sh.

    To use it copy the script into the directory where you downloaded the gdal source code and run it as follows:

    You can also type sh build_gdal_ios.sh -h to get the help.

        #!/bin/bash
    ################################################################################
    #
    # Copyright (c) 2008-2009 Christopher J. Stawarz
    #
    # Permission is hereby granted, free of charge, to any person
    # obtaining a copy of this software and associated documentation files
    # (the "Software"), to deal in the Software without restriction,
    # including without limitation the rights to use, copy, modify, merge,
    # publish, distribute, sublicense, and/or sell copies of the Software,
    # and to permit persons to whom the Software is furnished to do so,
    # subject to the following conditions:
    #
    # The above copyright notice and this permission notice shall be
    # included in all copies or substantial portions of the Software.
    #
    # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
    # NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
    # BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
    # ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
    # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    # SOFTWARE.
    #
    ################################################################################



    # Disallow undefined variables
    set -u


    default_gcc_version=4.2
    default_iphoneos_version=6.0
    default_macos_version=10.8
    default_architecture=armv7
    default_prefix="${HOME}/Documents/iOS_GDAL"

    GCC_VERSION="${GCC_VERSION:-$default_gcc_version}"
    export IPHONEOS_DEPLOYMENT_TARGET="${IPHONEOS_DEPLOYMENT_TARGET:-$default_iphoneos_version}"
    export MACOSX_DEPLOYMENT_TARGET="${MACOSX_DEPLOYMENT_TARGET:-$default_macos_version}"
    DEFAULT_ARCHITECTURE="${DEFAULT_ARCHITECTURE:-$default_architecture}"
    DEFAULT_PREFIX="${HOME}/Documents/iOS_GDAL"

    echo Default architecture: $DEFAULT_ARCHITECTURE

    usage ()
    {
        cat >&2 << EOF
    Usage: ${0##*/} [-ht] [-p prefix] [-a arch] target [configure_args]
        -h  Print help message
        -p  Installation prefix (default: \$HOME/Documents/iOS_GDAL...)
        -t  Use 16-bit Thumb instruction set (instead of 32-bit ARM)
        -a  Architecture target for compilation (default: armv7)

    The target must be "device" or "simulator".  Any additional arguments
    are passed to configure.

    The following environment variables affect the build process:

        GCC_VERSION (default: $default_gcc_version)
        IPHONEOS_DEPLOYMENT_TARGET  (default: $default_iphoneos_version)
        MACOSX_DEPLOYMENT_TARGET    (default: $default_macos_version)
        DEFAULT_PREFIX  (default: $default_prefix)
    EOF
    }

    prefix="${DEFAULT_PREFIX}"

    echo Prefix: $prefix

    while getopts ":hp:a:t" opt; do
        case $opt in
        h  ) usage ; exit 0 ;;
        p  ) prefix="$OPTARG" ;;
        t  ) thumb_opt=thumb ;;
        a  ) DEFAULT_ARCHITECTURE="$OPTARG" ;;
        \? ) usage ; exit 2 ;;
        esac
    done
    shift $(( $OPTIND - 1 ))

    if (( $# < 1 )); then
        usage
        exit 2
    fi

    target=$1
    shift

    case $target in

        device )
        arch="${DEFAULT_ARCHITECTURE}"
        platform=iPhoneOS
        extra_cflags="-m${thumb_opt:-no-thumb} -mthumb-interwork"
        ;;

        simulator )
        arch=i386
        platform=iPhoneSimulator
        extra_cflags="-D__IPHONE_OS_VERSION_MIN_REQUIRED=${IPHONEOS_DEPLOYMENT_TARGET%%.*}0000"
        ;;

        * )
        echo No target found!!!
        usage
        exit 2

    esac


    platform_dir="/Applications/Xcode.app/Contents/Developer/Platforms/${platform}.platform/Developer"
    platform_bin_dir="${platform_dir}/usr/llvm-gcc-${GCC_VERSION}/bin"
    platform_sdk_dir="${platform_dir}/SDKs/${platform}${IPHONEOS_DEPLOYMENT_TARGET}.sdk"
    prefix="${prefix}/${arch}/${platform}.platform/${platform}${IPHONEOS_DEPLOYMENT_TARGET}.sdk"

    echo library will be exported to $prefix

    export CC="${platform_bin_dir}/llvm-gcc-${GCC_VERSION}"
    export CFLAGS="-arch ${arch} -pipe -Os -gdwarf-2 -isysroot ${platform_sdk_dir} ${extra_cflags}"
    export LDFLAGS="-arch ${arch} -isysroot ${platform_sdk_dir}"
    export CXX="${platform_bin_dir}/llvm-g++-${GCC_VERSION}"
    export CXXFLAGS="${CFLAGS}"
    export CPP="${platform_bin_dir}/llvm-cpp-${GCC_VERSION}"
    export CXXCPP="${CPP}"


    ./configure \
        --prefix="${prefix}" \
        --host="${arch}-apple-darwin" \
        --disable-shared \
        --enable-static \
        --with-unix-stdio-64=no \
        "$@" || exit

    make install || exit

    cat >&2 << EOF

    Build succeeded!  Files were installed in

      $prefix


   EOF

    Notice that this script has a few default parameters which you can change to reflect your preferences or changes in the SDK or LLVM Apple compiler:

    And now building for multiple architectures

    Using the preceding script (build_gdal_ios.sh) allows you to build one architecture at a time... You need to compile for 3 and then bring all these libraries together under one single static library file.

    The following script allows just that (save it to another name such as build_gdal_all_ios.sh):

    #!/bin/bash
make clean
./build_gdal_ios.sh -p ${HOME}/Documents/GDALLibrary -a armv7 device
make clean
./build_gdal_ios.sh -p ${HOME}/Documents/GDALLibrary -a armv7s device
make clean
./build_gdal_ios.sh -p ${HOME}/Documents/GDALLibrary simulator

    After running this script you will have your libraries saved in your ${HOME}/Documents/GDALLibrary directory in subfolders:

    You can now use the executable lipo (for liposuction) to join the 3 libraries into a single one like so:

    lipo ${HOME}/Documents/GDALLibrary/i386/iPhoneSimulator.platform/iPhoneSimulator6.0.sdk/lib/libgdal.a ${HOME}/Documents/GDALLibrary/armv7/iPhoneOS.platform/iPhoneSimulator6.0.sdk/lib/libgdal.a ${HOME}/Documents/GDALLibrary/armv7s/iPhoneOS.platform/iPhoneSimulator6.0.sdk/lib/libgdal.a -output ${HOME}/Documents/GDALLibrary/libgdal.a -create

    ... And you're done...

    Add the static library to your XCode project

    This step is rather straightforward:

    1. Create a new project in Xcode (4.5) or open the one you want to add GDAL to
    2. In the file explorer right click and select "Add files to projects"
    3. Select the libgdal.a created above along with the include files in one of the include directories (the 3 directories contain the same files)
    4. Add the following libraries to your XCode project (from the project framework list):
      • libstdc++.6.0.9.dylib
      • libz.dylib
      • libiconv.dylib
      • libsqlite3.dylib
      • libxml2.dylib (if Undefined symbols for architecture armv7: "_xmlCatalogResolveSystem" etc)

    Build your code. All should compile without trouble.

    Start coding

    There is a trick here: you are using a C++ library (and header files) in an Objective-C environment. If you include one of the GDAL header files into a .m file XCode will complain about the C++ syntax.

    Here you have two solutions:

    1. Write all your GDAL code inside .mm files which Xcode will then recognize as Objective-C++ files and will compile
    2. Use a class extension in your Objective-C files as described by Phil Jordan on his excellent article Mixing Objective-C++ and C++

    At one point I will be posting some GDAL code samples... but later...