[Mono.Android] Add Android API-P preview binding (#1380)

Context: https://web.archive.org/web/20180311204050/https://developer.android.com/preview/features.html

Android P Developer Preview (DP) 1 has been released.
[The Android P Developer Preview Timeline][timeline] has DP2 in May,
DP3 with final APIs in June, and final release in Q3 2018.

Add support for binding API-P as API-28, `$(TargetFrameworkVersion)` v8.1.99.

Configuration.props

@@ -13,12 +13,18 @@
   />
   <PropertyGroup>
     <ProductVersion>8.3.99</ProductVersion>
-    <!-- *Latest* API level binding that we support; used when building src/Xamarin.Android.Build.Tasks -->
-    <AndroidLatestApiLevel Condition="'$(AndroidLatestApiLevel)' == ''">27</AndroidLatestApiLevel>
-    <AndroidLatestFrameworkVersion Condition="'$(AndroidLatestFrameworkVersion)' == ''">v8.1</AndroidLatestFrameworkVersion>
+    <!-- *Latest* *stable* API level binding that we support; used when building src/Xamarin.Android.Build.Tasks -->
+    <AndroidLatestStableApiLevel Condition="'$(AndroidLatestStableApiLevel)' == ''">27</AndroidLatestStableApiLevel>
+    <AndroidLatestStablePlatformId Condition="'$(AndroidLatestStablePlatformId)' == ''">$(AndroidLatestStableApiLevel)</AndroidLatestStablePlatformId>
+    <AndroidLatestStableFrameworkVersion Condition="'$(AndroidLatestStableFrameworkVersion)'==''">v8.1</AndroidLatestStableFrameworkVersion>
+    <!-- *Latest* (possibly unstable) API level binding that we support; used when building src/Xamarin.Android.Build.Tasks -->
+    <AndroidLatestApiLevel Condition="'$(AndroidLatestApiLevel)' == ''">28</AndroidLatestApiLevel>
+    <AndroidLatestPlatformId Condition=" '$(AndroidLatestPlatformId)' == '' ">P</AndroidLatestPlatformId>
+    <AndroidLatestFrameworkVersion Condition="'$(AndroidLatestFrameworkVersion)' == ''">v8.1.99</AndroidLatestFrameworkVersion>
     <!-- The API level and TargetFrameworkVersion for the default Mono.Android.dll build -->
-    <AndroidApiLevel Condition=" '$(AndroidApiLevel)' == '' ">$(AndroidLatestApiLevel)</AndroidApiLevel>
-    <AndroidFrameworkVersion Condition=" '$(AndroidFrameworkVersion)' == '' ">$(AndroidLatestFrameworkVersion)</AndroidFrameworkVersion>
+    <AndroidApiLevel Condition=" '$(AndroidApiLevel)' == '' ">$(AndroidLatestStableApiLevel)</AndroidApiLevel>
+    <AndroidPlatformId Condition=" '$(AndroidPlatformId)' == '' ">$(AndroidLatestStablePlatformId)</AndroidPlatformId>
+    <AndroidFrameworkVersion Condition=" '$(AndroidFrameworkVersion)' == '' ">$(AndroidLatestStableFrameworkVersion)</AndroidFrameworkVersion>
   </PropertyGroup>
   <PropertyGroup>
     <AutoProvision Condition=" '$(AutoProvision)' == '' ">False</AutoProvision>
@@ -39,7 +45,6 @@
     <ManagedRuntimeArgs Condition=" '$(ManagedRuntimeArgs)' == '' And '$(ManagedRuntime)' == 'mono' ">--debug=casts</ManagedRuntimeArgs>
     <MonoSgenBridgeVersion Condition=" '$(MonoSgenBridgeVersion)' == '' ">5</MonoSgenBridgeVersion>
     <HOME Condition=" '$(HOME)' == '' ">$(USERPROFILE)</HOME>
-    <AndroidPlatformId Condition=" '$(AndroidPlatformId)' == '' ">$(AndroidApiLevel)</AndroidPlatformId>
     <AndroidPreviousFrameworkVersion Condition=" '$(AndroidPreviousFrameworkVersion)' == '' ">v1.0</AndroidPreviousFrameworkVersion>
     <AndroidToolchainCacheDirectory Condition=" '$(AndroidToolchainCacheDirectory)' == '' ">$(HOME)\android-archives</AndroidToolchainCacheDirectory>
     <AndroidToolchainDirectory Condition=" '$(AndroidToolchainDirectory)' == '' ">$(HOME)\android-toolchain</AndroidToolchainDirectory>
@@ -68,8 +73,8 @@
     <AllSupported32BitTargetAndroidAbis>armeabi;armeabi-v7a;x86</AllSupported32BitTargetAndroidAbis>
     <AllSupported64BitTargetAndroidAbis>arm64-v8a;x86_64</AllSupported64BitTargetAndroidAbis>
     <AllSupportedTargetAndroidAbis>$(AllSupported32BitTargetAndroidAbis);$(AllSupported64BitTargetAndroidAbis)</AllSupportedTargetAndroidAbis>
-    <XABuildToolsVersion>27.0.3</XABuildToolsVersion>
-    <XABuildToolsFolder Condition="'$(XABuildToolsFolder)' == ''">27.0.3</XABuildToolsFolder>
+    <XABuildToolsVersion>28-rc1</XABuildToolsVersion>
+    <XABuildToolsFolder Condition="'$(XABuildToolsFolder)' == ''">28.0.0-rc1</XABuildToolsFolder>
     <XAIntegratedTests Condition="'$(XAIntegratedTests)' == ''">False</XAIntegratedTests>
     <PathSeparator>$([System.IO.Path]::PathSeparator)</PathSeparator>
     <TestsAotName Condition=" '$(AotAssemblies)' == 'true' ">-Aot</TestsAotName>

Documentation/building/configuration.md

@@ -31,6 +31,39 @@ Overridable MSBuild properties include:
     version which corresponds to `$(AndroidApiLevel)`. This is *usually* the
     Android version number with a leading `v`, e.g. `v4.0.3` for API-15.
 
+  * `$(AndroidLatestStableApiLevel)`: The highest/latest Android API level that
+    has a stable API. The `src/Xamarin.Android.Build.Tasks` build uses this
+    value to reference files built within `src/Mono.Android`.
+
+    This should be consistent with `$(AndroidLatestStableFrameworkVersion)` and
+    `$(AndroidLatestStablePlatformId)`.
+
+    This should only be updated when a new API level is declared stable.
+
+  * `$(AndroidLatestStableFrameworkVersion)`: The highest/latest Xamarin.Android
+    `$(TargetFrameworkVersion)` value which has a stable API.
+    The `src/Xamarin.Android.Build.Tasks` build uses this value to reference
+    files built within `src/Mono.Android`.
+
+    This should be consistent with `$(AndroidLatestStableApiLevel)` and
+    `$(AndroidLatestStablePlatformId)`.
+
+    This should only be updated when a new API level is declared stable.
+
+  * `$(AndroidLatestStablePlatformId)`: The highest/latest Android platform ID
+    which has a stable API.
+    The `src/Xamarin.Android.Build.Tasks` build uses this value to reference
+    files built within `src/Mono.Android`.
+
+    This should be consistent with `$(AndroidLatestStableApiLevel)` and
+    `$(AndroidLatestStableFrameworkVersion)`.
+
+    This should only be updated when a new API level is declared stable.
+
+  * `$(AndroidPlatformId)`: The "Platform ID" for the `android.jar` to use when
+    building `src/Mono.Android`. This is usually the same value as
+    `$(AndroidApiLevel)`, but may differ with Android Preview releases.
+
   * `$(AndroidSupportedHostJitAbis)`: The Android ABIs for which to build a
     host JIT *and* Xamarin.Android base class libraries (`mscorlib.dll`/etc.).
     The "host JIT" is used e.g. with the Xamarin Studio Designer, to render

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

@@ -121,6 +121,10 @@
       <HostOS></HostOS>
       <DestDir>platforms\android-27</DestDir>
     </AndroidSdkItem>
+    <AndroidSdkItem Include="platform-P_r01.zip">
+      <HostOS></HostOS>
+      <DestDir>platforms\android-P</DestDir>
+    </AndroidSdkItem>
     <AndroidSdkItem Include="docs-24_r01.zip">
       <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
+API_LEVELS = 10 15 16 17 18 19 20 21 22 23 24 25 26 27 P
 
 XML_OUTPUT_DIR = .
 

build-tools/api-xml-adjuster/api-xml-adjuster.targets

@@ -25,7 +25,7 @@
     <MakeDir Directories="$(_OutputPath)api" />
     <Exec
         Condition="Exists('$(_TopDir)\src\Mono.Android\Profiles\api-%(ApiFileDefinition.Level).params.txt')"
-        Command="$(ManagedRuntime) $(ClassParse) $(AndroidSdkDirectory)\platforms\android-%(ApiFileDefinition.Level)\android.jar -platform=%(ApiFileDefinition.Level) -parameter-names=&quot;%(ApiFileDefinition.ParameterDescription)&quot; -o=&quot;%(ApiFileDefinition.ClassParseXml)&quot;"
+        Command="$(ManagedRuntime) $(ClassParse) $(AndroidSdkDirectory)\platforms\android-%(ApiFileDefinition.Id)\android.jar -platform=%(ApiFileDefinition.Level) -parameter-names=&quot;%(ApiFileDefinition.ParameterDescription)&quot; -o=&quot;%(ApiFileDefinition.ClassParseXml)&quot;"
     />
   </Target>
   <Target Name="_AdjustApiXml"

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
+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
 # 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
+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  P
 # supported api levels
-ALL_FRAMEWORKS    = _ _ _ _ _ _ _ _ _ v2.3  _   _   _   _   v4.0.3  v4.1  v4.2  v4.3  v4.4  v4.4.87   v5.0  v5.1  v6.0  v7.0  v7.1  v8.0  v8.1
-API_LEVELS        =                   10                    15      16    17    18    19    20        21    22    23    24    25    26  27
+ALL_FRAMEWORKS    = _ _ _ _ _ _ _ _ _ v2.3  _   _   _   _   v4.0.3  v4.1  v4.2  v4.3  v4.4  v4.4.87   v5.0  v5.1  v6.0  v7.0  v7.1  v8.0  v8.1  v8.1.99
+API_LEVELS        =                   10                    15      16    17    18    19    20        21    22    23    24    25    26  27  28
 STABLE_API_LEVELS =                   10                    15      16    17    18    19    20        21    22    23    24    25    26
 
 ## The preceding values *must* use SPACE, **not** TAB, to separate values.
@@ -118,14 +118,14 @@ framework-assemblies:
 		$(_SLN_BUILD) $(MSBUILD_FLAGS) src/Xamarin.Android.NUnitLite/Xamarin.Android.NUnitLite.csproj /p:Configuration=$(conf) $(_MSBUILD_ARGS) \
 			/p:AndroidApiLevel=$(firstword $(API_LEVELS)) /p:AndroidPlatformId=$(word $(firstword $(API_LEVELS)), $(ALL_PLATFORM_IDS)) \
 			/p:AndroidFrameworkVersion=$(firstword $(FRAMEWORKS)) || exit 1; )
