Merge branch 'main' into dev/grendel/blazor-hang

* main:
  [ci] Use managed identity for ApiScan (#8823)
  [Xamarin.Android.Build.Tasks] DTBs should not rm generator output (#8706)
  [Xamarin.Android.Build.Tasks] Bump to NuGet 6.7.1 (#8833)
  $(AndroidPackVersionSuffix)=preview.4; net9 is 34.99.0.preview.4 (#8831)
  Localized file check-in by OneLocBuild Task (#8824)
  [Xamarin.Android.Build.Tasks] Enable POM verification features. (#8649)
  [runtime] Optionally disable inlining (#8798)
  Fix assembly count when satellite assemblies are present (#8790)
  [One .NET] new "greenfield" projects are trimmed by default (#8805)
  Localized file check-in by OneLocBuild Task (#8819)
  LEGO: Merge pull request 8820
  LEGO: Merge pull request 8818
  Bump to dotnet/installer@b40c44502d 9.0.100-preview.3.24165.20 (#8817)
  Bump com.android.tools:r8 from 8.2.47 to 8.3.37 (#8816)
  [Mono.Android] Prevent NullPointerException in TranslateStackTrace (#8795)
  Localized file check-in by OneLocBuild Task (#8815)
  [Xamarin.Android.Build.Tasks] Make all assemblies RID-specific (#8478)
  Localized file check-in by OneLocBuild Task (#8813)

Author: grendello

Directory.Build.props

@@ -36,7 +36,7 @@
          * Bump first digit of the patch version for feature releases (and reset the first two digits to 0)
     -->
     <AndroidPackVersion>34.99.0</AndroidPackVersion>
-    <AndroidPackVersionSuffix>preview.3</AndroidPackVersionSuffix>
+    <AndroidPackVersionSuffix>preview.4</AndroidPackVersionSuffix>
   </PropertyGroup>
 
   <!-- Common <PackageReference/> versions -->
@@ -48,7 +48,7 @@
     <NuGetApiPackageVersion>5.4.0</NuGetApiPackageVersion>
     <LZ4PackageVersion>1.1.11</LZ4PackageVersion>
     <MonoOptionsVersion>6.12.0.148</MonoOptionsVersion>
-    <SystemCollectionsImmutableVersion>6.0.0</SystemCollectionsImmutableVersion>
+    <SystemCollectionsImmutableVersion>8.0.0</SystemCollectionsImmutableVersion>
     <SystemRuntimeCompilerServicesUnsafeVersion>6.0.0</SystemRuntimeCompilerServicesUnsafeVersion>
     <ELFSharpVersion>2.13.1</ELFSharpVersion>
     <HumanizerVersion>2.14.1</HumanizerVersion>

Documentation/building/configuration.md

@@ -1,3 +1,12 @@
+<!--toc:start-->
+- [Build Configuration](#build-configuration)
+  - [Options suitable to use in builds for public use](#options-suitable-to-use-in-builds-for-public-use)
+  - [Options suitable for local development](#options-suitable-for-local-development)
+    - [Native runtime (`src/monodroid`)](#native-runtime-srcmonodroid)
+      - [Disable function inlining](#disable-function-inlining)
+      - [Don't strip the runtime shared libraries](#dont-strip-the-runtime-shared-libraries)
+<!--toc:end-->
+
 # Build Configuration
 
 The Xamarin.Android build is heavily dependent on MSBuild, with the *intention*
@@ -10,6 +19,8 @@ However, some properties may need to be altered in order to suit your
 requirements, such as the location of a cache directory to store
 the Android SDK and NDK.
 
+## Options suitable to use in builds for public use
+
 To modify the build process, copy
 [`Configuration.Override.props.in`](../../Configuration.Override.props.in)
 to `Configuration.Override.props`, and edit the file as appropriate.
@@ -93,7 +104,7 @@ Overridable MSBuild properties include:
 
   * `$(IgnoreMaxMonoVersion)`: Skip the enforcement of the `$(MonoRequiredMaximumVersion)`
     property. This is so that developers can run against the latest
-    and greatest. But the build system can enforce the min and max 
+    and greatest. But the build system can enforce the min and max
     versions. The default is `true`, however on CI we use:
 
          /p:IgnoreMaxMonoVersion=False
@@ -129,6 +140,43 @@ Overridable MSBuild properties include:
       * `4`: Mono 4.6 support.
       * `5`: Mono 4.8 and above support. This is the default.
 
-  * `$(AndroidEnableAssemblyCompression)`: Defaults to `True`. When enabled, all the 
+  * `$(AndroidEnableAssemblyCompression)`: Defaults to `True`. When enabled, all the
      assemblies placed in the APK will be compressed in `Release` builds. `Debug`
      builds are not affected.
+
+## Options suitable for local development
+
+### Native runtime (`src/monodroid`)
+
+Note that in order for the native build settings to have full effect, one needs to make sure that
+the entire native runtime is rebuilt **and** that all `cmake` files are regenerated.  This is true
+on the very first build, but rebuilds may require forcing the entire runtime to be rebuilt.
+
+The simplest way to do it is to remove `src/monodroid/obj` and run the usual build from the
+repository's root directory.
+
+#### Disable function inlining
+
+The native runtime by default builds with function inlining enabled, making heavy use of
+the feature in order to generate faster code.  However, when debugging a native crash inlining
+causes stack traces to point to unlikely locations, reporting the outer function as the crash
+location instead of the inlined function where crash actually happened.  There are two ways to
+enable this mode of operation:
+
+  1. Export the `XA_NO_INLINE` environment variable before building either the entire repository
+     or just `src/monodroid/`
+  2. Set the MSBuild property `DoNotInlineMonodroid` to `true`, when building `src/monodroid/monodroid.csproj`
+
+Doing either will force all normally inlined functions to be strictly preserved and kept
+separate.  The generated code will be slower, but crash stack traces should be much more precise.
+
+#### Don't strip the runtime shared libraries
+
+Similar to the previous section, this option makes crash stack traces more informative.  In normal
+builds, all the debugging information is stripped from the runtime shared libraries, thus making
+stack traces rarely point to anything more than the surrounding function name (which may sometimes
+be misleading, too).  Just as for inlining, the no-strip mode can be enabled with one of two ways:
+
+  1. Export the `XA_NO_STRIP` environment variable before building either the entire repository
+     or just `src/monodroid/`
+  2. Set the MSBuild property `DoNotStripMonodroid` to `true`, when building `src/monodroid/monodroid.csproj`

Documentation/guides/AndroidMavenLibrary.md

@@ -17,9 +17,10 @@ Note: This feature is only available in .NET 9+.
 </ItemGroup>
 ```
 
-This will do two things at build time:
+This will do several things at build time:
 - Download the Java [artifact](https://central.sonatype.com/artifact/com.squareup.okhttp3/okhttp/4.9.3) with group id `com.squareup.okhttp3`, artifact id `okhttp`, and version `4.9.3` from [Maven Central](https://central.sonatype.com/) to a local cache (if not already cached).
 - Add the cached package to the .NET Android bindings build as an [`<AndroidLibrary>`](https://github.com/xamarin/xamarin-android/blob/main/Documentation/guides/building-apps/build-items.md#androidlibrary).
+- Download the Java artifact's POM file (and any needed parent/imported POM files) to enable [Java Dependency Verification](JavaDependencyVerification.md). To opt out of this feature, add `VerifyDependencies="false"` to the `<AndroidMavenLibrary>` item.
 
 Note that only the requested Java artifact is added to the .NET Android bindings build. Any artifact dependencies are not added. If the requested artifact has dependencies, they must be fulfilled individually.
 

Documentation/guides/JavaDependencyVerification.md

@@ -0,0 +1,115 @@
+# Java Dependency Verification
+
+Note: This feature is only available in .NET 9+.
+
+## Description
+
+A common problem when creating Java binding libraries for .NET Android is not providing the required Java dependencies. The binding process ignores API that requires missing dependencies, so this can result in large portions of desired API not being bound.
+
+Unlike .NET assemblies, a Java library does not specify its dependencies in the package. The dependency information is stored in external files called POM files. In order to consume this information to ensure correct dependencies an additional layer of files must be added to a binding project.
+
+Note: the preferred way of interacting with this system is to use [`<AndroidMavenLibrary>`](AndroidMavenLibrary.md) which will automatically download any needed POM files.
+
+For example:
+
+```xml
+<AndroidMavenLibrary Include="com.squareup.okio:okio" Version="1.17.4" />
+```
+
+automatically gets expanded to:
+
+```xml
+<AndroidLibrary 
+  Include="<MavenCacheDir>/Central/com.squareup.okio/okio/1.17.4/com.squareup.okio_okio.jar" 
+  Manifest="<MavenCacheDir>/Central/com.squareup.okio/okio/1.17.4/com.squareup.okio_okio.pom"
+  JavaArtifact="com.squareup.okio:okio" 
+  JavaVersion="1.17.4" />
+  
+<AndroidAdditionalJavaManifest
+  Include="<MavenCacheDir>/Central/com.squareup.okio/okio-parent/1.17.4/okio-parent-1.17.4.pom"
+  JavaArtifact="com.squareup.okio:okio-parent"
+  JavaVersion="1.17.4" />
+  
+etc.
+```
+
+However it is also possible to manually opt in to Java dependency verification using the build items documented here.
+
+## Specification
+
+To manually opt in to Java dependency verification, add the `Manifest`, `JavaArtifact`, and `JavaVersion` attributes to an `<AndroidLibrary>` item:
+
+```xml
+<!-- JavaArtifact format is {GroupId}:{ArtifactId} -->
+<ItemGroup>
+  <AndroidLibrary
+    Include="my_binding_library.jar"
+    Manifest="my_binding_library.pom"
+    JavaArtifact="com.example:mybinding"
+    JavaVersion="1.0.0" />
+</ItemGroup>
+```
+
+Building the binding project now should result in verification errors if `my_binding_library.pom` specifies dependencies that are not met.
+
+For example:
+
+```
+error : Java dependency 'androidx.collection:collection' version '1.0.0' is not satisfied.
+```
+
+Seeing these error(s) or no errors should indicate that the Java dependency verification is working. Follow the [Resolving Java Dependencies](ResolvingJavaDependencies.md) guide to fix any missing dependency errors.
+
+## Additional POM Files
+
+POM files can sometimes have some optional features in use that make them more complicated than the above example.
+
+That is, a POM file can depend on a "parent" POM file:
+
+```xml
+<parent>
+  <groupId>com.squareup.okio</groupId>
+  <artifactId>okio-parent</artifactId>
+  <version>1.17.4</version>
+</parent>
+```
+
+Additionally, a POM file can "import" dependency information from another POM file:
+
+```xml
+<dependencyManagement>
+  <dependencies>
+    <dependency>
+      <groupId>com.squareup.okio</groupId>
+      <artifactId>okio-bom</artifactId>
+      <version>3.0.0</version>
+      <type>pom</type>
+      <scope>import</scope>
+    </dependency>
+  </dependencies>
+</dependencyManagement>
+```
+
+Dependency information cannot be accurately determined without also having access to these additional POM files, and will results in an error like:
+
+```
+error : Unable to resolve POM for artifact 'com.squareup.okio:okio-parent:1.17.4'.
+```
+
+In this case, we need to provide the POM file for `com.squareup.okio:okio-parent:1.17.4`:
+
+```xml
+<!-- JavaArtifact format is {GroupId}:{ArtifactId} -->
+<ItemGroup>
+  <AndroidAdditionalJavaManifest
+    Include="com.square.okio.okio-parent.1.17.4.pom"
+    JavaArtifact="com.squareup.okio:okio-parent"
+    JavaVersion="1.17.4" />
+</ItemGroup>
+```
+
+Note that as "Parent" and "Import" POMs can themselves have parent and imported POMs, this step may need to be repeated until all POM files can be resolved.
+
+Note also that if using `<AndroidMavenLibrary>` this should all be handled automatically.
+
+At this point, if there are dependency errors, follow the [Resolving Java Dependencies](ResolvingJavaDependencies.md) guide to fix any missing dependency errors.

Documentation/guides/ResolvingJavaDependencies.md

@@ -0,0 +1,101 @@
+# Resolving Java Dependencies
+
+Note: This feature is only available in .NET 9+.
+
+## Description
+
+Once Java dependency verification has been enabled for a bindings project, either automatically via `<AndroidMavenLibrary>` or manually via `<AndroidLibrary>`, there may be errors to resolve, such as:
+
+```
+error : Java dependency 'androidx.collection:collection' version '1.0.0' is not satisfied.
+```
+
+These dependencies can be fulfilled in many different ways.
+
+## `<PackageReference>`
+
+In the best case scenario, there is already an existing binding of the Java dependency available on NuGet.org. This package may be provided by Microsoft or the .NET community. Packages maintained by Microsoft may be surfaced in the error message like this:
+
+```
+error : Java dependency 'androidx.collection:collection' version '1.0.0' is not satisfied. Microsoft maintains the NuGet package 'Xamarin.AndroidX.Collection' that could fulfill this dependency.
+```
+
+Adding the `Xamarin.AndroidX.Collection` package to the project should automatically resolve this error, as the package provides metadata to advertise that it provides the `androidx.collection:collection` dependency. This is done by looking for a specially crafted NuGet tag.  For example, for the AndroidX Collection library, the tag looks like this:
+
+```xml
+<!-- artifact={GroupId}:{ArtifactId}:{Java Library Version} -->
+<PackageTags>artifact=androidx.collection:collection:1.0.0</PackageTags>
+```
+
+However there may be NuGet packages which fulfill a dependency but have not had this metadata added to it.  In this case, you will need to explicitly specify which dependency the package contains with `JavaArtifact` and `JavaVersion`:
+
+```xml
+<PackageReference 
+  Include="Xamarin.Kotlin.StdLib" 
+  Version="1.7.10" 
+  JavaArtifact="org.jetbrains.kotlin:kotlin-stdlib" 
+  JavaVersion="1.7.10" />
+```
+
+With this, the binding process knows the Java dependency is satisfied by the NuGet package.
+
+> Note: NuGet packages specify their own dependencies, so you will not need to worry about transitive dependencies.
+
+## `<ProjectReference>`
+
+If the needed Java dependency is provided by another project in your solution, you can annotate the `<ProjectReference>` to specify the dependency it fulfills:
+
+```xml
+<ProjectReference 
+  Include="..\My.Other.Binding\My.Other.Binding.csproj" 
+  JavaArtifact="my.other.binding:helperlib" 
+  JavaVersion="1.0.0" />
+```
+
+With this, the binding process knows the Java dependency is satisfied by the referenced project.
+
+> Note: Each project specifies their own dependencies, so you will not need to worry about transitive dependencies.
+
+## `<AndroidLibrary>`
+
+If you are creating a public NuGet package, you will want to follow NuGet's "one library per package" policy so that the NuGet dependency graph works.  However, if creating a binding for private use, you may want to include your Java dependencies directly inside the parent binding.
+
+This can be done by adding additional `<AndroidLibrary>` items to the project:
+
+```xml
+<ItemGroup>
+  <AndroidLibrary Include="mydependency.jar" JavaArtifact="my.library:dependency-library" JavaVersion="1.0.0" />
+</ItemGroup>
+```
+
+To include the Java library but not produce C# bindings for it, mark it with `Bind="false"`:
+
+```xml
+<ItemGroup>
+  <AndroidLibrary Include="mydependency.jar" JavaArtifact="my.library:dependency-library" JavaVersion="1.0.0" Bind="false" />
+</ItemGroup>
+```
+
+Alternatively, `<AndroidMavenLibrary>` can be used to retrieve a Java library from a Maven repository:
+
+```xml
+<ItemGroup>
+  <AndroidMavenLibrary Include="my.library:dependency-library" Version="1.0.0" />
+  <!-- or, if the Java library doesn't need to be bound -->
+  <AndroidMavenLibrary Include="my.library:dependency-library" Version="1.0.0" Bind="false" />
+</ItemGroup>
+```
+
+> Note: If the dependency library has its own dependencies, you will be required to ensure they are fulfilled.
+
+## `<AndroidIgnoredJavaDependency>`
+
+As a last resort, a needed Java dependency can be ignored. An example of when this is useful is if the dependency library is a collection of Java annotations that are only used at compile type and not runtime.
+
+Note that while the error message will go away, it does not mean the package will magically work. If the dependency is actually needed at runtime and not provided the Android application will crash with a `Java.Lang.NoClassDefFoundError` error.
+
+```xml
+<ItemGroup>
+  <AndroidIgnoredJavaDependency Include="com.google.errorprone:error_prone_annotations" Version="2.15.0" />
+</ItemGroup>
+```