[xaprepare] Generate SourceLink.json

[jonpryor]

Fixes: #2614

Context: https://developercommunity.visualstudio.com/t/JNINativeWrappergcs-file-Not-found/10020777
Context: https://www.nuget.org/packages/sourcelink/
Context: https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md#source-link-file-specification
Context: https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/sourcelink
Context: https://www.hanselman.com/blog/exploring-net-cores-sourcelink-stepping-into-the-source-code-of-nuget-packages-you-dont-own

SourceLink is a set of tooling which allows debuggers to obtain
source code, allowing developers to "step into" assemblies for which
they don't have local source code to.

It operates by adding a JSON document to Portable PDB files, which
allows mapping paths within the Portable PDB file to a URL, which the
debugger can optionally download.

The JSON document contains a documents key, which contains a nested
dictionary which maps local filesystem path prefixes to URLs, e.g.

{
  "documents": {
    "…/xamarin/xamarin-android/external/Java.Interop/*":            "https://raw.githubusercontent.com/xamarin/java.interop/a5756ca8b8764c24cc169e40a473f79302b40ca9/*",
    "…/xamarin/xamarin-android/external/xamarin-android-tools/*":   "https://raw.githubusercontent.com/xamarin/xamarin-android-tools/9c641b3e08e56db37467a64a2c5de2c7f7ddb3ef/*",
    "…/xamarin/xamarin-android/*":                                  "https://raw.githubusercontent.com/xamarin/xamarin-android/903ba37ce70d2840983774e1d6fb55f8002561e2/*"
  }
}

This JSON document can be provided to the C# compiler by setting the
$(SourceLink) MSBuild property to the path of the JSON document.

The sourcelink dotnet global tool can be used to check .pdb
file contents:

% dotnet tool install --global SourceLink --version 3.1.1

To view the local paths within a .pdb file, use
sourcelink print-documents:

% $HOME/.dotnet/tools/sourcelink print-documents bin/Debug/lib/xamarin.android/xbuild-frameworks/Microsoft.Android/33/Mono.Android.pdb
9c5ad5a588d5a49deb98ccd63c7b0c4699c8f39d6ee1df4a8f4ae555be827e06 sha256 csharp …/xamarin-android/external/Java.Interop/src/Java.Interop.Tools.TypeNameMappings/Java.Interop.Tools.TypeNameMappings/JavaNativeTypeManager.cs
…

To view the remote URLs for those paths, use sourcelink print-urls:

% $HOME/.dotnet/tools/sourcelink print-urls bin/Debug/lib/xamarin.android/xbuild-frameworks/Microsoft.Android/33/Mono.Android.pdb
9c5ad5a588d5a49deb98ccd63c7b0c4699c8f39d6ee1df4a8f4ae555be827e06 sha256 csharp …/xamarin-android/external/Java.Interop/src/Java.Interop.Tools.TypeNameMappings/Java.Interop.Tools.TypeNameMappings/JavaNativeTypeManager.cs
https://raw.githubusercontent.com/xamarin/java.interop/a5756ca8b8764c24cc169e40a473f79302b40ca9/src/Java.Interop.Tools.TypeNameMappings/Java.Interop.Tools.TypeNameMappings/JavaNativeTypeManager.cs
…

To view the contents of the JSON document provided to the compiler,
use sourcelink print-json:

%  $HOME/.dotnet/tools/sourcelink print-json bin/Debug/lib/xamarin.android/xbuild-frameworks/Microsoft.Android/33/Mono.Android.pdb
{
  "documents": {
    …
    "…/xamarin/xamarin-android/external/Java.Interop/*": "https://raw.githubusercontent.com/xamarin/java.interop/a5756ca8b8764c24cc169e40a473f79302b40ca9/*",
    "…/xamarin/xamarin-android/external/xamarin-android-tools/*": "https://raw.githubusercontent.com/xamarin/xamarin-android-tools/9c641b3e08e56db37467a64a2c5de2c7f7ddb3ef/*",
    "…/xamarin/xamarin-android/*": "https://raw.githubusercontent.com/xamarin/xamarin-android/903ba37ce70d2840983774e1d6fb55f8002561e2/*"
  }
}

Finally, to verify that all URLs from sourcelink print-urls are
valid, use sourcelink test:

% $HOME/.dotnet/tools/sourcelink test bin/Debug/lib/xamarin.android/xbuild-frameworks/Microsoft.Android/33/Mono.Android.pdb

Note: this can take awhile.

To make all this work, update xaprepare to create a
bin/Build$(Configuration)/SourceLink.json file, and update
Configuration.props so that $(SourceLink) is set to the generated
SourceLink.json file, if it exists. SourceLink.json is generated
by reading .gitmodules to determine all of the git submodules, and
using that information to construct the "remote" URL prefix.

TODO:

SourceLink.json assumes that all remote URLs are GitHub URLs.
This may not be ideal, but works for most of our assemblies.

What should be done about generated files?

[grendello]

I think the PR is missing the GeneratedSourceLinkJsonFile sources :(

[jonpryor]

Doh!

[grendello]

turn that to

this.submodules = submodules ?? throw new ArgumentNullException(nameof (submodules));

to save some vertical space? :)

[grendello]

Constructor doesn't check whether xaCommit is valid and given that it is used to form a URL, perhaps it should?