xamarin / xamarin-macios

.NET for iOS, Mac Catalyst, macOS, and tvOS provide open-source bindings of the Apple SDKs for use with .NET managed languages such as C#

Other

2.42k stars 507 forks source link

[bgen] Implement support for using default interface members to bind protocols. #20681

Closed rolfbjarne closed 3 weeks ago

rolfbjarne commented 4 weeks ago

Given the following API definition:

[Protocol]
public interface Protocol {
    [Abstract]
    [Export ("requiredMethod")]
    void RequiredMethod ();

    [Export ("optionalMethod")]
    void OptionalMethod ();
}

we're now binding it like this:

[Protocol ("Protocol")]
public interface IProtocol : INativeObject {
    [RequiredMember]
    [Export ("requiredMethod")]
    public void RequiredMethod () { /* default implementation */ }

    [OptionalMember]
    [Export ("optionalMethod")]
    public void OptionalMethod () { /* default implementation */ }
}

The main difference from before is that the only difference between required and optional members is the [RequiredMember]/[OptionalMember] attributes.

This has one major advantage: it's now possible to switch a member from being required to being optional, or vice versa, without breaking neither source nor binary compatibility.

It also improves intellisense for optional members. In the past optional members were implemented using extension methods, which were not very discoverable when you were supposed to implement a protocol in your own class.

The main downside is that the C# compiler won't enforce developers to implement required protocol members (which is a necessary side effect of the fact that we want to be able to switch members between being required and optional without breaking compatibility). If this turns out to be a problem, we can implement a custom source analyzer and/or linker step that detects missing implementations and issue warnings/errors.

This PR also:

Adds numerous tests.
Updates the requiredness of a few members in Metal to test that it works as expected.
Adds documentation.
Handles numerous corner cases, which are documented in code and docs.

This PR is probably best reviewed commit-by-commit.

Fixes https://github.com/xamarin/xamarin-macios/issues/13294.

vs-mobiletools-engineering-service2 commented 4 weeks ago

:books: [PR Build] Artifacts :books:

Packages generated

View packages

* [xamarin.ios-17.3.0.492.pkg](https://dl.internalx.com/wrench/merge/707ac2428af0156fc2b45a21f4c1a54887123f6d/9675157/package/xamarin.ios-17.3.0.492.pkg) * [xamarin.mac-9.3.0.492.pkg](https://dl.internalx.com/wrench/merge/707ac2428af0156fc2b45a21f4c1a54887123f6d/9675157/package/xamarin.mac-9.3.0.492.pkg)

Pipeline on Agent Hash: [PR build]

vs-mobiletools-engineering-service2 commented 4 weeks ago

:computer: [PR Build] Tests on macOS M1 - Mac Ventura (13) passed :computer:

:white_check_mark: All tests on macOS M1 - Mac Ventura (13) passed.

Pipeline on Agent Hash: [PR build]

vs-mobiletools-engineering-service2 commented 4 weeks ago

:computer: [PR Build] Tests on macOS M1 - Mac Monterey (12) passed :computer:

:white_check_mark: All tests on macOS M1 - Mac Monterey (12) passed.

Pipeline on Agent Hash: [PR build]

vs-mobiletools-engineering-service2 commented 4 weeks ago

:computer: [PR Build] Tests on macOS M1 - Mac Big Sur (11) passed :computer:

:white_check_mark: All tests on macOS M1 - Mac Big Sur (11) passed.

Pipeline on Agent Hash: [PR build]

vs-mobiletools-engineering-service2 commented 4 weeks ago

:computer: [PR Build] Tests on macOS X64 - Mac Sonoma (14) passed :computer:

:white_check_mark: All tests on macOS X64 - Mac Sonoma (14) passed.

Pipeline on Agent Hash: [PR build]

vs-mobiletools-engineering-service2 commented 4 weeks ago

:x: [CI Build] Windows Integration Tests failed :x:

:x: Failed :x:

Pipeline on Agent Hash: 4e8df9caec6ed74687af348eda8f4f2af321bbb4 [PR build]

vs-mobiletools-engineering-service2 commented 4 weeks ago

:heavy_exclamation_mark: API diff for current PR / commit (Breaking changes)

Legacy Xamarin (No breaking changes)

* iOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/previous-api-comparison/ios-api-diff.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/192c7b6e1db08f196cd78db552eaa8cf) (No breaking changes) * tvOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/previous-api-comparison/tvos-api-diff.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/d05be0e61b3c1a8c24bb0ed4031d93ae) (No breaking changes) * watchOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/previous-api-comparison/watchos-api-diff.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/043f7fdd364c38bd743ac547d6848469) (No breaking changes) * macOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/previous-api-comparison/mac-api-diff.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/79cfd722b3cb7bec780306dd624ce18c) (No breaking changes)

.NET (:heavy_exclamation_mark: Breaking changes :heavy_exclamation_mark:)

* iOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/previous-api-comparison/diff/dotnet/Microsoft.iOS.Ref/ref/net8.0/Microsoft.iOS.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/3a338f384b52a909c8b17af9f9d47569) (:heavy_exclamation_mark: Breaking changes :heavy_exclamation_mark:) * tvOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/previous-api-comparison/diff/dotnet/Microsoft.tvOS.Ref/ref/net8.0/Microsoft.tvOS.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/1c50a11159ae70acbb4af599cdb997f2) (:heavy_exclamation_mark: Breaking changes :heavy_exclamation_mark:) * MacCatalyst: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/previous-api-comparison/diff/dotnet/Microsoft.MacCatalyst.Ref/ref/net8.0/Microsoft.MacCatalyst.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/4ea95fba2e60ac47ba4a92ce9c1decf9) (:heavy_exclamation_mark: Breaking changes :heavy_exclamation_mark:) * macOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/previous-api-comparison/diff/dotnet/Microsoft.macOS.Ref/ref/net8.0/Microsoft.macOS.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/e69b73652085a5919c0a3ceed13fcb1b) (No breaking changes)

:heavy_exclamation_mark: API diff vs stable (Breaking changes)

Legacy Xamarin (No breaking changes)

* iOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/stable-api-comparison/ios-api-diff.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/9f18378506b44ebb021c8217cc3410b4) (No breaking changes) * tvOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/stable-api-comparison/tvos-api-diff.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/589de296d1125094c4bc9b39f4cd46a5) (No breaking changes) * watchOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/stable-api-comparison/watchos-api-diff.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/5e312bcd7a25ffb66b8d70c10a24db0c) (No breaking changes) * macOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/stable-api-comparison/mac-api-diff.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/b0bcd73bc3257866785ad62d0fb36691) (No breaking changes)

.NET (:heavy_exclamation_mark: Breaking changes :heavy_exclamation_mark:)

* iOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/stable-api-comparison/diff/dotnet/Microsoft.iOS.Ref/ref/net8.0/Microsoft.iOS.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/af51f926d332d5d1a49643edd8b93124) (:heavy_exclamation_mark: Breaking changes :heavy_exclamation_mark:) * tvOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/stable-api-comparison/diff/dotnet/Microsoft.tvOS.Ref/ref/net8.0/Microsoft.tvOS.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/5fdc0c15a7fd1ce86480dbdec8217f2a) (:heavy_exclamation_mark: Breaking changes :heavy_exclamation_mark:) * MacCatalyst: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/stable-api-comparison/diff/dotnet/Microsoft.MacCatalyst.Ref/ref/net8.0/Microsoft.MacCatalyst.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/3db42e89c4269fe4e8c9be18657858a7) (:heavy_exclamation_mark: Breaking changes :heavy_exclamation_mark:) * macOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/stable-api-comparison/diff/dotnet/Microsoft.macOS.Ref/ref/net8.0/Microsoft.macOS.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/a1162be49a7804cef83dee65da22bfda) (No breaking changes) * Microsoft.iOS vs Microsoft.MacCatalyst: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/stable-api-comparison/diff/dotnet/iOS-MacCatalyst-diff/Microsoft.iOS.Ref/ref/net8.0/Microsoft.iOS.MacCatalyst.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/dc348fede5c213beeccdf0b232317614)

Legacy Xamarin (stable) vs .NET

* iOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/stable-api-comparison/diff/dotnet/legacy-diff/Microsoft.iOS.Ref/ref/net8.0/Microsoft.iOS.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/1e45d81781905fdb452c6139cd5fbb0f) * tvOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/stable-api-comparison/diff/dotnet/legacy-diff/Microsoft.tvOS.Ref/ref/net8.0/Microsoft.tvOS.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/da28ea4c2ce8be7d52d2d41dc38bf44f) * macOS: [vsdrops](https://vsdrop.corp.microsoft.com/file/v1/xamarin-macios/detected-changes/20240604.6/9675157-1/;/stable-api-comparison/diff/dotnet/legacy-diff/Microsoft.macOS.Ref/ref/net8.0/Microsoft.macOS.html) [gist](https://gist.github.com/vs-mobiletools-engineering-service2/485ce30f9c972828cb924ac06e5c9010)

:information_source: Generator diff

Generator Diff: vsdrops (html) vsdrops (raw diff) gist (raw diff) - Please review changes)

Pipeline on Agent Hash: 4e8df9caec6ed74687af348eda8f4f2af321bbb4 [PR build]

vs-mobiletools-engineering-service2 commented 4 weeks ago