-	_latest_framework=$$($(MSBUILD) /p:DoNotLoadOSProperties=True /nologo /v:minimal /t:GetAndroidLatestFrameworkVersion build-tools/scripts/Info.targets | tr -d '[[:space:]]') ; \
+	_latest_stable_framework=$$($(MSBUILD) /p:DoNotLoadOSProperties=True /nologo /v:minimal /t:GetAndroidLatestStableFrameworkVersion build-tools/scripts/Info.targets | tr -d '[[:space:]]') ; \
 	$(foreach conf, $(CONFIGURATIONS), \
-		rm -f "bin/$(conf)/lib/xamarin.android/xbuild-frameworks/MonoAndroid/$$_latest_framework"/Mono.Android.Export.* ; \
+		rm -f "bin/$(conf)/lib/xamarin.android/xbuild-frameworks/MonoAndroid/$$_latest_stable_framework"/Mono.Android.Export.* ; \
 		$(_SLN_BUILD) $(MSBUILD_FLAGS) src/Mono.Android.Export/Mono.Android.Export.csproj /p:Configuration=$(conf) $(_MSBUILD_ARGS) \
 			/p:AndroidApiLevel=$(firstword $(API_LEVELS)) /p:AndroidPlatformId=$(word $(firstword $(API_LEVELS)), $(ALL_PLATFORM_IDS)) \
 			/p:AndroidFrameworkVersion=$(firstword $(FRAMEWORKS)) || exit 1; ) \
 	$(foreach conf, $(CONFIGURATIONS), \
-		rm -f "bin/$(conf)/lib/xamarin.android/xbuild-frameworks/MonoAndroid/$$_latest_framework"/OpenTK-1.0.* ; \
+		rm -f "bin/$(conf)/lib/xamarin.android/xbuild-frameworks/MonoAndroid/$$_latest_stable_framework"/OpenTK-1.0.* ; \
 		$(_SLN_BUILD) $(MSBUILD_FLAGS) src/OpenTK-1.0/OpenTK.csproj /p:Configuration=$(conf) $(_MSBUILD_ARGS) \
 			/p:AndroidApiLevel=$(firstword $(API_LEVELS)) /p:AndroidPlatformId=$(word $(firstword $(API_LEVELS)), $(ALL_PLATFORM_IDS)) \
 			/p:AndroidFrameworkVersion=$(firstword $(FRAMEWORKS)) || exit 1; )

