Add Mac Catalyst TargetFrameworkIdentifier

[rolfbjarne]

I'm implementing support for Mac Catalyst in Xamarin, and I've run into a question whether a new TFI should be created or not.

First a few facts:

• Mac Catalyst is a blend of iOS and macOS (much more iOS than macOS though). We currently have two TFIs for these platforms, Xamarin.iOS and Xamarin.Mac respectively.
• The API surface that we would bind in managed code in Mac Catalyst is not identical to neither Xamarin.iOS nor Xamarin.Mac: it would contain parts of Xamarin.iOS, parts of Xamarin.Mac, and potentially API that's in neither Xamarin.iOS nor Xamarin.Mac.
• The native binaries (libmono, coreclr, etc.) have to be built specifically for Mac Catalyst. Binaries built for iOS or macOS won't work.

Adding a new TFI would have a few consequences:

• We'd have to implement support for the new TFI to many other places. NuGet comes to mind, but I'm certain there are many other places I'm unaware of. We'd also have a new TFI for .NET 6 (for instance net6.0-catalyst).
• Any existing NuGet for either Xamarin.iOS or Xamarin.Mac won't work.

Not adding a new TFI would also have a few consequences (say we re-use Xamarin.iOS):

• It would not be possible to create a NuGet that uses any API in Mac Catalyst that isn't in Xamarin.iOS.

Design proposal dotnet/designs#174

[Dotnet-GitSync-Bot]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[marek-safar]

@terrajobst @ericstj @mhutch would you be in favour of adding a new TFM for this configuration

[Redth]

If we didn't add a new TFI, we could probably still reason about attempting to use API's with runtime exceptions.

Given that Catalyst is much more similar to iOS, would we be able to swap out API binding references based on a project property? By default you get Xamarin.iOS.dll, but if you set <MacCatalyst>True</MacCatalyst>, we instead give you Xamarin.MacCatalyst.dll which has the superset of available API's? We could then use the existing API annotations on those bindings in roslyn analyzers to advise the user of things unavailable when building with -p:MacCatalyst=False. Then the iOS TFI could pivot based on that variable and build with the correct binding dll. We could also provide #define CATALYST based on the variable. The one disadvantage here is I'm not sure how nugets could provide anything but the MacCatalyst API superset of their assemblies to iOS/Catalyst developers. We could make the attribute available so they could proactively annotate their own API's around incompatibilities, but that feels sad.

For NuGets, this would mean we can still consume existing assemblies targeting iOS, though I'm not sure if there's a great path to surfacing runtime errors if you try and call an API path in one of these existing assemblies that isn't implemented on Catalyst, beyond some unhandled exception lacking much context.

[rolfbjarne]

Given that Catalyst is much more similar to iOS, would we be able to swap out API binding references based on a project property? By default you get Xamarin.iOS.dll, but if you set <MacCatalyst>True</MacCatalyst>, we instead give you Xamarin.MacCatalyst.dll which has the superset of available API's?

Would that work with the IDEs and things like intellisense? Or would you get red squiggles whenever you tried to use a Catalyst only API?

[Redth]

Given that Catalyst is much more similar to iOS, would we be able to swap out API binding references based on a project property? By default you get Xamarin.iOS.dll, but if you set <MacCatalyst>True</MacCatalyst>, we instead give you Xamarin.MacCatalyst.dll which has the superset of available API's?

Would that work with the IDEs and things like intellisense? Or would you get red squiggles whenever you tried to use a Catalyst only API?

I think that is the intention, if you aren’t specifying catalyst, you don’t get the APIs to reference. Or are you thinking the IDE may not handle swapping references based on a property this way very well?

[rolfbjarne]

Given that Catalyst is much more similar to iOS, would we be able to swap out API binding references based on a project property? By default you get Xamarin.iOS.dll, but if you set <MacCatalyst>True</MacCatalyst>, we instead give you Xamarin.MacCatalyst.dll which has the superset of available API's?

Would that work with the IDEs and things like intellisense? Or would you get red squiggles whenever you tried to use a Catalyst only API?

I think that is the intention, if you aren’t specifying catalyst, you don’t get the APIs to reference. Or are you thinking the IDE may not handle swapping references based on a property this way very well?

It's the second part: I wonder if the IDE will handle the reference swap correctly.

[marek-safar]

What about the following? We keep an only a single version of APIs, we could keep calling it Xamarin.iOS. We annotate all APIs which are not available on the Catalyst with [UnsupportedOSPlatformAttribute ("osx")] attribute and rely on existing platform compatibility analyzer to take care of flagging the unavailable APIs to the developers.

[rolfbjarne]

What about the following? We keep an only a single version of APIs, we could keep calling it Xamarin.iOS. We annotate all APIs which are not available on the Catalyst with [UnsupportedOSPlatformAttribute ("osx")] attribute and and rely on existing platform compatibility analyzer to take care of flagging the unavailable APIs to the developers.

That could work.

We'd also have to add all the macOS API (AppKit) that are available in Catalyst but not in iOS, and mark those with [UnsupportedOSPlatformAttribute ("iOS")].

and rely on existing platform compatibility analyzer

I assume there's a way to tell the platform compatibility analyzer which platform we're building for outside of the TFM?

[am11]

fwiw, currently the granularity chosen for shipping artifacts is 'package', such that, there is no concept of 'very similar' when it comes to a consumable package; slightly different is just another package. it has some benefit at the cost of a slightly scaled bandwidth usage (which is not an issue in this day and age). e.g. in .net 5, the difference between dotnet-sdk-linux-x64.tar.gz (linux glibc x64) and dotnet-sdk-linux-musl-x64.tar.gz (linux musl-libc x64) is about 13 binary files; out of total of 3100+ files, yet they are kept separate as it is easy to tag and reason about, imo (and it goes hand in hand with tfm mappings on engineering side of the house).

[filipnavara]

If you keep a single TFM how would I actually multi-target an app for both iOS and macOS in a single build?

[mhutch]

@terrajobst @richlander

My initial feeling is that we need a new TFM. But catalyst doesn't seem particularly descriptive and may end up seeming out of date in a few years. Maybe we should use net6.0-mac-catalyst? Or given we haven't shipped net6.0-mac yet, maybe we should use that for Catalyst and use net6.0-mac-cocoa for Xamarin.Mac?