[docs] improve "building" docs

Documentation/building/configuration.md

@@ -2,7 +2,7 @@
 - [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)
+    - [Native runtime (`src/native`)](#native-runtime-srcnative)
       - [Disable function inlining](#disable-function-inlining)
       - [Don't strip the runtime shared libraries](#dont-strip-the-runtime-shared-libraries)
 <!--toc:end-->
@@ -146,13 +146,13 @@ Overridable MSBuild properties include:
 
 ## Options suitable for local development
 
-### Native runtime (`src/monodroid`)
+### Native runtime (`src/native`)
 
 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
+The simplest way to do it is to remove `src/native/obj` and run the usual build from the
 repository's root directory.
 
 #### Disable function inlining
@@ -164,8 +164,8 @@ location instead of the inlined function where crash actually happened.  There a
 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`
+     or just `src/native/`
+  2. Set the MSBuild property `DoNotInlineMonodroid` to `true`, when building `src/native/native-*.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.
@@ -178,5 +178,5 @@ stack traces rarely point to anything more than the surrounding function name (w
 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`
+     or just `src/native/`
+  2. Set the MSBuild property `DoNotStripMonodroid` to `true`, when building `src/native/native-*.csproj`

Documentation/building/windows/dependencies.md

@@ -2,36 +2,28 @@
 
 Building .NET for Android requires:
 
-  * 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)
+* An existing installation of the .NET for Android SDK and the Android SDK
 
-The recommended steps to install these dependencies are:
+* The latest stable .NET SDK
+
+* Git for Windows
 
- 1. Run the [Visual Studio Installer](https://visualstudio.microsoft.com/vs/).
+* The Java Development Kit (JDK)
 
- 2. Under the **Workloads** tab, ensure that the **Mobile development with
-    .NET** workload is installed.  Under the **Optional** items for the
-    workload, ensure **Android SDK setup** is selected.
+The recommended steps to install these dependencies are:
 
- 3. Also ensure the **.NET desktop development** workload is installed.  Under
-    the **Optional** items for the workload, ensure the following items are
-    installed:
+1. Run the [Visual Studio Installer](https://visualstudio.microsoft.com/vs/).
 
-      * **.NET Framework 4 – 4.6 SDKs**
-      * **.NET Framework 4.6.2 SDK**
-      * **.NET Framework 4.7 SDK**
-      * **.NET Core 2.0 or 3.0 SDK**
+2. Under the **Workloads** tab, ensure that the **.NET Multi-platform
+   App UI development** workload is installed.  Under the
+   **Optional** items for the workload, ensure **Android SDK setup**
+   is selected.
 
-    The following items are also recommended:
+3. Also ensure the **.NET desktop development** workload is installed.
 
-      * **.NET Framework 4.7.1 development tools**
-      * **.NET Framework 4.7.2 development tools**
+   The following items are also recommended:
 
- 4. Under the **Individual components** tab, ensure that **Code tools > Git for
-    Windows** is installed.
+   * **.NET Framework 4.8 development tools**
 
- 5. Ensure the .NET Framework 3.5 SP1 Runtime is installed by downloading and
-    running the installer from
-    <https://www.microsoft.com/net/download/visual-studio-sdks>.
+4. Under the **Individual components** tab, ensure that **Code tools > Git for
+   Windows** is installed.

Documentation/building/windows/instructions.md

@@ -1,55 +1,58 @@
 # Building .NET for Android on Windows
 
-Building .NET for Android on Windows requires .NET and the `msbuild` command
+Building .NET for Android on Windows requires .NET and the `dotnet` 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.
+.NET 9 SDK or later is required at the time of writing.
 
-# Building .NET for Android
+## Building .NET for Android
 
  1. Install the [build dependencies](dependencies.md).
 
- 2. Clone the xamarin-android repo:
+ 2. Clone the dotnet/android repo:
 
-        git clone https://github.com/xamarin/xamarin-android.git
+        git clone https://github.com/dotnet/android.git
 
- 3. Navigate to the `xamarin-android` directory
+ 3. Navigate to the `android` directory
 
  4. (Optional) [Configure the build](../configuration.md).
 
  5. In a [Developer Command Prompt][developer-prompt], prepare the project:
 
-        dotnet msbuild Xamarin.Android.sln -t:Prepare -nodeReuse:false
-        dotnet msbuild external\Java.Interop\Java.Interop.sln -t:Prepare -nodeReuse:false
+        dotnet msbuild Xamarin.Android.sln -t:Prepare
 
     This will ensure that the build dependencies are installed, perform
     `git submodule update`, download NuGet dependencies, and other
     "preparatory" and pre-build tasks that need to be performed.
 
  6. Build the project:
 
-        dotnet-local.cmd build Xamarin.Android.sln  -nodeReuse:false
+        dotnet-local.cmd build Xamarin.Android.sln
 
  7. (For Microsoft team members only - Optional) In a [Developer Command
     Prompt][developer-prompt], build external proprietary git
     dependencies:
 
         dotnet-local.cmd build Xamarin.Android.sln -t:BuildExternal
 
-    This will clone and build external proprietary components such as `monodroid`.
+    This will clone and build external proprietary components such as
+    the `android-platform-support` repository in Azure DevOps.
+
+ 8. Configure local `android` workload:
+
+        dotnet-local.cmd build build-tools/create-packs/Microsoft.Android.Sdk.proj -t:ConfigureLocalWorkload
 
 After the solution has built successfully, you can use `dotnet-local.cmd` to create and build Android projects.
 
+Once an initial build succeeds, for incremental builds, you can simply do:
+
+    dotnet-local.cmd build Xamarin.Android.sln
+
 [developer-prompt]: https://docs.microsoft.com/dotnet/framework/tools/developer-command-prompt-for-vs
-[configprops-main]: https://github.com/xamarin/xamarin-android/blob/main/Configuration.props
 
 ## Windows Build Notes
 
-Currently Windows avoids building many of the macOS dependencies by downloading
-a zip bundle of mono-related binaries previously built on macOS.  This speeds up
-the build and enables development on Windows, in general.
-
 Opening `Xamarin.Android.sln` in Visual Studio currently tends to hold file
 locks on output assemblies containing MSBuild tasks.  If you are only making
 changes to Xamarin.Android.Build.Tasks, one way to avoid this issue is to open
@@ -64,31 +67,15 @@ Visual Studio Code instead and build via the command-line.
 
 [xamdevsummit]: https://youtu.be/8qaQleb6Tbk
 
-## Alternatives to Developer Command Prompt
-
-The [Developer Command Prompt][developer-prompt] is not explicitly required,
-you mostly just need a way to easily invoke `MSBuild.exe`.
-
-So for example:
-
-* You *could* use:
-  `"C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\MSBuild\15.0\Bin\MSBuild.exe"`.
-* You could add `MSBuild.exe` to your `%PATH%` via
-  [Windows environment variables GUI][windows_path].
-* You could setup a powershell alias to `msbuild` using [Set-Alias][set_alias].
-
-[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 for 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 for Android workload install with:
 
-    dotnet-local.cmd build Xamarin.Android.sln -t:BuildDotNet -m:1
+    dotnet-local.cmd build Xamarin.Android.sln -t:BuildDotNet
 
 Your local `bin\$(Configuration)\lib\packs` directory will be
 populated with a local Android "workload" in
@@ -118,82 +105,83 @@ Using the `dotnet-local` script will execute the `dotnet` provisioned in
 
 See the [One .NET Documentation](../../guides/OneDotNet.md) for further details.
 
-# Creating installers
+## Creating installers
 
 Once `dotnet msbuild Xamarin.Android.sln -t:Prepare` is complete,
 .NET for Android workload packs can be built with:
 
-    dotnet-local.cmd build Xamarin.Android.sln -t:BuildDotNet,PackDotNet -m:1
+    dotnet-local.cmd build Xamarin.Android.sln -t:BuildDotNet,PackDotNet
 
 Several `.nupkg` files will be output in `.\bin\Build$(Configuration)\nuget-unsigned`.
 
 Commercial packages will be created by this command if the
 `dotnet-local.cmd build Xamarin.Android.sln -t:BuildExternal`
 command was ran before building.
 
-# Building Unit Tests
+## Building Unit Tests
 
-Once `dotnet msbuild Xamarin.Android.sln` has completed, the unit tests may
+Once `dotnet-local.cmd build Xamarin.Android.sln` has completed, the unit tests may
 be built with e.g.:
 
-	dotnet-local.cmd build Xamarin.Android-Tests.sln /restore /p:Configuration=Debug /bl:bin\TestDebug\msbuild-build-tests.binlog
+    dotnet-local.cmd build Xamarin.Android-Tests.sln /restore /p:Configuration=Debug /bl:bin\TestDebug\msbuild-build-tests.binlog
 
-Note that the `Debug` in `bin\Debug` must match the Configuration which was
-built.  If xamarin-android was built with `msbuild /p:Configuration=Release ...`,
-then this should be `bin\Release`, not `bin\Debug`.
+Note that the `Debug` in `bin\Debug` must match the Configuration
+which was built.  If dotnet/android was built with `-c Release`, then
+this should be `bin\Release`, not `bin\Debug`.
 
 *NOTE*: There is currently no equivalent to [`make
 jenkins`](../unix/instructions.md) on Windows.
 
-*Troubleshooting*: Ensure you check your MSBuild version (`msbuild -version`)
-and path for the proper version of MSBuild.
+*Troubleshooting*: Ensure you check your .NET version (`dotnet --version`)
+and path for the proper version of `dotnet`.
 
-
-# Running Unit Tests
+## Running Unit Tests
 
 All `.apk`-based unit tests can be executed via
 
-	msbuild Xamarin.Android.sln /t:RunApkTests
+    dotnet-local.cmd build Xamarin.Android.sln /t:RunApkTests
 
-## Listing Nunit Tests
+### Listing Nunit Tests
 
 In order to get a list of the tests you can use the `ListNUnitTests` target
 
-    msbuild Xamarin.Android.sln /t:ListNUnitTests
+    dotnet-local.cmd build Xamarin.Android.sln /t:ListNUnitTests
 
 This will produce a list of the tests in all of the test assemblies.
 
-## Running Specific Nunit Tests
+### Running Specific Nunit Tests
 
-You can run then a single (or a group) of tests using the `$(TEST)` msbuild property.
+You can run then a single (or a group) of tests using the `$(TEST)` MSBuild property.
 
-    msbuild Xamarin.Android.sln /t:RunNunitTests /p:TEST=Xamarin.Android.Build.Tests.Aapt2Tests.Aapt2Compile
+    dotnet-local.cmd build Xamarin.Android.sln /t:RunNunitTests /p:TEST=Xamarin.Android.Build.Tests.Aapt2Tests.Aapt2Compile
 
-## Running Individual `.apk` Projects
+### Running Individual `.apk` Projects
 
 See also the [`tests/RunApkTests.targets`](../../tests/RunApkTests.targets) and
 [`build-tools/scripts/TestApks.targets`](../../build-tools/scripts/TestApks.targets)
 files.
 
 All `.apk`-based unit test projects provide the following targets:
 
-  * `DeployTestApks`: Installs the associated `.apk` to an Android device.
-  * `UndeployTestApks`: Uninstalls the associated `.apk` from an Android device.
-  * `RunTestApks`: Executes the unit tests contained within a `.apk`.
-    This target must be executed *after* the `DeployTestApks` target.
+* `DeployTestApks`: Installs the associated `.apk` to an Android device.
+
+* `UndeployTestApks`: Uninstalls the associated `.apk` from an Android device.
+
+* `RunTestApks`: Executes the unit tests contained within a `.apk`.
+  This target must be executed *after* the `DeployTestApks` target.
 
 To run an individual `.apk`-based test project, a package must be built, using the
 `SignAndroidPackage` target, installed, and executed.
 
-## Running `.apk` Projects with Include/Exclude
+### Running `.apk` Projects with Include/Exclude
 
 If an `.apk`-based unit test uses the NUnit `[Category]` custom attribute, then
 those tests can be explicitly included or excluded from execution by setting
 the `$(IncludeCategories)` or `$(ExcludeCategories)` MSBuild properties.
 
 For example, to exclude tests that use the internet (`InetAccess`) category:
 
-	msbuild Xamarin.Android.sln /t:RunApkTests /p:ExcludeCategories=InetAccess
+    dotnet-local.cmd build Xamarin.Android.sln /t:RunApkTests /p:ExcludeCategories=InetAccess
 
 `$(IncludeCategories)` functions in the same fashion.