:computer: [PR Build] Tests on macOS X64 - Mac Sonoma (14) passed :computer:

:white_check_mark: All tests on macOS X64 - Mac Sonoma (14) passed.

Pipeline on Agent Hash: [PR build]

vs-mobiletools-engineering-service2 commented 4 weeks ago

:computer: [PR Build] Tests on macOS M1 - Mac Ventura (13) passed :computer:

:white_check_mark: All tests on macOS M1 - Mac Ventura (13) passed.

Pipeline on Agent Hash: [PR build]

vs-mobiletools-engineering-service2 commented 4 weeks ago

:computer: [PR Build] Tests on macOS M1 - Mac Monterey (12) passed :computer:

:white_check_mark: All tests on macOS M1 - Mac Monterey (12) passed.

Pipeline on Agent Hash: [PR build]

vs-mobiletools-engineering-service2 commented 4 weeks ago

:computer: [PR Build] Tests on macOS M1 - Mac Big Sur (11) passed :computer:

:white_check_mark: All tests on macOS M1 - Mac Big Sur (11) passed.

Pipeline on Agent Hash: [PR build]

vs-mobiletools-engineering-service2 commented 4 weeks ago

:fire: [CI Build] Test results :fire:

Test results

:x: Tests failed on VSTS: test results

1 tests crashed, 6 tests failed, 97 tests passed.

Failures

:x: linker tests

:fire: Failed catastrophically on VSTS: test results - linker (no summary found).

xamarin / xamarin-macios

[bgen] Implement support for using default interface members to bind protocols. #20681

:books: [PR Build] Artifacts :books:

Packages generated

:computer: [PR Build] Tests on macOS M1 - Mac Ventura (13) passed :computer:

:computer: [PR Build] Tests on macOS M1 - Mac Monterey (12) passed :computer:

:computer: [PR Build] Tests on macOS M1 - Mac Big Sur (11) passed :computer:

:computer: [PR Build] Tests on macOS X64 - Mac Sonoma (14) passed :computer:

:x: [CI Build] Windows Integration Tests failed :x:

:heavy_exclamation_mark: API diff for current PR / commit (Breaking changes)

:heavy_exclamation_mark: API diff vs stable (Breaking changes)

:information_source: Generator diff

:computer: [PR Build] Tests on macOS X64 - Mac Sonoma (14) passed :computer:

:computer: [PR Build] Tests on macOS M1 - Mac Ventura (13) passed :computer:

:computer: [PR Build] Tests on macOS M1 - Mac Monterey (12) passed :computer:

:computer: [PR Build] Tests on macOS M1 - Mac Big Sur (11) passed :computer:

:fire: [CI Build] Test results :fire:

Test results

Failures

:x: linker tests

:x: monotouch tests (iOS)

:x: monotouch tests (MacCatalyst)

:x: monotouch tests (tvOS)

Successes

:books: [PR Build] Artifacts :books:

Packages generated

:white_check_mark: API diff for current PR / commit

:white_check_mark: API diff vs stable

:information_source: Generator diff

:fire: [CI Build] Test results :fire:

Test results

Failures

:x: monotouch tests (iOS)

:x: monotouch tests (MacCatalyst)

:x: monotouch tests (tvOS)

Successes

:computer: [CI Build] Windows Integration Tests passed :computer:

:fire: [CI Build] Test results :fire:

Test results

Failures

:x: monotouch tests (iOS) [attempt 2]

:x: monotouch tests (MacCatalyst) [attempt 2]

:x: monotouch tests (tvOS) [attempt 2]

Successes

:white_check_mark: API diff for current PR / commit

:white_check_mark: API diff vs stable

:information_source: Generator diff

:fire: [CI Build] Test results :fire:

Test results

Failures

:x: cecil tests

:x: dotnettests tests (iOS)

:x: dotnettests tests (MacCatalyst)

:x: dotnettests tests (macOS)

:x: dotnettests tests (Multiple platforms)

:x: dotnettests tests (tvOS)

:x: framework tests

:x: fsharp tests

:x: generator tests

:x: install-source tests

:x: interdependent-binding-projects tests

:x: introspection tests

:x: linker tests

:x: mac-binding-project tests

:x: mmp tests

:x: mononative tests

:x: monotouch tests (iOS)

:x: monotouch tests (MacCatalyst)

:x: monotouch tests (macOS)

:x: monotouch tests (tvOS)

:x: monotouch tests (watchOS)

:x: msbuild tests

:x: mtouch tests

:x: xammac tests

:x: xcframework tests

:x: xtro tests

Successes

:books: [PR Build] Artifacts :books:

Packages generated

:computer: [PR Build] Tests on macOS X64 - Mac Sonoma (14) passed :computer: