Remove Support for Android NDKs before r18

To get rid of the hacky GCC support in platform_macros.GNU, ensure that
all the NDKs we support have >=C++11 by default, and to be able to
default to using lld as recommended by Google.

Also:

- Removed `ANDROID_ARCH` make variable.
- Replaced `ANDROID_ABI` with `android_abi` make variables to match
  other make variables, but keep `ANDROID_ABI` as an alias of
  `android_abi` for compatibility.
- Will no longer default to 32-bit ARM. `android_abi` or `ANDROID_ABI`
  are now required.
- Update ACE-INSTALL.html for all the changes so far

1 files changed, 47 insertions, 92 deletions

diff --git a/ACE/ACE-INSTALL.html b/ACE/ACE-INSTALL.html
index 13bcad42f95..779b16a2df4 100644
--- a/ACE/ACE-INSTALL.html
+++ b/ACE/ACE-INSTALL.html
@@ -1626,8 +1626,8 @@ symbols are necessary when you want to debug your code.</p>
 <h2><a name="android">Building and Installing ACE on Android</a></h2>
 
 <ul>
-  <li><a href="#android-toolchain">Generating a Toolchain</a></li>
-  <li><a href="#android-oldndks">Using Older NDKs</a></li>
+  <li><a href="#android-target">Choosing the Target</a></li>
+  <li><a href="#android-toolchain">Generating a Toolchain (Optional)</a></li>
   <li><a href="#android-building">Building</a></li>
   <li><a href="#android-install">Installing ACE on Android</a></li>
   <li><a href="#android-logging">Logging</a></li>
@@ -1637,13 +1637,16 @@ symbols are necessary when you want to debug your code.</p>
 <p>ACE can be built for Android by using the <a
 href="https://developer.android.com/ndk/">Android Native Development Kit
 (NDK)</a>. This is different than the standard way of writing Android
-applications in Java which run the on Android Runtime or the older Dalvik
-Virtual Machine. Applications built using the NDK are native Linux applications
-written in C or C++ specifically compiled to run on Android systems. In
-addition, applications built using the NDK have access to Android-specific APIs
-much like the ones available to Java-based Android applications.
+applications in Java which run the on the Android Runtime or the older Dalvik
+Virtual Machine. Applications and libraries built using the NDK are native
+Linux applications written in C or C++ specifically compiled to run on Android
+systems and libraries can be included in normal Android apps. In addition,
+applications and libraries built using the NDK have access to Android-specific
+APIs much like the ones available to Java-based Android applications.
 </p>
 
+<p><b>NOTE: ACE requires NDK r18 or later</b></p>
+
 <div class="boxed">
 <p><b>Windows Users:</b> These instructions are written for a Unix based
 platform like Linux, but can also be used on Windows. If you are using an
@@ -1658,11 +1661,17 @@ addition to the Windows version of the Android NDK, you will also need
 <a href="https://www.msys2.org">MSYS2 for Unix utilities that ACE needs</a>.
 </div>
 
-<h3><a name="android-toolchain">Generating a Toolchain</a></h3>
+After downloading the NDK, you will have to decide on what target you want to
+build for, which is covered in the next section, then decide if you want to
+build directly using the NDK or using
+<a href="#android-toolchain">a generated standalone toolchain</a>. Generating a
+toolchain is optional and only really makes sense if you're building for just
+one architecture/API level pair and don't need to keep the entire NDK around.
+
+<h3><a name="android-toolchain">Choosing the Target</a></h3>
 
-<p>To build ACE for Android you need to download the NDK and generate a
-toolchain for the specific Android target you want. The specific target is
-defined by two things:</p>
+<p>To build ACE for Android you need to know the specific Android target you
+want. The specific target is defined by two things:</p>
 
 <dl class="indent">
   <dt>- The minimal API level to target.</dt>
@@ -1677,14 +1686,14 @@ defined by two things:</p>
     although support for MIPS has been dropped from the NDK. <a
     href="https://developer.android.com/ndk/guides/abis">This is the official
     documentation on the ABIs</a>. These are the ABIs that ACE supports at the
-    time of writing and must be passed to ACE as <code>ANDROID_ABI</code>:
+    time of writing and must be passed to ACE as <code>android_abi</code>:
     <!-- Check to see if any architectures have been added or removed. If so
       update this list and the table below as well-->
-    <dl>
+    <dl id="android_abis">
       <dt><code>armeabi-v7a</code></dt>
-        <dd>32-bit ARM, The default ABI for both the NDK and ACE.</dd>
-      <dt><code>armeabi-v7a-with-neon</code></dt>
-        <dd><code>armeabi-v7a</code> with NEON extensions enabled.</dd>
+        <dd>32-bit ARM. Builds with NEON extensions enabled by default. Include
+        <code>android_neon := 0</code> in your <code>platform_macros.GNU</code>
+        if you want to support processors without NEON support.</dd>
       <dt><code>arm64-v8a</code></dt>
         <dd>64-bit ARM, Sometimes referred to as <code>aarch64</code>.</dd>
       <dt><code>x86</code></dt>
@@ -1695,15 +1704,16 @@ defined by two things:</p>
     <p><b>
       It should be noted that starting in August 2019, the Google Play
       Store will require new apps to have 64-bit libraries if they have native
-      libraries. 32-bit native libraries will still be supported but they must also
-      have 64-bit libraries. Look up any restrictions that may affect
-      apps you want to publish on the Play Store, including minimum API
-      level.
+      libraries. 32-bit native libraries will still be supported but apps must
+      also have 64-bit libraries. Look up any restrictions that may affect apps
+      you want to publish on the Play Store, including targeted API level
+      requirements.
     </b></p>
     </dd>
   </li>
 </dl>
 
+<h3><a name="android-toolchain">Generating a Toolchain (Optional)</a></h3>
 
 <p>To generate a toolchain, one use must use
 <code>build/tools/make_standalone_toolchain.py</code> in the NDK. A destination must be
@@ -1715,10 +1725,11 @@ toolchain targeting 32-bit ARM Android 7.0 "Nougat" (API Level 24) and later: </
 <p><code>$TOOLCHAIN/bin</code> must be in your <code>$PATH</code> when building ACE and
 applications using ACE.</p>
 
-<p>This table shows how the <code>ANDROID_ABI</code> variable and the <code>--arch</code> argument correlate:</p>
-<table class="indent">
+<p>This table shows how the <code>android_abi</code> variable and the
+<code>--arch</code> argument correlate:</p>
+<table class="indent" id="android_abi_toolchain_table">
   <tr>
-    <th><code>ANDROID_ABI</code></th>
+    <th><code>android_abi</code></th>
     <th><code>--arch</code></th>
   </tr>
   <tr>
@@ -1726,10 +1737,6 @@ applications using ACE.</p>
     <td><code>arm</code></td>
   </tr>
   <tr>
-    <td><code>armeabi-v7a-with-neon</code></td>
-    <td><code>arm</code></td>
-  </tr>
-  <tr>
     <td><code>arm64-v8a</code></td>
     <td><code>arm64</code></td>
   </tr>
@@ -1763,64 +1770,6 @@ utilities must be in <code>%PATH%</code> when cross compiling ACE. The default
 location for these would be <code>C:\msys64\usr\bin</code>.
 </div>
 
