[dotnet] Add support for the @(LinkerArgument) item group to pass arguments to the native linker. Fixes #21331. (#23468)

Quite often customers need to pass custom arguments to the native linker.

Until now we haven't had an official way of doing this, besides the rather clunky:

```xml
<AppBundleExtraOptions>$(AppBundleExtraOptions) --gcc_flags '...'</AppBundleExtraOptions>
```

So add support for the `LinkerArgument` item group, which will now serve this purpose.

A code search on GitHub for '<LinkerArgument' shows exactly 1 result, which
seems to be unrelated (it's for Java code), so hopefully no existing projects
will already have 'LinkerArguments' set.

Fixes #21331.

Author: rolfbjarne

docs/building-apps/build-items.md

@@ -198,6 +198,38 @@ Additional xml files to pass to the trimmer.
 
 This is the same as setting [TrimmerRootDescriptor](/dotnet/core/deploying/trimming/trimming-options?#root-descriptors).
 
+## LinkerArgument
+
+Additional arguments to pass to the native linker (`ld`) when compiling the main executable for an app or app extension.
+
+Example 1 (to link with the `AudioToolbox` framework):
+
+```xml
+<ItemGroup>
+    <LinkerArgument Include="-framework" />
+    <LinkerArgument Include="AudioToolbox" />
+</ItemGroup>
+```
+
+Example 2 (to link with a custom static library):
+
+```xml
+<ItemGroup>
+    <LinkerArgument Include="$(MSBuildProjectDirectory)/libCustom.a" />
+</ItemGroup>
+```
+
+Each argument to the linker is a separate `LinkerArgument`, and arguments must not be quoted.
+
+All the arguments will be passed to the native linker in the order they're
+added to the `LinkerArgument` item group, but the exact location within all
+the arguments passed to the native linker is not defined.
+
+The native executable will be rebuilt automatically if the set of
+`LinkerArgument` changes between builds, but if a `LinkerArgument` points to a
+file (such as a static library), and that file changes, this change will not
+be detected and the native executable will not be rebuilt automatically.
+
 ## Metal
 
 An item group that contains metal assets.

dotnet/targets/Xamarin.Shared.Sdk.targets

@@ -1701,6 +1701,8 @@
 
 			<_AllLinkerFlags Condition="'$(_UseClassicLinker)' == 'true'" Include="-Xlinker" />
 			<_AllLinkerFlags Condition="'$(_UseClassicLinker)' == 'true'" Include="-ld_classic" />
+
+			<_AllLinkerFlags Include="@(LinkerArgument)" />
 		</ItemGroup>
 
 		<!-- write a hash of all the relevant input so that we can force a re-link if necessary -->