[Mono.Android] Use 'merge.SourceFile' to set 'ApiSince'. #4671
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jpobst
force-pushed
the
api-since
branch
6 times, most recently
from
94fe2db to
1f4ddf6
Compare
jonpryor
pushed a commit
that referenced
this pull request
May 15, 2020
Context: #4012 (comment) Context: #4012 (comment) Context: dotnet/java-interop@005e273 Context: a348617 Changes: dotnet/java-interop@e599781...d6024f1 * dotnet/java-interop@d6024f1: [generator] Use //*/@api-since for RegisterAttribute.ApiSince (#644) * dotnet/java-interop@3968236: [generator] slnf file should use relative path. (#641) * dotnet/java-interop@67b6f70: [CI] Add a .NET Core Windows lane. (#640) When `generator --apiversions=FILE` is used, then the `RegisterAttribute.ApiSince` field will be set to contain the API version which introduced a method, e.g. when building `src/Mono.Android`: $ generator.exe --apiversions=$HOME/android-toolchain/sdk/platform-tools/api/api-versions.xml … and `$HOME/android-toolchain/sdk/platform-tools/api/api-versions.xml` contains: <class name="android/view/inspector/IntFlagMapping" since="29"> <extends name="java/lang/Object"/> then `generator` will emit: [Register ("android/view/inspector/IntFlagMapping", DoNotGenerateAcw=true, ApiSince=29)] partial class IntFlagMapping {} Unfortunately, we have found that Google's support of this file isn't guaranteed. Sometimes it is missing, other times it changes in unexpected ways; either can causes `ApiCompat` breakage when building `Mono.Android`, resulting in the removal or modification of the `RegisterAttribute.ApiSince` values. In short, we have lost faith in `api-versions.xml`. dotnet/java-interop@186174c updates `generator` so that *instead of* using an `api-versions.xml` file to provide `RegisterAttribute.ApiSince` values, those values can instead come from `//*/@api-since` attributes. The `//*/@api-since` attributes in turn can come from `src/Mono.Android/metadata`, based on the `//*/@merge.SourceFile` attribute values that `build-tools/api-merge` emits (a073d99). This data is computed directly from the `android.jar` files, and should always be updated and (reasonably) correct. ~~ Notable differences ~~ Our current method provides data for API levels that we do not use for `api-merge`, such as 2, 4, 11, and 14. However we feel it is ok to "lose" this data, as it isn't really useful to our users. That is, if the minimum Xamarin.Android can target is API-21 (a648981), it is not useful to know that an API was added in API-9, since there is no way to target an API level where the member is not available. As such, we are not collecting data for API levels 21 or below, and all members added in any of those levels are considered to "always" have been available, with no `RegisterAttribute.ApiSince` value. ~~ ApiCompat ~~ This change creates a significant amount of API "breakages" where `RegisterAttribute.ApiSince` is either getting added or removed. Rather than add an additional 25K lines to `acceptable-breakages`, we are updating the reference assembly. [Elsewhere][0] is a list of the `ApiSince` info that changed as a result, for reference. There are no non-`ApiSince` changes. * ~12.3K members previously had no `ApiSince` and now have `ApiSince=22-29`. * ~12.1K members previously had `ApiSince=1-21` and now have no `ApiSince` value. * ~200 related fields changed from `28` to `29`, this seems to be correct from looking at the source files. A snippet of the file: System.String Android.Service.Carrier.CarrierMessagingService.ServiceInterface - 0 => 22 Android.Service.Carrier.CarrierMessagingService..ctor() - 0 => 22 Android.Service.Carrier.CarrierMessagingService.OnBind(Android.Content.Intent) - 0 => 22 Android.Service.Carrier.CarrierMessagingService.OnDownloadMms(Android.Net.Uri, System.Int32, Android.Net.Uri, Android.Service.Carrier.CarrierMessagingService.IResultCallback) - 0 => 22 … Finally, ignore the attribute `T:System.Diagnostics.DebuggerStepThroughAttribute`, which seems to be generated in some versions of Roslyn when using an `async Task` method. My local compiler (VS2019 16.5) generates it but apparently the version on the Mac agents does not. [0]: https://github.com/xamarin/xamarin-android/files/4616691/api-compat-parsed.txt
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Today we populate bound members with
ApiSinceinfo in their[Register]attribute. This denotes which platform level the api was added in, allowing the IDE to provide correct cues of which apis are available based on which platform a project targets.This information is provided via some xml files that Google provides with each platform sdk. Unfortunately these files are not always provided, are not always updated, or not always correct. This leads to issues where we are missing information, or updating platform sdks causes "api breakage" because the info changes.
We generate equivalent data via our
api-mergeprocess that we will now use to populateApiSinceinstead of the Google-provided files. This data is computed directly from the variousandroid.jarfiles, so it should always be updated and correct.Notable differences
Our current method provides data for API levels that we do not use for
api-merge, such as 2, 4, 11, 14. However we feel it is ok to lose this data, as it isn't really useful to our users. That is, if the minimum Xamarin.Android can target is API-21, it is not useful to know that an API was added in API-9, since there is no way to target an API level where the member is not available.As such, we are not collecting data for API levels 21 or below, and all members added in any of those levels are considered to "always" have been available. (No
ApiSince.)ApiCompat
This change creates a significant amount of API "breakages" where
ApiSinceis either getting added or removed. Rather than add an additional 25K lines toacceptable-breakages, we are updating the reference assembly.Attached is a file describing the
ApiSinceinfo that changed as a result of this for reference. There are no non-ApiSincechanges.~12.3K members previously had no
ApiSinceand now haveApiSince=22-29.~12.1K members previously had
ApiSince=1-21and now have noApiSince.~200 related fields changed from
28to29, this seems to be correct from looking at the source files.api-compat-parsed.txt
Also ignored attribute
T:System.Diagnostics.DebuggerStepThroughAttributewhich seems to be generated in some versions of Roslyn when using anasync Taskmethod. My local compiler (VS2019 16.5) generates it but apparently the version on the Mac agents does not.