-<!-- Remove this section if these NDKs can be considered not supported anymore -->
-<h3><a name="android-oldndks">Using Older NDKs</a></h3>
-
-<p><b>Skip this section if using NDK r18 or later.</b></p>
-
-<p>
-It is <b>highly recommended</b> to use the latest NDK available assuming
-that it works with ACE. It is possible to use NDKs older than r18, but these
-have caveats:
-</p>
-<ul>
-  <li>
-    In NDK r16, a file called <code>ndk-version.h</code> was added that
-    contains the version of the NDK. If using an earlier NDK, you <b>must</b>
-    define the macros <code>__NDK_MAJOR__</code> and <code>__NDK_MINOR__</code>
-    in <code>ace/config.h</code> before
-    <code>#include "ace/config-android.h"</code>.
-    The scheme works like this:
-    <table class="indent" style="margin-top: .5em; margin-bottom: .5em;">
-      <tr>
-        <th>Revision</th>
-        <th><code>__NDK_MAJOR__</code></th>
-        <th><code>__NDK_MINOR__</code></th>
-      </tr>
-      <tr>
-        <td>r16</td>
-        <td>16</td>
-        <td>0</td>
-      </tr>
-      <tr>
-        <td>r16a</td>
-        <td>16</td>
-        <td>1</td>
-      </tr>
-      <tr>
-        <td>r16b</td>
-        <td>16</td>
-        <td>2</td>
-      </tr>
-    </table>
-  </li>
-  <li>
-    As of NDK r18, the only compiler that comes with the NDK is clang and by
-    default the build system assumes that clang is available and will use it.
-    However there was a transitional period between r12 and r17 where GCC and
-    clang both exist in the NDK. In some cases GCC should be used if linking
-    errors occur with these NDKs (For example missing references to
-    <code>stderr</code>). To let the build system decide between them, set
-    <code>android_force_clang:=0</code> in
-    <code>include/makeinclude/platform_macros.GNU</code> before including
-    <code>platform_android.GNU</code>. <b>This should be set for NDKs before r15.</b>
-  </li>
-  <li>
-    There are probably unknown conflicts, especially in the minor revisions
-    before the last minor revision of a NDK revision.
-  </li>
-</ul>
-
 <h3><a name="android-building">Building</a></h3>
 
 <ul>
@@ -1837,14 +1786,19 @@ have caveats:
     </div>
   </li>
   <li>Setup the Android build<ul>
-    <li>Create <code>ace/config.h</code>: <code>#include "ace/config-android.h"</code></li>
+    <li>Create <code>ace/config.h</code>: <code>#include "config-android.h"</code></li>
     <li>Create <code>include/makeinclude/platform_macros.GNU</code>:
       <ul>
         <li>
-          Set <code>ANDROID_ABI</code> to one of the options above. This
-          must match the toolchain <code>--arch</code> argument used according
-          to the table above.
+          Set <code>android_abi</code> to one of
+          <a href="#android_abis">the options above</a>.
+          If using a standalone toolchain this must match the
+          <code>--arch</code> argument used according
+          to <a href="#android_abi_toolchain_table">the table above</a>.
         </li>
+        <li>If using the NDK directly, set <code>android_ndk</code> to the
+          location of the extracted NDK and <code>android_api</code> to the API
+          level desired.</li>
         <li>Set options for debug and optimization options as desired.</li>
           <li>If you want to compile static, add <code>static_libs_only:=1</code></li>
           <li>Must include <code>include $(ACE_ROOT)/include/makeinclude/platform_android.GNU</code>.</li>
@@ -1857,10 +1811,11 @@ have caveats:
     </li>
     </li>
     <li>Generate makefiles (if necessary).</li>
-    <li>Build with GNU make. Make sure you have <code>$TOOLCHAIN/bin</code> in
-      your <code>$PATH</code>.
+    <li>Build with GNU make. If using a standalone toolchain, make sure you
+      have <code>$TOOLCHAIN/bin</code> in your <code>$PATH</code>.
       <div class="boxed indent"><p>
-        <b>Windows Users:</b> Make sure you have <code>%TOOLCHAIN%\bin</code>
+        <b>Windows Users:</b> If using a standalone toolchain,
+        Make sure you have <code>%TOOLCHAIN%\bin</code>
         and MSYS2's <code>bin</code> in your <code>%PATH%</code> when building.
         If you are cross compiling TAO you will also need a preprocessor for
         <code>tao_idl</code> available (See Windows note above).</p>