Skip to content

Conversation

@jonpryor
Copy link
Contributor

@jonpryor jonpryor commented Jul 26, 2018

Context: dotnet/android#1998 (comment)
Context: https://github.com/xamarin/monodroid/commit/2c515356d9a671f729aff2e81c4c2f6184749722

Long ago, generator was written to consume API XML descriptions
provided by Google. This approach worked reasonably well until
Honeycomb, at which point Google didn't provide an XML API description
when the API-H android.jar was released.

The fix was jar2xml, which used Java Reflection around android.jar
to generate a similar API XML description which generator could use.

jar2xml in turn had its own share of problems, which resulted in
class-parse, which had a different share of problems. :-)

The original hope was that generator could directly use
class-parse output. Turns out, it wasn't that easy, hence
Xamarin.Android.Tools.ApiXmlAdjuster, which took class-parse
output and "munged" it into something resembling jar2xml output
(e.g. with respect to whether method overrides were included).

However, before Xamarin.Android.Tools.ApiXmlAdjuster existed, I
tried to get generator to consume class-parse output directly, and
in that spirit xamarin/monodroid@2c515356 updated generator to skip
processing of synthetic methods:

Don't emit synthetic methods, as this results in "duplicate" methods
-- one for the "real" method, one for the synthetic method.

However, the scenario monodroid@2c515356 attempted to address --
direct support for class-parse output -- is not something that has
ever been used, or been tested, or even worked.

Thus, the special-casing of synthetic methods is effectively dead
code, all the more so because Xamarin.Android.Tools.ApiXmlAdjuster
never emitted the //method/@synthetic attribute in the first place,
so generators special-casing of synthetic methods was never hit.

...until 0881acc, which updated
Xamarin.Android.Tools.ApiXmlAdjuster to include and copy over all
source attributes, including //method/@synthetic.

NOW generator began to see methods with
//method[@synthetic='true'], and skip them.

The resulting code compiled, but had ABI breakage.

Remove the special-casing logic for synthetic methods from
generator. monodroid@2c515356 never supported direct consumption
of class-parse output by generator, meaning such an effort will
require more work anyway, and removing synthetic special-casing from
generator will allow it to consume post-0881accd
Xamarin.Android.Tools.ApiXmlAdjuster output without breaking things.

Context: dotnet/android#1998 (comment)
Context: https://github.com/xamarin/monodroid/commit/2c515356d9a671f729aff2e81c4c2f6184749722

Long ago, `generator` was written to consume API XML descriptions
provided by Google.  This approach worked reasonably well until
Honeycomb, at which point Google didn't provide an XML API description
when the API-H `android.jar` was released.

The fix was `jar2xml`, which used Java Reflection around `android.jar`
to generate a similar API XML description which `generator` could use.

`jar2xml` in turn had its own share of problems, which resulted in
`class-parse`, which had a *different* share of problems. :-)

The original hope was that `generator` could directly use
`class-parse` output.  Turns out, it wasn't that easy, hence
`Xamarin.Android.Tools.ApiXmlAdjuster`, which took `class-parse`
output and "munged" it into something resembling `jar2xml` output
(e.g. with respect to whether method overrides were included).

However, *before* `Xamarin.Android.Tools.ApiXmlAdjuster` existed, I
tried to get `generator` to consume `class-parse` output directly, and
in that spirit monodroid@2c515356 updated `generator` to *skip*
processing of `synthetic` methods:

> Don't emit `synthetic` methods, as this results in "duplicate" methods
> -- one for the "real" method, one for the synthetic method.

However, the scenario monodroid@2c515356 attempted to address --
direct support for `class-parse` output -- is not something that has
ever been used, or been tested, or even *worked*.

Thus, the special-casing of `synthetic` methods is effectively dead
code, all the more so because `Xamarin.Android.Tools.ApiXmlAdjuster`
never emitted the `//method/@synthetic` attribute in the first place,
so `generator`s special-casing of `synthetic` methods was never hit.

...until 0881acc, which updated
`Xamarin.Android.Tools.ApiXmlAdjuster` to include and copy over *all*
source attributes, *including* `//method/@synthetic`.

*NOW* `generator` began to see methods with
`//method[@Synthetic='true']`, *and **skip** them*.

The resulting code *compiled*, but had [ABI breakage][0].

Remove the special-casing logic for `synthetic` methods from
`generator`.  monodroid@2c515356 never supported direct consumption
of `class-parse` output by `generator`, meaning such an effort will
require more work *anyway*, and removing `synthetic` special-casing from
`generator` will allow it to consume post-0881accd
`Xamarin.Android.Tools.ApiXmlAdjuster` output without breaking things.

[0]: https://jenkins.mono-project.com/job/xamarin-android-pr-builder/3642/API_20Compatibility_20Checks/
@jonpryor
Copy link
Contributor Author

The reported unit test failure makes no sense at all, so I've restarted that build.

/me crosses fingers for the next build...

@jonpryor
Copy link
Contributor Author

Rebuild is successful!

@atsushieno
Copy link
Contributor

We'll have to keep using ApiXmlAdjuster for at least a few years because otherwise metadata fixups from anyone won't work as expected anymore.

@atsushieno atsushieno merged commit 78f7301 into dotnet:master Jul 27, 2018
@github-actions github-actions bot locked and limited conversation to collaborators Apr 14, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants