[Mono.Android] Add Android API-Q preview binding (#2829)

Context: https://developer.android.com/preview/overview [^1]

Android Q Beta 1 has been released.  The API-Q Program Overview
[Timeline and updates][0] section suggests the following:

  * Beta 2 in early April
  * Beta 3 in early May
  * Beta 4 in early June.
    This contains the final APIs and official SDK.
  * Beta 5, 6, and final release sometime in Q3, 2019.

Add support for binding API-Q as API-29, with
`$(TargetFrameworkVersion)` v9.0.99.

Note: The Android SDK **Build-tools** package version 29-rc1 appears
to be busted, in that `apksigner.jar` generates invalid `.apk` files.
Our [PR build][1] had errors attempting to install `.apk` files:

        AndroidApkSigner:
          ApkSignerJar: …/android-toolchain/sdk/build-tools/29.0.0-rc1/lib/apksigner.jar
          ApkToSign: …/bin/TestRelease/Xamarin.Android.Locale_Tests-Signed.apk
          ManifestFile: obj/Release/android/AndroidManifest.xml
          AdditionalArguments: 
        java -jar …/android-toolchain/sdk/build-tools/29.0.0-rc1/lib/apksigner.jar sign --ks "…/.local/share/Xamarin/Mono for Android/debug.keystore" --ks-pass pass:android --ks-key-alias androiddebugkey --key-pass pass:android --min-sdk-version 16 --max-sdk-version 22  …/bin/TestRelease/Xamarin.Android.Locale_Tests-Signed.apk
	...
	  Executing: …/android-toolchain/sdk/platform-tools/adb -s emulator-5570  install "…/bin/TestRelease/Xamarin.Android.Locale_Tests-Signed.apk"
	…/build-tools/scripts/TestApks.targets(154,5): warning : adb: failed to install …/bin/TestRelease/Xamarin.Android.Locale_Tests-Signed.apk: Failure [INSTALL_PARSE_FAILED_NOT_APK: Failed to parse /data/app/vmdl242845261.tmp/base.apk]

Finally, remove `Animation` events from set~ method only after Q API.
Without this change, there was API compatibility breakage:

	<h3>Type Changed: Android.Views.Animations.Animation</h3>
	<p>Removed events:</p>
	<pre>
		<span class='removed removed-event breaking' data-is-breaking>public event System.EventHandler&lt;Animation.AnimationEndEventArgs&gt; AnimationEnd;</span>
		<span class='removed removed-event breaking' data-is-breaking>public event System.EventHandler&lt;Animation.AnimationRepeatEventArgs&gt; AnimationRepeat;</span>
		<span class='removed removed-event breaking' data-is-breaking>public event System.EventHandler&lt;Animation.AnimationStartEventArgs&gt; AnimationStart;</span>
	</pre>


[0]: https://developer.android.com/preview/overview#timeline
[1]: https://jenkins.mono-project.com/job/xamarin-android-pr-pipeline-release/151/

[^1]: No `archive.org` URL because one doesn't exist yet. :-(

Author: atsushieno

Configuration.props

@@ -26,9 +26,9 @@
     <AndroidLatestStablePlatformId Condition="'$(AndroidLatestStablePlatformId)' == ''">$(AndroidLatestStableApiLevel)</AndroidLatestStablePlatformId>
     <AndroidLatestStableFrameworkVersion Condition="'$(AndroidLatestStableFrameworkVersion)'==''">v9.0</AndroidLatestStableFrameworkVersion>
     <!-- *Latest* (possibly unstable) API level binding that we support; for informational purposes -->
-    <AndroidLatestApiLevel Condition="'$(AndroidLatestApiLevel)' == ''">28</AndroidLatestApiLevel>
-    <AndroidLatestPlatformId Condition=" '$(AndroidLatestPlatformId)' == '' ">28</AndroidLatestPlatformId>
-    <AndroidLatestFrameworkVersion Condition="'$(AndroidLatestFrameworkVersion)' == ''">v9.0</AndroidLatestFrameworkVersion>
+    <AndroidLatestApiLevel Condition="'$(AndroidLatestApiLevel)' == ''">29</AndroidLatestApiLevel>
+    <AndroidLatestPlatformId Condition=" '$(AndroidLatestPlatformId)' == '' ">Q</AndroidLatestPlatformId>
+    <AndroidLatestFrameworkVersion Condition="'$(AndroidLatestFrameworkVersion)' == ''">v9.0.99</AndroidLatestFrameworkVersion>
     <!-- The API level and TargetFrameworkVersion for the default Mono.Android.dll build -->
     <AndroidApiLevel Condition=" '$(AndroidApiLevel)' == '' ">$(AndroidLatestStableApiLevel)</AndroidApiLevel>
     <AndroidPlatformId Condition=" '$(AndroidPlatformId)' == '' ">$(AndroidLatestStablePlatformId)</AndroidPlatformId>

Documentation/workflow/HowToAddNewApiLevel.md

@@ -1,6 +1,23 @@
 
 # How to deal with new API Level
 
+
+## Quick Android Q API support workflow logs.
+
+- Make changes to Configuration.props
+- Add android-toolchain projitems
+- Run `make prepare` and `make` to first download platform-Q under `~/android-toolchain`
+- Generate android-Q.params.txt
+  - go to `external/Java.Interop/build-tools/xamarin-android-docimporter-ng`.
+  - add new API level to `generate.sh`
+  - run `nuget restore`, `make`, and `./generate.sh`. Take some rest (it takes a while).
+  - copy `android-*.params.txt` to `{xamarin-android topdir}/src/Mono.Android/Profiles/`.
+  - In `src/Mono.Android/Profiles/`, renamed `android-Q.params.txt` to `android-29.params.txt` as the later builds expect that.
+  - Make changes to `Configuration.props`, create `Configuration.Override.props` to set AndroidApiLevel etc.
+  - Make other changes to e.g. `build-tools/scripts/BuildEverything.mk`, `src/Mono.Android/Mono.Android.projitems`.
+  - run `make` on xamarin-android topdir. It results in various errors.
+  - Fix builds by making changes to `src/Mono.Android/metadata` and sources under `src/Mono.Android`.
+
 ## This documentation is incomplete
 
 In Xamarin ages, we used to have (more complete) API upgrade guide internally. But since then we switched to new xamarin-android repository which entirely changed the build system from Makefile to MSBuild solution, as well as the managed API for manipulating Android SDK, the old documentation almost does not make sense anymore. Even though I am writing this documentation, I don't know everything required (nor those who changed the build system didn't care about API upgrades).

