Add analyzer for platform-specific APIs

[terrajobst]

This provides the attribute and analyzer needed to realize #97.

[marek-safar]

Will these attributes exist in reference assemblies only?

[terrajobst]

We should spec that indeed. What does Xamarin do today? Generally speaking, we don't strip most of the attributes. Leaving them in allows runtime light-up, but I can see them causing bloat.

[rolfbjarne]

Xamarin doesn't have reference assemblies, there's a single implementation assembly which contains all the availability attributes. They're all removed by the managed linker at build time (if the linker is enabled).

[marek-safar]

/cc @rolfbjarne

[rolfbjarne]

/cc @spouliot

[timheuer]

My general feedback here is that historically the trend to look for OS/runtime-specific versioning has been frowned upon. Even in the web world looking for if (IE7) {} kind of things has been a frowned upon approach in favor of looking at capabilities e.g., if (browserCanUseLocation()) {} -- here we are implementing a recommended pattern of explicit OS version checks (and how deep does it go? into patch release) versus a capability example. Is there a different design that would enable the analyzer to fire and say: if (Platform.CanCreateDirectorySecurity()) {} approach?

[terrajobst]

@timheuer

My general feedback here is that historically the trend to look for OS/runtime-specific versioning has been frowned upon. Even in the web world looking for if (IE7) {} kind of things has been a frowned upon approach in favor of looking at capabilities e.g., if (browserCanUseLocation()) {} -- here we are implementing a recommended pattern of explicit OS version checks (and how deep does it go? into patch release) versus a capability example. Is there a different design that would enable the analyzer to fire and say: if (Platform.CanCreateDirectorySecurity()) {} approach?

The reason it's frowned upon in web is because none of the features are browser-specific. However, there is such as thing as OS specific APIs and APIs that are introduced in a specific version. And given an analyzer we can tell people what version to check for. Capability APIs aren't as easy to tool as it's hard to correlate them back to specific APIs that need the check (see #111 if you're curious).

[mhutch]

My general feedback here is that historically the trend to look for OS/runtime-specific versioning has been frowned upon. Even in the web world looking for if (IE7) {} kind of things has been a frowned upon approach in favor of looking at capabilities e.g., if (browserCanUseLocation()) {} -- here we are implementing a recommended pattern of explicit OS version checks (and how deep does it go? into patch release) versus a capability example. Is there a different design that would enable the analyzer to fire and say: if (Platform.CanCreateDirectorySecurity()) {} approach?

Both approaches are valid and complementary - see #97 (comment)

[jzabroski]

The reason it's frowned upon in web is because none of the features are browser-specific. However, there is such as thing as OS specific APIs and APIs that are introduced in a specific version. And given an analyzer we can tell people what version to check for. Capability APIs aren't as easy to tool as it's hard to correlate them back to specific APIs that need the check (see #111 if you're curious).

⚠️ Brain dump
@terrajobst But to further @timheuer point: These kinds of arguments were made by jQuery development team, too. A loose cannon by the name of David Mark would debunk that, and explain how through careful API design, one could avoid "Browser-specific APIs". I used to eat popcorn and watch him flame jQuery and Sencha developers on Usenet on my lunch break as a junior developer. Rude guy, but had good points after you plucked through the ridiculous insults. Through picking the kernels out of my teeth, I learned a lot from him about not seeing things as platform-specific but as capability-specific. One BIG lesson I learned from David is it needs to be clear, transitively, that your API depends on either OS-detection or Capability-detection. And with Roslyn, why can't we automate a bunch of that information with simple annotations? So, let's say for example you're running tests on alpine linux which doesnt ship locales by default and you try a StringComparison enum value that doesn't make sense on alpine zero locale instance.

Frankly, a lot of the differences for most of us application developers are not even OS-specific. For UNIX, its ulibc vs glibc vs musl libc and link-load DWARF&ELF issues.

So, while on one hand, you do have a point, it doesn't mitigate the general preference to try to provide metadata around what that OS-specific capability really means. For example, POSIX gaurantees atomic file replacement, whereas Windows Replace Win32 call states nothing of the sort, except for an obscure Microsoft Research paper claiming it is atomic, and so its ambiguous as to whether File.Replace C# .NET call is atomic, or simply best-efforts atomic, and what OSes it can be atomic on, and how one can fallback to behaviors that may or may not be pseudo-atomic. You can easily see that PlatformAbstractions namespace should strive to advertise such ACID capabilities and/or design notes.

On the far end of the spectrum, you can dive into the docker file system abstraction logic and see all the ridiculous driver logic they created to support layers and think, "UGH, I give up - I need an docker-specific set of rules here." And to some extent, maybe only a certain subset of engineers should need to understand all the different failures that can happen with a file system and accept and adapt to rules for creating stackable filesystems. (I mean, how do you define a "capability" for some of the minimum viable product hacks they put into their driver code?)

[terrajobst]

I've update the document to match what we agreed on in the API review.