Add NOTES.ANDROID.
[openssl.git] / 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 naturally cross-compiled target and you can't use ./config.
19  You have to use ./Configure and name your target explicitly; there are
20  android-arm, android-arm64, android-mips, android-mip64, android-x86
21  and android-x86_64. Do not pass --cross-compile-prefix (as you might
22  be tempted), as it will be "calculated" automatically based on chosen
23  platform. Though you still need to know the prefix to extend your PATH,
24  in order to invoke $(CROSS_COMPILE)gcc and company. (Configure will fail
25  and give you a hint if you get it wrong.) Apart from PATH adjustment
26  you need to set ANDROID_NDK environment to point at NDK directory
27  as /some/where/android-ndk-<ver>. NDK customarily supports multiple
28  Android API levels, e.g. android-14, android-21, etc. By default latest 
29  one available is chosen. If you need to target older platform, pass
30  additional -D__ANDROID_API__=N to Configure. N is numeric value of the
31  target platform version. For example, to compile for ICS on ARM with
32  NDK 10d:
33
34     ANDROID_NDK=/some/where/android-ndk-10d
35     PATH=$ANDROID_NDK/toolchains/arm-linux-androideabi-4.8/prebuild/linux-x86_64/bin:$PATH
36     ./Configure android-arm -D__ANDROID_API__=14
37
38  Caveat lector! Earlier OpenSSL versions relied on additional CROSS_SYSROOT
39  variable set to $ANDROID_NDK/platforms/android-<api>/arch-<arch> to
40  appoint headers-n-libraries' location. It's still recognized in order
41  to facilitate migration from older projects. However, since API level
42  appears in CROSS_SYSROOT value, passing -D__ANDROID_API__=N can be in
43  conflict, and mixing the two is therefore not supported. Migration to
44  CROSS_SYSROOT-less setup is recommended.
45
46  One can engage clang by passing CC=clang to Configure. In such case
47  PATH needs even more adjustments to cover NDK's clang itself, as well
48  as unprefixed, yet target-specific, ar and ranlib (or not, if you use
49  binutils-multiarch on your Linux).
50
51  Running tests (on Linux)
52  ------------------------
53
54  This is not actually supported. Notes are meant rather as inspiration.
55
56  Even though build output targets alien system, it's possible to execute
57  test suite on Linux system by employing qemu-user. The trick is static
58  linking. Pass -static to Configure, then edit generated Makefile and
59  remove occurrences of -ldl and -pie flags. You would also need to pick
60  API version that comes with usable static libraries, 42/2=21 used to
61  work. Once built, you should be able to
62
63     env EXE_SHELL=qemu-<arch> make test
64
65  If you need to pass additional flag to qemu, quotes are your friend, e.g.
66
67     env EXE_SHELL="qemu-mips64el -cpu MIPS64R6-generic" make test