build-tools/scripts/Info.targets

@@ -7,9 +7,9 @@
         Importance="High"
     />
   </Target>
-  <Target Name="GetAndroidLatestFrameworkVersion">
+  <Target Name="GetAndroidLatestStableFrameworkVersion">
     <Message
-        Text="$(AndroidLatestFrameworkVersion)"
+        Text="$(AndroidLatestStableFrameworkVersion)"
         Importance="High"
     />
   </Target>

src/Mono.Android/Mono.Android.projitems

@@ -139,5 +139,11 @@
       <Id>27</Id>
       <Stable>True</Stable>
     </AndroidApiInfo>
+    <AndroidApiInfo Include="v8.1.99">
+      <Name>P Preview UNSTABLE</Name>
+      <Level>28</Level>
+      <Id>P</Id>
+      <Stable>False</Stable>
+    </AndroidApiInfo>
   </ItemGroup>
 </Project>

src/Mono.Android/Mono.Android.targets

@@ -131,7 +131,7 @@
   </Target>
   <Target Name="_GenerateAndroidApiInfo"
       BeforeTargets="_GenerateFrameworkList"
-      Inputs="$(MSBuildProjectFullPath)"
+      Inputs="$(MSBuildProjectFullPath);$(MSBuildThisFileDirectory)Mono.Android.projitems"
       Outputs="$(OutputPath)AndroidApiInfo.xml">
    <MakeDir Directories="$(OutputPath)" />
    <ItemGroup>