Add NOTES.ANDROID.

Reviewed-by: NRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5613)

Configurations/15-android.conf

 #### Android...
 #
-# It takes *one* prior-set environment variable to make it work:
-#
-# ANDROID_NDK=/some/where/android-ndk-<ver>
-#
-# As well as PATH *adjusted* to cover ${CROSS_COMPILE}gcc and company.
-#
-# Note that it's different from original instructions that required to
-# set CROSS_SYSROOT [to $ANDROID_NDK/platforms/android-<api>/arch-<arch>]
-# and CROSS_COMPILE. CROSS_SYSROOT is still recognized [and even required
-# for some legacy targets], but if not set, it's detected and set to the
-# latest Android platform available with appointed NDK automatically. If
-# you need to target older platform, pass additional -D__ANDROID_API__=N
-# to Configure. For example, to compile for ICS on ARM with NDK 10d:
-#
-# ANDROID_NDK=/some/where/android-ndk-10d
-# PATH=$ANDROID_NDK/toolchains/arm-linux-androideabi-4.8/prebuild/linux-x86_64/bin:$PATH
-# [..]./Configure android-arm -D__ANDROID_API__=14
-#
-# One can engage clang by passing CC=clang to Configure. In such case
-# PATH needs even more adjustments to cover NDK's clang itself, as well
-# as unprefixed, yet target-specific ar and ranlib [or not, if you use
-# binutils-multiarch].
+# See NOTES.ANDROID for details. But don't miss platform-specific
+# comments below...
 
 {
     my $android_ndk = {};
@@ -53,7 +33,7 @@
                     }
                 }
 
-                # list available platforms [numerically]
+                # list available platforms (numerically)
                 my @platforms = sort { $a =~ m/-([0-9]+)$/; my $aa = $1;
                                        $b =~ m/-([0-9]+)$/; $aa <=> $1;
                                      } glob("$ndk/platforms/android-$api");
@@ -141,7 +121,7 @@ my %targets = (
         # ability to engage NEON is not constrained by ABI choice, nor
         # is your ability to call OpenSSL from your application code
         # compiled with floating-point ABI other than default 'soft'.
-        # [Latter thanks to __attribute__((pcs("aapcs"))) declaration.]
+        # (Latter thanks to __attribute__((pcs("aapcs"))) declaration.)
         # This means that choice of ARM libraries you provide in .apk
         # is driven by application needs. For example if application
         # itself benefits from NEON or is floating-point intensive, then
@@ -154,10 +134,11 @@ my %targets = (
         # in order to build "universal" binary and allow OpenSSL take
         # advantage of NEON when it's available.
         #
-        # Keep in mind that [just like with linux-armv4] we rely on
+        # Keep in mind that (just like with linux-armv4) we rely on
         # compiler defaults, which is not necessarily what you had
         # in mind, in which case you would have to pass additional
         # -march and/or -mfloat-abi flags. NDK defaults to armv5te.
+	# Some NDK versions reportedly require additional -latomic.
         #
         inherit_from     => [ "android", asm("armv4_asm") ],
         bn_ops           => add("RC4_CHAR"),
@@ -201,7 +182,7 @@ my %targets = (
     },
 
     ####################################################################
-    # Backward compatible targets, [might] requre $CROSS_SYSROOT
+    # Backward compatible targets, (might) requre $CROSS_SYSROOT
     #
     "android-armeabi" => {
         inherit_from     => [ "android-arm" ],

INSTALL

@@ -22,6 +22,7 @@
   * NOTES.VMS (OpenVMS)
   * NOTES.WIN (any supported Windows)
   * NOTES.DJGPP (DOS platform with DJGPP)
+  * NOTES.ANDROID (obviously Android [NDK])
 
  Notational conventions in this document
  ---------------------------------------

NOTES.ANDROID

+
+ NOTES FOR ANDROID PLATFORMS
+ ===========================
+
+ Requirement details
+ -------------------
+
+ Beside basic tools like perl and make you'll need to download the Android
+ NDK. It's available for Linux, Mac OS X and Windows, but only Linux
+ version was actually tested. There is no reason to believe that Mac OS X
+ wouldn't work. And as for Windows, it's unclear which "shell" would be
+ suitable, MSYS2 might have best chances. NDK version should play lesser
+ role, the goal is to support a range of most recent versions.
+
+ Configuration
+ -------------
+
+ Android is naturally cross-compiled target and you can't use ./config.
+ You have to use ./Configure and name your target explicitly; there are
+ android-arm, android-arm64, android-mips, android-mip64, android-x86
+ and android-x86_64. Do not pass --cross-compile-prefix (as you might
+ be tempted), as it will be "calculated" automatically based on chosen
+ platform. Though you still need to know the prefix to extend your PATH,
+ in order to invoke $(CROSS_COMPILE)gcc and company. (Configure will fail
+ and give you a hint if you get it wrong.) Apart from PATH adjustment
+ you need to set ANDROID_NDK environment to point at NDK directory
+ as /some/where/android-ndk-<ver>. NDK customarily supports multiple
+ Android API levels, e.g. android-14, android-21, etc. By default latest 
+ one available is chosen. If you need to target older platform, pass
+ additional -D__ANDROID_API__=N to Configure. N is numeric value of the
+ target platform version. For example, to compile for ICS on ARM with
+ NDK 10d:
+
+    ANDROID_NDK=/some/where/android-ndk-10d
+    PATH=$ANDROID_NDK/toolchains/arm-linux-androideabi-4.8/prebuild/linux-x86_64/bin:$PATH
+    ./Configure android-arm -D__ANDROID_API__=14
+
+ Caveat lector! Earlier OpenSSL versions relied on additional CROSS_SYSROOT
+ variable set to $ANDROID_NDK/platforms/android-<api>/arch-<arch> to
+ appoint headers-n-libraries' location. It's still recognized in order
+ to facilitate migration from older projects. However, since API level
+ appears in CROSS_SYSROOT value, passing -D__ANDROID_API__=N can be in
+ conflict, and mixing the two is therefore not supported. Migration to
+ CROSS_SYSROOT-less setup is recommended.
+
+ One can engage clang by passing CC=clang to Configure. In such case
+ PATH needs even more adjustments to cover NDK's clang itself, as well
+ as unprefixed, yet target-specific, ar and ranlib (or not, if you use
+ binutils-multiarch on your Linux).
+
+ Running tests (on Linux)
+ ------------------------
+
+ This is not actually supported. Notes are meant rather as inspiration.
+
+ Even though build output targets alien system, it's possible to execute
+ test suite on Linux system by employing qemu-user. The trick is static
+ linking. Pass -static to Configure, then edit generated Makefile and
+ remove occurrences of -ldl and -pie flags. You would also need to pick
+ API version that comes with usable static libraries, 42/2=21 used to
+ work. Once built, you should be able to
+
+    env EXE_SHELL=qemu-<arch> make test
+
+ If you need to pass additional flag to qemu, quotes are your friend, e.g.
+
+    env EXE_SHELL="qemu-mips64el -cpu MIPS64R6-generic" make test