[dotnet] Add sourcelink support

Fixes xamarin#18968

We provide a mapping to the checked in source files via SourceLink.json
and the rest of the generated/untracked sources are embedded into the
PDB to provide a more comprehensive debugging experience. Since we
invoke CSC directly, there were a few workarounds that had to be implemented
(ex: implementing a helper script to account for untracked sources
instead of simply using the EmbedUntrackedSources MSBuild property).

As for testing, the newly added support was validated via the sourcelink
dotnet tool which confirmed all the sources in the PDB either had valid
urls or were embedded.

sourcelink test Microsoft.MacCatalyst.pdb —> sourcelink test passed: Microsoft.MacCatalyst.pdb

The PDB size does increase in size after embedding;
for example, Microsoft.MacCatalyst.pdb went from 5 MB to 15.7 MB.

But considering it would significantly help improve the debugging
experience, be consistent with Android’s offerings, and it’s a
highlighted attribute on the NuGet package explorer I think it’s a
worthy size increase.

Refs:
dotnet/android#7298
dotnet/roslyn#12625
https://github.com/dotnet/sourcelink/tree/main/docs

src/Makefile

@@ -1213,6 +1213,12 @@ dotnet-gen:: dotnet-gen-$(3)
 $($(2)_DOTNET_BUILD_DIR)/ILLink.LinkAttributes.xml: $(TOP)/src/ILLink.LinkAttributes.xml.in | $($(2)_DOTNET_BUILD_DIR)
 	$$(call Q_PROF_GEN,$(3)) sed < $$< > $$@ 's|@PRODUCT_NAME@|Microsoft.$(1)|g;'
 
+$($(2)_DOTNET_BUILD_DIR)/SourceLink.json: $($(2)_DOTNET_BUILD_DIR)
+	$$(Q) $(TOP)/src/generate-sourcelink-json.csharp "$(PACKAGE_HEAD_REV)" "$(abspath $(TOP)/src)" "$$@" >/dev/null 2>&1
+
+$($(2)_DOTNET_BUILD_DIR)/embed-files.rsp: $($(2)_DOTNET_BUILD_DIR)/$(3)-generated-sources
+	$$(Q) $(TOP)/src/generate-embed-files.sh $($(2)_DOTNET_BUILD_DIR) $(3) > $$@
+
 $($(2)_DOTNET_BUILD_DIR)/ILLink.Substitutions.xml: $(TOP)/src/ILLink.Substitutions.$(1).xml | $($(2)_DOTNET_BUILD_DIR)
 	$(Q) $(CP) $$< $$@
 
@@ -1259,6 +1265,8 @@ endif
 $(2)_DOTNET_PLATFORM_ASSEMBLY_DEPENDENCIES = \
 	$($(2)_DOTNET_SOURCES) \
 	$($(2)_DOTNET_BUILD_DIR)/$(3)-generated-sources \
+	$($(2)_DOTNET_BUILD_DIR)/SourceLink.json \
+	$($(2)_DOTNET_BUILD_DIR)/embed-files.rsp \
 	$($(2)_DOTNET_BUILD_DIR)/ILLink.LinkAttributes.xml \
 	$($(2)_DOTNET_BUILD_DIR)/ILLink.Substitutions.xml \
 	$(PRODUCT_KEY_PATH) \
@@ -1277,6 +1285,8 @@ $($(2)_DOTNET_BUILD_DIR)/$(4)/Microsoft.$(1)%dll $($(2)_DOTNET_BUILD_DIR)/$(4)/M
 		-publicsign -keyfile:$(PRODUCT_KEY_PATH) \
 		$$($(2)_$(4)_REFOUT_ARG) \
 		$$($(2)_$(4)_DOC_ARG) \
+		-sourcelink:$($(2)_DOTNET_BUILD_DIR)/SourceLink.json \
+		@$($(2)_DOTNET_BUILD_DIR)/embed-files.rsp \
 		$$($(2)_DEFINES) \
 		$(ARGS_$(4)) \
 		$$(DOTNET_WARNINGS_TO_FIX) \

src/generate-embed-files.sh

@@ -0,0 +1,28 @@
+#!/bin/bash -e
+
+find_files() {
+    find "$(realpath "$1")" -type f -name "$2" -exec printf "%s," {} +
+}
+
+build_dir="$1"
+platform="$2"
+
+if [ "$platform" = "macos" ]; then
+    modified_platform="mac"
+else
+    modified_platform="$platform"
+fi
+
+root="$(realpath "$build_dir/../../../..")"
+
+# find generated/untracked files
+# impt to include, otherwise sourcelink test will fail (don't have a valid source file to link to)
+files=$(find_files "$build_dir" "*.g.cs")
+files+=$(find_files "$root/src/build/common" "*.cs")
+files+=$(find_files "$root/src/build/$modified_platform" "AssemblyInfo.cs")
+files+=$(find_files "$root/src/build/$modified_platform" "Constants.cs")
+files+=$(find_files "$root/src/build/dotnet" "Constants.$platform.generated.cs")
+files+=$(find_files "$root/runtime" "*generated.cs") 
+files+=$(find_files "$root/src" "MinimumVersions.cs")
+files="-embed:${files%,}"
+echo $files

src/generate-sourcelink-json.csharp

@@ -0,0 +1,25 @@
+#!/usr/bin/env /Library/Frameworks/Mono.framework/Commands/csharp
+
+using System.IO;
+using System.Text;
+
+var args = Environment.GetCommandLineArgs ();
+
+var latestCommit = args [2];
+var src = args [3];
+var outputPath = args [4];
+
+var json    = new StringBuilder ();
+json.AppendLine ("{");
+json.AppendLine ("  \"documents\": {");
+
+json.AppendLine ($"    \"{src}*\": \"https://raw.githubusercontent.com/xamarin/xamarin-macios/{latestCommit}/src/*\"");
+json.AppendLine ("  }");
+json.AppendLine ("}");
+
+string outputData = json.ToString ();
+using (StreamWriter writer = new StreamWriter(outputPath))
+{
+    writer.Write(outputData);
+}
+