Merge branch 'main' into dev/grendel/native-tracing

* main:
  It's ".NET for Android", not ".NET Android" (#8933)
  Bump to xamarin/Java.Interop/main@78d5937 (#8935)
  [docs] Add "Getting Started" docs (#8934)
  [Xamarin.Android.Build.Tests] Fix ActionBarSherlock URL (#8926)

Author: grendello

.gdn/tsaoptions-v2.json

@@ -1,5 +1,5 @@
 {
-  "codebaseName": "xamarin.android_main",
+  "codebaseName": "dotnet.android_main",
   "notificationAliases": [
       "dotnet-android-eng@microsoft.com"
   ],

.vscode/tasks.json

@@ -4,7 +4,7 @@
     "version": "2.0.0",
     "tasks": [
         {
-            "label": "Build All Xamarin.Android",
+            "label": "Build All .NET for Android",
             "type": "shell",
             "windows":{ "command": ".\\build.cmd ${input:buildtype}"},
             "linux":{"command": "./build.sh ${input:buildtype}"},
@@ -231,4 +231,4 @@
         ]
       },
     ]
-}
+}

Documentation/README.md

@@ -2,9 +2,9 @@
 
 # Getting Started
 
-  * [Installing the Xamarin.Android SDK](https://developer.xamarin.com/guides/android/getting_started/installation/)
-  * [Xamarin.Android Documentation](https://developer.xamarin.com/guides/android/)
-  * [Xamarin.Android API Documentation](https://developer.xamarin.com/api/root/MonoAndroid-lib/)
+  * [Installing the .NET for Android SDK](https://developer.xamarin.com/guides/android/getting_started/installation/)
+  * [.NET for Android Documentation](https://learn.microsoft.com/dotnet/android/)
+  * [.NET for Android API Documentation](https://learn.microsoft.com/en-us/dotnet/api/?preserve-view=true&view=net-android-34.0)
 
 
 # Project Docs
@@ -30,9 +30,9 @@
 
   * [Build System Configuration](building/configuration.md)
   * [Build Dependencies for Linux and macOS](building/unix/dependencies.md)
-  * [Building Xamarin.Android on Linux and macOS](building/unix/instructions.md)
+  * [Building .NET for Android on Linux and macOS](building/unix/instructions.md)
   * [Build Dependencies for Windows](building/windows/dependencies.md)
-  * [Building Xamarin.Android on Windows](building/windows/instructions.md)
+  * [Building .NET for Android on Windows](building/windows/instructions.md)
 
 
 # Development Workflow
@@ -50,4 +50,4 @@
 
 # Other Information
 
-  * [Wikipedia Entry for Xamarin.Android](https://en.wikipedia.org/wiki/Mono_(software)#Xamarin.Android)
+  * [Wikipedia Entry for .NET for Android](https://en.wikipedia.org/w/index.php?title=.NET_for_Android&redirect=yes)

Documentation/binfmt_misc-warning-Linux.txt

@@ -4,11 +4,11 @@ Your Linux appears to have support for binfmt_misc kernel module enabled.
 The module makes it possible to execute non-Linux binaries if the appropriate
 interpreter for the given format is available.
 Your machine is configured to handle Windows PE executables either via Mono or
-Wine. It will make the Xamarin.Android build fail IF you choose to build the
+Wine. It will make the .NET for Android build fail IF you choose to build the
 Windows cross-compilers by enabling the 'mxe-Win32' or 'mxe-Win64' host targets.
 
 You can disable the binfmt_misc module by issuing the following command as root
-before building Xamarin.Android:
+before building .NET for Android:
 
    echo 0 > /proc/sys/fs/binfmt_misc/status
 

Documentation/building/configuration.md

@@ -9,7 +9,7 @@
 
 # Build Configuration
 
-The Xamarin.Android build is heavily dependent on MSBuild, with the *intention*
+The .NET for Android build is heavily dependent on MSBuild, with the *intention*
 that it should (eventually?) be possible to build the project simply by
 checking out the repo, loading `Xamarin.Android.sln` into an IDE, and Building
 the solution. (This isn't currently possible, and may never be, but it's

Documentation/building/unix/dependencies.md

@@ -1,6 +1,6 @@
 # Build Dependencies for Linux and macOS
 
-Building Xamarin.Android requires:
+Building .NET for Android requires:
 
   * [Homebrew](#homebrew)
   * [Latest Mono](#mono-sdk)

Documentation/building/unix/instructions.md

@@ -1,10 +1,10 @@
-# Building Xamarin.Android on Linux and macOS
+# Building .NET for Android on Linux and macOS
 
-Building Xamarin.Android on Linux and macOS relies on GNU make and
+Building .NET for Android on Linux and macOS relies on GNU make and
 MSBuild via the `msbuild` command (within Mono). MSBuild via `xbuild`
 can also be used by setting the `$(MSBUILD)` make variable to `xbuild`.
 
-# Building Xamarin.Android
+# Building .NET for Android
 
  1. Install the [build dependencies](dependencies.md).
 
@@ -58,11 +58,11 @@ can also be used by setting the `$(MSBUILD)` make variable to `xbuild`.
 2019][xamdevsummit] with a full walkthrough. Even though the demo was
 on Windows, many of the concepts should still apply:
 
-[![Build Xamarin.Android](https://img.youtube.com/vi/8qaQleb6Tbk/maxresdefault.jpg)][xamdevsummit]
+[![Build .NET for Android](https://img.youtube.com/vi/8qaQleb6Tbk/maxresdefault.jpg)][xamdevsummit]
 
 [xamdevsummit]: https://youtu.be/8qaQleb6Tbk
 
-# Creating a local .NET android Workload
+# Creating a local .NET for Android Workload
 
 `make prepare` provisions a specific build of .NET to
 `bin/$(Configuration)/dotnet`.
@@ -95,12 +95,12 @@ See the [One .NET Documentation](../../guides/OneDotNet.md) for further details.
 # Creating installers
 
 Once `make all` or `make jenkins` have completed, macOS (.pkg),
-Windows (.vsix), and .NET android workload .nupkg files
+Windows (.vsix), and .NET for Android workload .nupkg files
 can be built with:
 
     make create-installers
 
-Alternatively, .NET android workload packs can be built with:
+Alternatively, .NET for Android workload packs can be built with:
 
     make create-nupkgs
     # -or-
@@ -351,23 +351,3 @@ For example, to rebuild Mono for armeabi-v7a:
 	$ msbuild /t:_InstallRuntimes src/mono-runtimes/mono-runtimes.csproj
 
 
-# How do I rebuild BCL assemblies?
-
-The Xamarin.Android Base Class Library assemblies, such as `mscorlib.dll`,
-are built within `external/mono`, using Mono's normal build system:
-
-	# This updates external/mono/mcs/class/lib/monodroid/ASSEMBLY.dll
-	$ make -C external/mono/mcs/class/ASSEMBLY PROFILE=monodroid
-
-Alternatively, if you want to rebuild *all* the assemblies, the "host"
-Mono needs to be rebuilt. Note that the name of the "host" directory
-varies based on the operating system you're building from:
-
-	$ make -C src/mono-runtimes/obj/Debug/host-Darwin
-
-Once the assemblies have been rebuilt, they can be copied into the appropriate
-Xamarin.Android SDK directory by using the `_InstallBcl` target:
-
-	# This updates bin/$(Configuration)/lib/xamarin.android/xbuild-frameworks/MonoAndroid/v1.0/ASSEMBLY.dll
-	$ msbuild src/mono-runtimes/mono-runtimes.csproj /t:_InstallBcl
-

Documentation/building/windows/dependencies.md

@@ -1,8 +1,8 @@
 # Build Dependencies for Windows
 
-Building Xamarin.Android requires:
+Building .NET for Android requires:
 
-  * An existing installation of the Xamarin.Android SDK and the Android SDK
+  * An existing installation of the .NET for Android SDK and the Android SDK
   * The .NET Framework 3.5 – 4.7 development tools
   * Git for Windows
   * The Java Development Kit (JDK)

Documentation/building/windows/instructions.md

@@ -1,12 +1,12 @@
-# Building Xamarin.Android on Windows
+# Building .NET for Android on Windows
 
-Building Xamarin.Android on Windows requires .NET and the `msbuild` command
+Building .NET for Android on Windows requires .NET and the `msbuild` command
 be available within the Command-Line environment.
 (The **Developer Command Prompt** that Visual Studio installs is sufficient.)
 
 MSBuild version 15 or later is required.
 
-# Building Xamarin.Android
+# Building .NET for Android
 
  1. Install the [build dependencies](dependencies.md).
 
@@ -80,13 +80,13 @@ So for example:
 [windows_path]: https://www.java.com/en/download/help/path.xml
 [set_alias]: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/set-alias?view=powershell-6
 
-# Creating a local .NET android Workload
+# Creating a local .NET for Android Workload
 
 `dotnet msbuild Xamarin.Android.sln -t:Prepare` provisions a
 specific build of .NET to `bin\$(Configuration)\dotnet`.
 
 Once the prepare target is complete, you can set up a local
-.NET android workload install with:
+.NET for Android workload install with:
 
     dotnet-local.cmd build Xamarin.Android.sln -t:BuildDotNet -m:1
 
@@ -121,7 +121,7 @@ See the [One .NET Documentation](../../guides/OneDotNet.md) for further details.
 # Creating installers
 
 Once `dotnet msbuild Xamarin.Android.sln -t:Prepare` is complete,
-.NET android workload packs can be built with:
+.NET for Android workload packs can be built with:
 
     dotnet-local.cmd build Xamarin.Android.sln -t:BuildDotNet,PackDotNet -m:1
 

Documentation/docs-mobile/getting-started/installation/dependencies.md

@@ -0,0 +1,106 @@
+---
+title: "Install .NET for Android dependencies"
+description: "Learn how to install .NET for Android dependencies so you can create native Android applications."
+ms.date: 11/01/2023
+---
+# Install .NET for Android dependencies
+
+In order to build .NET for Android applications you need to install the Android SDK and the Java SDK.
+
+## Using "InstallAndroidDependencies" target
+
+The easiest way to install the required dependencies for your Android application is to run the
+[`InstallAndroidDependencies`](../../building-apps/build-targets.md#installandroiddependencies)
+MSBuild target.
+
+This target will examine your application project and install the exact components which are needed.
+If you update your project to target a new Android API you will need to run this target again
+to make sure you get the required components.
+
+For example if you are upgrading your project to target API 34 from API 32, you will only have
+API 32 installed. Running the `InstallAndroidDependencies` target will install API 34 for you.
+
+If you do not have the Android SDK installed at all, this target can also handle installing the SDK
+on a clean machine. You can change the destination of the installation by setting the
+`AndroidSdkDirectory` MSBuild property.  It will also install the Java SDK if the `JavaSdkDirectory`
+MSBuild property is provided.
+
+```dotnetcli
+dotnet build -t:InstallAndroidDependencies -f net8.0-android -p:AndroidSdkDirectory=c:\work\android-sdk -p:JavaSdkDirectory=c:\work\jdk -p:AcceptAndroidSdkLicenses=True
+```
+
+Here are all the arguments which the target will use when installing the dependencies:
+
+* `-p:AndroidSdkDirectory="<PATH>"` installs or updates Android dependencies to the specified path.  
+    *Note*: You must use an absolute path; Unix developers should not use tilde (`~`), as it is
+    not expanded when used *within* a command-line argument.
+
+* `-p:JavaSdkDirectory="<PATH>"` installs Java to the specified path.  
+    *Note*: You must use an absolute path; Unix developers should not use tilde (`~`), as it is
+    not expanded when used *within* a command-line argument.
+
+* `-p:AcceptAndroidSDKLicenses=True` accepts the necessary Android licenses for development.
+
+> [!NOTE]
+> To make development easier try to avoid using paths which contain spaces or non-ASCII characters.
+
+## Install the Android SDK manually
+
+You might find it necessary to install the Android SDK manually:
+
+ 1. Go to [Android Studio download](https://developer.android.com/studio#download).  
+    Scroll down to the "Command Line Tools only" section and download the zip file for your operating system.
+
+ 2. Create an `android-sdk` directory somewhere on your hard drive. To make your life easier create it near to the root of the drive. For example `c:\android-sdk`.
+
+ 3. Extract the files from the zip file into this directory. You should end up with a folder structure like
+  `android-sdk\cmdline-tools`
+
+ 4. Open a terminal or Command Prompt.
+
+ 5. Navigate to the `android-sdk\cmdline-tools\bin` directory within the directory you created.
+
+ 6. Run the `sdkmanager` command to install the desired components.
+
+For example, to install the latest platform and platform tools, use:
+
+```console
+sdkmanager "platforms;android-34" "platform-tools" "build-tools;34.0.0" "emulator" "system-images;android-34;default;x86_64" "cmdline-tools;11.0" --sdk_root=c:\android-sdk
+```
+
+Note that double-quotes should be used liberally to enclose the semicolon `;`, which is part of the component names.
+
+You will be prompted to accept the license, after which the Android SDK will install.
+
+You can use `sdkmanager` to install additional components. You can use the `--list` argument to get a list of all the available components. You can then look through the list and find the additional components you want.
+
+```console
+sdkmanager --list
+```
+
+The following component types are useful to know:
+
+  * `platforms;android-XX`: Installs the platform `android-XX` into the sdk.
+    Replace *XX* with the API Level of your chosen platform.
+    For example `platforms;android-30` will install Android API 30, while
+    `platforms;android-21` will install Android API 21.
+
+  * `system-images;android-XX;default;x86_64`: Installs an emulator image for
+    the specific API level. The `x86_64` can be swapped out for different ABIs
+    such as `x86`, `arm64-v8a`, and `x86_64`. These reflect the ABI of the image
+    being installed. This can be useful if you have issues on specific ABI's.
+
+It is also good practice to set the `ANDROID_HOME` environment variable, as this
+allows you to use certain tooling from the command line.
+
+## Install Microsoft JDK manually
+
+In order to build .NET for Android applications or libraries you need to have a version of the Java Development Kit installed.
+We recommend you use the Microsoft Open JDK, this has been tested against our .NET for Android builds:
+
+ 1. Download [Microsoft OpenJDK 11](/java/openjdk/download#openjdk-11).
+
+ 2. Depending on your platform run the appropriate installer.
+
+ 3. It is also good practice to set the `JAVA_HOME` environment variable.
+    This will allow you to use the JDK from the Command Prompt or Terminal.