Android_Qt.txt

This document contains various information regarding usage
of libosmscout for/under Android using the Qt backend
as part of Qt applications under Android.

Installation of the Android development environment under Arch Linux
====================================================================

Instructions are for compiling under x86_64 Arch Linux.

* Activate multilib, see https://wiki.archlinux.org/index.php/multilib
  and https://wiki.archlinux.org/index.php/Arch64_FAQ
  
* Install the Android AUR packages:
  https://wiki.archlinux.org/index.php/android
  
* I did not install any platforms at this point, since the
  android-qt5 package will install relevant AUR packages (platform
  versions 10, 11, 16) anyway.
  
* Install the normal Qt development environment and also the package
  android-qt5. Make sure that the Qt versions match. This will also
  pull in the android-ndk package.
  
* set environment variable ANDROID_NDK_ROOT, the variable should point
  to the root of the NDK.
  (in case of arch linux: /opt/android-ndk)
  
* Because we want to use the C++ compiler together with the stl, we
  need to create a standalone toolchain. For this call using root
  rights:

  make-standalone-toolchain.sh \
    --verbose \
    --toolchain=arm-linux-androideabi-4.8 \
    --system=linux-X86_64 \
    --install-dir=/home/tim/projects/arm-linux-androideabi-4.8

  The install directory of course could be places somewhere else

* set environment variable ANDROID_SYSROOT, the variable should point
  to the to be used platform tools sysroot directory.
  (/home/tim/projects/arm-linux-androideabi-4.8/sysroot im my case).

Cross compilation of libosmscout, libosmscout-map and libosmscout-map-qt
========================================================================

The Android SDK/NDK supports various toolschains for various platforms,
in the following examples we target arm-linux-androideabi, which is used by
most modern Android mobiles. We also target API level 16, which corresponds
to Android 4.1.2 - things however should work similar for other platforms
and API versions.

* extend the path to contain bin directory of your toolchain
  (/home/tim/projects/arm-linux-androideabi-4.8/bin)
  
* set a number of environment variables to point to the
  corresponding files in the toolchain directory:

  export CPP=arm-linux-androideabi-cpp
  export CC=arm-linux-androideabi-gcc
  export CXX=arm-linux-androideabi-g++
  export LD=arm-linux-androideabi-ld

  export CPPFLAGS="--sysroot=$ANDROID_SYSROOT -march=armv7-a -mfloat-abi=softfp -mfpu=vfp"
  export CFLAGS="--sysroot=$ANDROID_SYSROOT -march=armv7-a -mfloat-abi=softfp -mfpu=vfp"
  export CXXFLAGS="--sysroot=$ANDROID_SYSROOT -march=armv7-a -mfloat-abi=softfp -mfpu=vfp"

  export PKG_CONFIG_LIBDIR=$ANDROID_SYSROOT/lib

  Note that I'm not sure regarding the correct directory for
  PKG_CONFIG_LIBDIR. However in this example it was just important
  that it did not find the libraries on the host.

  Note that PKG_CONFIG_SYSROOT_DIR should possibly also have been
  set, but in this case this would force us to install libosmscout
  for its headers to be found because all paths in the *.pc would be
  prefixed with the variable content.

  Note that PKG_CONFIG_PATH should point to the various used libosmscout-*
  directories and to the directory of the Android-Qt package containing
  the *.pc files
  (under arch linux: /opt/android-qt5/5.3.0/lib/pkgconfig/)

* For Android version-less libraries have to get build (requirement of the
  device local shared library loader). Standard under Linux are versioned
  libraries. It is the task of the used libtool package to do platform
  dependend compiler/linker calls, however libtool currently does not have
  special handling for Android. Android is thus detected as Linux and
  this versioned libraries are build. You have to patch your local
  m4/libtool.m4 to get the special handling for Android. Apply the
  following patch:
  
  http://lists.gnu.org/archive/html/libtool-patches/2013-06/msg00002.html
  
  Note that autoconf may reinstall the official libtool.m4 if autogen.sh
  is called. You then have to reapply the patch.

* Now configure and compile the libraries using:
  ./configure --host=arm-linux-androideabi --with-sysroot=$ANDROID_SYSROOT --disable-openmp-support

  Note  that openmp seams to be not supported (I got crashes quickly) so
  disable it using the above configure option for configure scripts that
  test for it (libosmscout).

  Note that the pkg-config tool used is that from the build system, so
  availability of libs detected via pkg-config is not based on the host
  (target) system but on the build system.
  
* Under Android qmake ignores pkg-config calls (it assumes that evaluating
  pkg-config does not make sense while cross compiling). You have to ensure
  that pkg-config is used (and the libosmscout libraries found) by adding

  QT_CONFIG -= no-pkg-config

  to the OSMScout2 project file.
  
* Goto the OSMScout2 directory and call the qmake from the Android-Qt5 package
  to generate a makefile.
  (under arch linux: /opt/android-qt5/5.3.0/bin/qmake).

* Build OSMScout2 by calling make.

* Building the Android *.apk fro the sources

  We assume that the package will get build in the "android-pkg" sub directory
  (of the OSMScout2 directory).
  Any templates will be searched in the sub directory "android".

  We clean up the existing directory:
  
  rm -rf android-pkg
  
  Then we install the OSMScout application into the android-pkg directory:
  
  make install INSTALL_ROOT=android-pkg

  We then call the Qt androiddeployqt application:
  
  /opt/android-qt5/5.3.0/bin/androiddeployqt --input android-libOSMScout.so-deployment-settings.json --output android-pkg --android-platform android-16 --verbose --install
  
  In this case we use the *.json file generated by the build as information
  base, place the package into the "nadroid-pkg" directory, build for
  platform 16, output a number of details and finally install the package
  directly onto the device (you must have USB debugging on the mobile active
  and the mobile connected and detected vi USB).
  
  Since the path to the libosmscout libraries is already (hardcoded) in the
  project file, these dependend libraries will get automatically placed into
  the package.
  
  That's it.