diff --git a/Documentation/building/configuration.md b/Documentation/building/configuration.md index aca9e72f359..6d1e059a7b2 100644 --- a/Documentation/building/configuration.md +++ b/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) @@ -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` diff --git a/Documentation/building/windows/dependencies.md b/Documentation/building/windows/dependencies.md index 19ad1e679d3..9104f3e1dfa 100644 --- a/Documentation/building/windows/dependencies.md +++ b/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 - . +4. Under the **Individual components** tab, ensure that **Code tools > Git for + Windows** is installed. diff --git a/Documentation/building/windows/instructions.md b/Documentation/building/windows/instructions.md index f46313966b4..70a214b821f 100644 --- a/Documentation/building/windows/instructions.md +++ b/Documentation/building/windows/instructions.md @@ -1,27 +1,26 @@ # 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 @@ -29,7 +28,7 @@ MSBuild version 15 or later is required. 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 @@ -37,19 +36,23 @@ MSBuild version 15 or later is required. 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,23 +67,7 @@ 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`. @@ -88,7 +75,7 @@ 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,12 +105,12 @@ 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`. @@ -131,45 +118,44 @@ 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) @@ -177,15 +163,17 @@ 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 @@ -193,7 +181,7 @@ 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. diff --git a/Documentation/guides/InstallBuildsFromMain.md b/Documentation/guides/InstallBuildsFromMain.md index c42b7f7fedb..05585c78550 100644 --- a/Documentation/guides/InstallBuildsFromMain.md +++ b/Documentation/guides/InstallBuildsFromMain.md @@ -1,7 +1,7 @@ # Installing builds from the `main` branch Each commit from xamarin-android/main (that builds successfully) is -pushed to the [dotnet7 feed][0]. We can install these builds using +pushed to the [dotnet10 feed][0]. We can install these builds using `dotnet workload` commands. ## Install the .NET SDK @@ -13,12 +13,12 @@ exact matching build. If you pick at least the same preview/release number, it should be *close enough* to work. You can guess what the URL is, if you need a specific version like -`7.0.100-preview.6.22277.6`, for example: +`10.0.100-rc.1.25427.104`, for example: -* Windows x64: https://ci.dot.net/public/Sdk/7.0.100-preview.6.22277.6/dotnet-sdk-7.0.100-preview.6.22277.6-win-x64.exe -* Windows arm64: https://ci.dot.net/public/Sdk/7.0.100-preview.6.22277.6/dotnet-sdk-7.0.100-preview.6.22277.6-win-arm64.exe -* macOS x64: https://ci.dot.net/public/Sdk/7.0.100-preview.6.22277.6/dotnet-sdk-7.0.100-preview.6.22277.6-osx-x64.pkg -* macOS arm64: https://ci.dot.net/public/Sdk/7.0.100-preview.6.22277.6/dotnet-sdk-7.0.100-preview.6.22277.6-osx-arm64.pkg +* Windows x64: https://ci.dot.net/public/Sdk/10.0.100-rc.1.25427.104/dotnet-sdk-10.0.100-rc.1.25427.104-win-x64.exe +* Windows arm64: https://ci.dot.net/public/Sdk/10.0.100-rc.1.25427.104/dotnet-sdk-10.0.100-rc.1.25427.104-win-arm64.exe +* macOS x64: https://ci.dot.net/public/Sdk/10.0.100-rc.1.25427.104/dotnet-sdk-10.0.100-rc.1.25427.104-osx-x64.pkg +* macOS arm64: https://ci.dot.net/public/Sdk/10.0.100-rc.1.25427.104/dotnet-sdk-10.0.100-rc.1.25427.104-osx-arm64.pkg *See [WindowsOnArm64.md][3] for further details about Windows on Arm64.* @@ -27,22 +27,21 @@ You can guess what the URL is, if you need a specific version like On Windows, in a terminal running as Administrator run: ```dotnetcli -> dotnet workload install android --source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet7/nuget/v3/index.json --source https://api.nuget.org/v3/index.json +> dotnet workload install android --source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet10/nuget/v3/index.json --source https://api.nuget.org/v3/index.json ... Successfully installed workload(s) android. ``` On macOS, you can prepend `sudo` to the same command. -## Install Android API 32 +## Install Android API 36 If you get the error: ``` -error XA5207: Could not find android.jar for API level 32. -This means the Android SDK platform for API level 32 is not installed. -Either install it in the Android SDK Manager (Tools > Android > Android SDK Manager...), -or change your .NET for Android project to target an API version that is installed. +error XA5207: Could not find android.jar for API level 36. +This means the Android SDK platform for API level 36 is not installed; it was expected to be in `C:\Program Files (x86)\Android\android-sdk\platforms\android-36\android.jar`. +See https://aka.ms/xa5207 for more details. ``` On Windows, if your Android SDK is located in `C:\Program Files @@ -57,32 +56,10 @@ administrator to run: Alternatively, you can open the `Android SDK Manager` as described, click the gear icon in the bottom right, and select **Repository** > -**Full List**. Check **Android API 32** > **Android SDK Platform 32** +**Full List**. Check **Android API 36** > **Android SDK Platform 36** and click `Apply Changes`. -## Using Visual Studio - -If you want to use Visual Studio on Windows, make sure to install at -least Visual Studio 2022 17.3 (currently in preview) and the `.NET -Multi-platform App UI development` workload. - -The .NET 7 SDK has some changes to optional workloads that requires -some manual changes. - -If you look in `C:\Program Files\dotnet\sdk-manifests`, and have -folders such as: - -``` -6.0.300 -7.0.100 -7.0.100-preview.6 -``` - -You will need to copy any subfolders in `7.0.100-preview.6` to the -`7.0.100` directory. This will be resolved as soon as the .NET 7 -workload resolver is updated in Visual Studio. - -[0]: https://dev.azure.com/dnceng/public/_artifacts/feed/dotnet7 +[0]: https://dev.azure.com/dnceng/public/_artifacts/feed/dotnet10 [1]: https://github.com/dotnet/installer#table [2]: ../../eng/Version.Details.xml [3]: WindowsOnArm64.md diff --git a/Documentation/workflow/DevelopmentTips.md b/Documentation/workflow/DevelopmentTips.md index 768cc60a55f..380100038bc 100644 --- a/Documentation/workflow/DevelopmentTips.md +++ b/Documentation/workflow/DevelopmentTips.md @@ -563,11 +563,19 @@ Android workload. To simplify things, we have an MSBuild target to install .NET MAUI: - msbuild Xamarin.Android.sln -t:InstallMaui -p:MauiVersion=6.0.100-rc.1.1351 + # or dotnet-local.cmd on Windows + dotnet-local.sh build Xamarin.Android.sln -t:InstallMaui -p:MauiVersion=9.0.0 To find the version number of .NET MAUI you want to install, find the package on the [nightly Azure DevOps feed][maui-feed]. Or look for the -`Microsoft.NET.Sdk.Maui.Manifest-6.0.100` package on NuGet.org for public -releases. +`Microsoft.NET.Sdk.Maui.Manifest-9.0.100` package on NuGet.org for +public releases. Note that you may have to pass +`-p:MauiVersionBand=9.0.100`, if the `InstallMaui` target is trying to +download the incorrect manifest pack. + +Note that this will not provision the `maui-ios`, `maui-maccatalyst`, +or `maui-windows` parts of .NET MAUI. Simply specify a single +`net9.0-android` in MAUI projects +to build them. [maui-feed]: https://dev.azure.com/dnceng/public/_packaging?_a=feed&feed=dotnet6%40Local