build-tools/android-toolchain/android-toolchain.projitems

@@ -143,6 +143,10 @@
       <HostOS></HostOS>
       <DestDir>platforms\android-28</DestDir>
     </AndroidSdkItem>
+    <AndroidSdkItem Include="platform-Q_r01">
+      <HostOS></HostOS>
+      <DestDir>platforms\android-Q</DestDir>
+    </AndroidSdkItem>
     <AndroidSdkItem Include="docs-24_r01">
       <HostOS></HostOS>
       <DestDir>docs</DestDir>

build-tools/api-xml-adjuster/Makefile

@@ -17,7 +17,7 @@ API_XML_TOOL = $(BUILDBIN)/api-xml-adjuster.exe
 RUNTIME = mono --debug
 RUN_CLASS_PARSE = $(RUNTIME) $(CLASS_PARSE)
 RUN_API_XML_TOOL = $(RUNTIME) $(API_XML_TOOL)
-API_LEVELS = 10 15 16 17 18 19 20 21 22 23 24 25 26 27 28
+API_LEVELS = 10 15 16 17 18 19 20 21 22 23 24 25 26 27 28 Q
 
 XML_OUTPUT_DIR = .
 

build-tools/scripts/BuildEverything.mk

@@ -23,12 +23,12 @@ ZIP_OUTPUT            = $(ZIP_OUTPUT_BASENAME).$(ZIP_EXTENSION)
 ## The following values *must* use SPACE, **not** TAB, to separate values.
 
 # $(ALL_API_LEVELS) and $(ALL_FRAMEWORKS) must be kept in sync w/ each other
-ALL_API_LEVELS    = 1 2 3 4 5 6 7 8 9 10  11  12  13  14  15  16  17  18  19    20        21    22    23    24    25    26    27    28
+ALL_API_LEVELS    = 1 2 3 4 5 6 7 8 9 10  11  12  13  14  15  16  17  18  19    20        21    22    23    24    25    26    27    28	29
 # this was different from ALL_API_LEVELS when API Level 26 was "O". Same could happen in the future.
-ALL_PLATFORM_IDS  = 1 2 3 4 5 6 7 8 9 10  11  12  13  14  15  16  17  18  19    20        21    22    23    24    25    26    27    28
+ALL_PLATFORM_IDS  = 1 2 3 4 5 6 7 8 9 10  11  12  13  14  15  16  17  18  19    20        21    22    23    24    25    26    27    28	Q
 # supported api levels
-ALL_FRAMEWORKS    = _ _ _ _ _ _ _ _ _ _   _   _   _   _   _   _   _   _   v4.4  v4.4.87   v5.0  v5.1  v6.0  v7.0  v7.1  v8.0  v8.1  v9.0
-API_LEVELS        =                                                       19    20        21    22    23    24    25    26    27    28
+ALL_FRAMEWORKS    = _ _ _ _ _ _ _ _ _ _   _   _   _   _   _   _   _   _   v4.4  v4.4.87   v5.0  v5.1  v6.0  v7.0  v7.1  v8.0  v8.1  v9.0 v9.0.99
+API_LEVELS        =                                                       19    20        21    22    23    24    25    26    27    28	29
 STABLE_API_LEVELS =                                                       19    20        21    22    23    24    25    26    27    28
 
 ## The preceding values *must* use SPACE, **not** TAB, to separate values.

src/Mono.Android/Java.Lang/StringBuffer.cs

@@ -3,6 +3,9 @@
 // It is introduced since API 26 not because of new member in StringBuffer
 // but in AbstractStringBuilder which is nonpublic and affects the generated API.
 
+#if !ANDROID_29
+// However, AbstractStringBuilder has changed in Android Q and it does not seem to be required anymore (this rather blocks build).
+
 using System;
 
 namespace Java.Lang
@@ -17,3 +20,4 @@ public IAppendable Append (string s, int start, int end)
 }
 
 #endif
+#endif

src/Mono.Android/Java.Lang/StringBuilder.cs

@@ -3,6 +3,9 @@
 // It is introduced since API 26 not because of new member in StringBuffer
 // but in AbstractStringBuilder which is nonpublic and affects the generated API.
 
+#if !ANDROID_29
+// However, AbstractStringBuilder has changed in Android Q and it does not seem to be required anymore (this rather blocks build).  
+
 using System;
 
 namespace Java.Lang
@@ -17,3 +20,4 @@ public IAppendable Append (string s, int start, int end)
 }
 
 #endif
+#endif

src/Mono.Android/Mono.Android.projitems

@@ -145,6 +145,12 @@
       <Id>28</Id>
       <Stable>True</Stable>
     </AndroidApiInfo>
+    <AndroidApiInfo Include="v9.0.99">
+      <Name>Q</Name>
+      <Level>29</Level>
+      <Id>Q</Id>
+      <Stable>False</Stable>
+    </AndroidApiInfo>
   </ItemGroup>
 
 </Project>