NOTES.ANDROID

   1
   2  NOTES FOR ANDROID PLATFORMS
   3  ===========================
   4
   5  Requirement details
   6  -------------------
   7
   8  Beside basic tools like perl and make you'll need to download the Android
   9  NDK. It's available for Linux, Mac OS X and Windows, but only Linux
  10  version was actually tested. There is no reason to believe that Mac OS X
  11  wouldn't work. And as for Windows, it's unclear which "shell" would be
  12  suitable, MSYS2 might have best chances. NDK version should play lesser
  13  role, the goal is to support a range of most recent versions.
  14
  15  Configuration
  16  -------------
  17
  18  Android is a cross-compiled target and you can't rely on ./Configure
  19  to find out the configuration target for you.  You have to name your
  20  target explicitly; there are android-arm, android-arm64, android-mips,
  21  android-mip64, android-x86 and android-x86_64 (*MIPS targets are no
  22  longer supported with NDK R20+).
  23
  24  Do not pass --cross-compile-prefix (as you might be tempted), as it
  25  will be "calculated" automatically based on chosen platform. However,
  26  you still need to know the prefix to extend your PATH, in order to
  27  invoke $(CROSS_COMPILE)clang [*gcc on NDK 19 and lower] and company.
  28  (Configure will fail and give you a hint if you get it wrong.)
  29
  30  Apart from PATH adjustment you need to set ANDROID_NDK_ROOT environment
  31  to point at the NDK directory. If you're using a side-by-side NDK the path
  32  will look something like /some/where/android-sdk/ndk/<ver>, and for a
  33  standalone NDK the path will be something like /some/where/android-ndk-<ver>.
  34  Both variables are significant at both configuration and compilation times.
  35  The NDK customarily supports multiple Android API levels, e.g. android-14,
  36  android-21, etc. By default latest API level is chosen. If you need to
  37  target an older platform pass the argument -D__ANDROID_API__=N to Configure,
  38  with N being the numerical value of the target platform version. For example,
  39  to compile for Android 10 arm64 with a side-by-side NDK r20.0.5594570
  40
  41     export ANDROID_NDK_ROOT=/home/whoever/Android/android-sdk/ndk/20.0.5594570
  42     PATH=$ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/bin:$ANDROID_NDK_ROOT/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/bin:$PATH
  43     ./Configure android-arm64 -D__ANDROID_API__=29
  44     make
  45
  46  Older versions of the NDK have GCC under their common prebuilt tools
  47  directory, so the bin path will be slightly different. EG: to compile
  48  for ICS on ARM with NDK 10d:
  49
  50     export ANDROID_NDK_ROOT=/some/where/android-ndk-10d
  51     PATH=$ANDROID_NDK_ROOT/toolchains/arm-linux-androideabi-4.8/prebuilt/linux-x86_64/bin:$PATH
  52     ./Configure android-arm -D__ANDROID_API__=14
  53     make
  54
  55  Caveat lector! Earlier OpenSSL versions relied on additional CROSS_SYSROOT
  56  variable set to $ANDROID_NDK_ROOT/platforms/android-<api>/arch-<arch> to
  57  appoint headers-n-libraries' location. It's still recognized in order
  58  to facilitate migration from older projects. However, since API level
  59  appears in CROSS_SYSROOT value, passing -D__ANDROID_API__=N can be in
  60  conflict, and mixing the two is therefore not supported. Migration to
  61  CROSS_SYSROOT-less setup is recommended.
  62
  63  One can engage clang by adjusting PATH to cover same NDK's clang. Just
  64  keep in mind that if you miss it, Configure will try to use gcc...
  65  Also, PATH would need even further adjustment to cover unprefixed, yet
  66  target-specific, ar and ranlib. It's possible that you don't need to
  67  bother, if binutils-multiarch is installed on your Linux system.
  68
  69  Another option is to create so called "standalone toolchain" tailored
  70  for single specific platform including Android API level, and assign its
  71  location to ANDROID_NDK_ROOT. In such case you have to pass matching
  72  target name to Configure and shouldn't use -D__ANDROID_API__=N. PATH
  73  adjustment becomes simpler, $ANDROID_NDK_ROOT/bin:$PATH suffices.
  74
  75  Running tests (on Linux)
  76  ------------------------
  77
  78  This is not actually supported. Notes are meant rather as inspiration.
  79
  80  Even though build output targets alien system, it's possible to execute
  81  test suite on Linux system by employing qemu-user. The trick is static
  82  linking. Pass -static to Configure, then edit generated Makefile and
  83  remove occurrences of -ldl and -pie flags. You would also need to pick
  84  API version that comes with usable static libraries, 42/2=21 used to
  85  work. Once built, you should be able to
  86
  87     env EXE_SHELL=qemu-<arch> make test
  88
  89  If you need to pass additional flag to qemu, quotes are your friend, e.g.
  90
  91     env EXE_SHELL="qemu-mips64el -cpu MIPS64R6-generic" make test