[Xamarin.Android.Build.Tasks] mostly R2R the main assembly (#12248)

crossgen2's `--partial` only precompiles methods named in the profile data passed via `--mibc`. There is no profile for a new app, so today the main app assembly is effectively not ReadyToRun compiled at all.

This adds a `GenerateMibcProfile` task that writes a `.mibc` naming the compilable methods of the main app assembly and adds it to `@(PublishReadyToRunPgoFiles)`, so crossgen2 compiles that assembly while everything else stays partial. Android version of dotnet/maui#34837.

The target runs `AfterTargets="ILLink" BeforeTargets="CreateReadyToRunImages"`, so the profile only contains methods that survived trimming, and only when `$(PublishReadyToRunCrossgen2ExtraArgs)` contains `--partial`.

Two things worth knowing:

- Methods in a generic context are left to the JIT. crossgen2 compiles those as shared code over `System.__Canon`, which a profile can only name via that implementation detail. So the assembly ends up mostly, not fully, R2R compiled.
- Output is deterministic, so an unchanged app produces a byte identical `.mibc` and does not invalidate incremental builds.

## Bring your own profile

If you record a real startup profile, for example with the `maui profile startup --format mibc` skill in [dotnet/maui-labs](https://github.com/dotnet/maui-labs), you have already said exactly what you want compiled, and the whole point of `--partial` is to compile only that. Naming every method of the app assembly on top of it would swamp it.

So this turns itself off when `@(PublishReadyToRunPgoFiles)` is already non-empty. Just adding your `.mibc` to that item group is enough, no extra property needed. MAUI's own framework profiles go into the private `@(_ReadyToRunPgoFiles)`, so they do not suppress this.

`$(_AndroidReadyToRunMainAssembly)` overrides the decision: `true` forces the profile on, `false` turns it off, blank (the default) means "on when crossgen2 is partial and the app brought no profile of its own".

## Results

Measured on the two MAUI templates, Android-only TFM, CoreCLR, Release, composite, `--partial;--map`, `-p:RuntimeIdentifier=android-arm64` so the APK carries a single ABI and the size numbers are not diluted by a second copy of everything. Each pair is the same project built twice, differing only by `$(_AndroidReadyToRunMainAssembly)`, so the profile is the only variable.

Startup is from a physical arm64 device: 25 iterations per run, and the whole thing run twice in opposite order (before/after, then after/before) so any ordering or thermal drift would show up as a gap between the two passes of the same APK. It does not.

| | `dotnet new maui` | `dotnet new maui -sc` |
| --- | --- | --- |
| methods in profile | 87 | 1,291 |
| profile size | 1,829 bytes | 14,867 bytes |
| skipped as generic | 0 | 23 |
| app methods in R2R image | 0 -> 87 | 0 -> 1,289 |
| APK size | 20,013,784 -> 20,079,320 | 23,032,560 -> 23,298,800 |
| APK delta | +65,536 (+0.33%) | +266,240 (+1.16%) |
| startup before | 826.6 +/- 3.6, 825.2 +/- 2.9 ms | 1685.1 +/- 3.8, 1688.3 +/- 4.0 ms |
| startup after | 805.7 +/- 2.7, 806.6 +/- 2.7 ms | 1609.0 +/- 2.9, 1613.7 +/- 3.7 ms |
| startup delta | -19.8 ms (-2.4%) | -75.4 ms (-4.5%) |

Both passes of each APK agree to within a couple of ms, and the before/after gap is 5-15x the combined standard error, so the deltas are well clear of the noise.

Essentially every method named in the profile lands in the R2R image, and the trade scales with how much code the app actually has: the blank template gains 87 methods for 64 KB, `-sc` gains 1,289 for 260 KB.

`apkdiff` shows all the growth is the composite R2R image; dex and every other entry are byte identical in both templates.

```
$ apkdiff full-arm64-before.apk full-arm64-after.apk      # dotnet new maui
  +      66,488 lib/arm64-v8a/libassembly-store.so
Summary:
  +           0 Other entries 0.00% (of 3,930,902)
  +           0 Dalvik executables 0.00% (of 16,997,756)
  +      66,488 Shared libraries 0.39% (of 17,016,032)
  +      65,536 Package size difference 0.33% (of 20,013,784)

$ apkdiff sc-arm64-before.apk sc-arm64-after.apk          # dotnet new maui -sc
  +     267,632 lib/arm64-v8a/libassembly-store.so
Summary:
  +           0 Other entries 0.00% (of 7,041,375)
  +           0 Dalvik executables 0.00% (of 17,026,184)
  +     267,632 Shared libraries 1.34% (of 20,013,592)
  +     266,240 Package size difference 1.16% (of 23,032,560)
```

## Build time cost

This never runs in a Debug build. `$(PublishReadyToRun)` only defaults to `true` for `$(Configuration)` of `Release`, and the target additionally requires crossgen2 to be in partial mode, so the inner-loop build is untouched. It is also CoreCLR only, since `Microsoft.Android.Sdk.CoreCLR.targets` is imported only for that runtime.

For Release builds, `GenerateMibcProfile` runs once per RID. Durations pulled from the binlogs:

| build | methods | 1st RID | 2nd RID |
| --- | --- | --- | --- |
| `dotnet new maui` | 87 | 33.6 ms | 1.0 ms |
| `dotnet new maui -sc` | 1,291 | 34.5 ms | 1.9 ms |
| `-sc`, `PublishTrimmed=false` | 1,291 | 40.4 ms | 1.9 ms |

So 35-45 ms per build, against roughly 50 s of wall clock and 128-142 s of total task time. Whichever RID runs first pays about 34 ms of task assembly load and JIT; the second pays 1-2 ms, and that marginal cost is the same whether the profile names 87 methods or 1,291. Writing the profile is effectively free, you are just paying to load the task once.

For scale, `RunReadyToRunCompiler` is 4.0-5.0 s in these same builds, so this is well under 1% of crossgen2's own time.

## Tests

`GenerateMibcProfileTests` for the writer, and `InstallAndRunTests.PublishReadyToRunPartial ([Values] bool isComposite)` builds, verifies the app assembly is R2R compiled in the APK, then installs and launches it. Both variants pass on an x86_64 emulator.

All four decision paths were verified end to end on a real MAUI app: partial with no profile generates it, a user supplied `@(PublishReadyToRunPgoFiles)` suppresses it, and each explicit value of `$(_AndroidReadyToRunMainAssembly)` overrides both. Both trimming paths were checked too: the default build profiles `obj/.../linked/App.dll`, and `-p:PublishTrimmed=false` profiles `obj/.../App.dll`.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: jonathanpeppers

.github/instructions/msbuild.instructions.md

@@ -0,0 +1,189 @@
+---
+applyTo: "**/*.targets,**/*.props,**/*.proj,**/*.csproj"
+---
+
+# MSBuild conventions
+
+Rules for authoring MSBuild targets, wherever they live — `.targets`, `.props`, `.proj`, and the
+18 `.csproj` files in this repo that declare their own `<Target>`. They matter most for the product
+targets under `src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/` and
+`src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets`, which ship to customers.
+
+## Every target that produces a file must be incremental
+
+Any target invoking a task that writes a file needs `Inputs` and `Outputs`. A target without them
+re-runs on every build, which shows up directly in customer inner-loop build times.
+
+```xml
+<Target Name="_AndroidGenerateSomething"
+    AfterTargets="_SomeUpstreamTarget"
+    DependsOnTargets="_AndroidGenerateSomethingInputs"
+    Inputs="@(_AndroidSomethingInput)"
+    Outputs="$(_AndroidSomethingOutput)">
+  <GenerateSomething Input="@(_AndroidSomethingInput)" OutputFile="$(_AndroidSomethingOutput)" />
+</Target>
+```
+
+### `Outputs` should be the real output file
+
+Write the output file directly from the task and use that file as `Outputs`. Do **not** reach for a
+temp file + `Files.CopyIfChanged` + a stamp file unless there is a concrete reason the timestamp
+must be preserved (e.g. the file feeds another incremental target that would otherwise cascade).
+
+`CopyIfChanged` deliberately leaves the timestamp alone when content is unchanged, which means the
+real output can never serve as `Outputs` — you are then forced to invent a
+`$(...)Stamp` file, `<MakeDir/>` it, `<Touch/>` it, and add it to `@(FileWrites)`. That is a lot of
+machinery to buy back something you did not need. Prefer the simple version.
+
+## Compute `Inputs` in a `<TargetName>Inputs` target
+
+Do not compute the input `ItemGroup` inside the target that consumes it — `Inputs` is evaluated
+before the target body runs, so the item group would be empty on the first evaluation. Put it in a
+separate target pulled in via `DependsOnTargets`, named `<TargetName>Inputs`:
+
+```xml
+<Target Name="_AndroidGenerateSomethingInputs">
+  <ItemGroup>
+    <_AndroidSomethingInput Include="@(_SomeBigList)" Condition=" '%(Filename)' == '$(TargetName)' " />
+  </ItemGroup>
+</Target>
+```
+
+`DependsOnTargets` targets run **before** the parent target's `Condition`, `Inputs`, and `Outputs`
+are evaluated, so this works.
+
+### Output paths belong in the same target
+
+`$(TargetName)`, `$(TargetFileName)`, `$(IntermediateOutputPath)`, `$(OutDir)` and friends are
+**not final** when our `.targets` files are evaluated — `$(TargetName)` is often blank, and
+`$(IntermediateOutputPath)` has not yet had the RID/TFM subdirectory appended. A top-level
+`<PropertyGroup>` computing an output path from them silently produces garbage such as
+`obj\Release\.mibc` instead of `obj\Release\net11.0\android-arm64\MyApp.mibc`.
+
+Compute output paths in a `<PropertyGroup>` inside the `<TargetName>Inputs` target alongside the
+input items. `DependsOnTargets` guarantees it runs before the parent's `Outputs` is evaluated.
+
+```xml
+<Target Name="_AndroidGenerateSomethingInputs">
+  <PropertyGroup>
+    <_AndroidSomethingOutput>$(IntermediateOutputPath)$(TargetName).ext</_AndroidSomethingOutput>
+  </PropertyGroup>
+  <ItemGroup>
+    ...
+  </ItemGroup>
+</Target>
+```
+
+### `Inputs` must be the actual inputs, not a superset
+
+Never list a whole upstream item group as `Inputs` when the task only consumes one item from it.
+Doing so makes the target re-run whenever *any* unrelated file in that list changes. Filter first,
+then use the filtered item group as `Inputs`.
+
+Filter in MSBuild — using `%(Filename)` batching and `@(X->Distinct())` — rather than
+passing everything to the task and filtering in C#. Prefer the simplest well-known property for the
+comparison (`%(Filename)` vs `$(TargetName)`, not `%(Filename)%(Extension)` vs `$(TargetFileName)`).
+Keep the task's surface area minimal; a task that takes `[Required] string MainAssembly` is easier
+to reason about and unit test than one that takes an `ITaskItem[]` plus a filter property.
+
+## Item groups in a skipped target *are* still evaluated
+
+If a target is skipped as **up to date** (its `Inputs` are older than its `Outputs`), MSBuild still
+evaluates the `<ItemGroup>` and `<PropertyGroup>` elements inside it. Downstream targets see those
+items. So do **not** split item population into a second `AfterTargets` target "so it still runs on
+incremental builds" — that is unnecessary indirection.
+
+```xml
+<Target Name="_AndroidGenerateSomething" Inputs="..." Outputs="...">
+  <GenerateSomething ... />
+  <!-- Still evaluated when the target is skipped as up to date. -->
+  <ItemGroup Condition=" Exists('$(_AndroidSomethingOutput)') ">
+    <_SomeConsumerList Include="$(_AndroidSomethingOutput)" />
+    <FileWrites Include="$(_AndroidSomethingOutput)" />
+  </ItemGroup>
+</Target>
+```
+
+This is **not** true for a target skipped by `Condition="false"` — that skips the entire target
+body, item groups included.
+
+## Read late-set properties from a target `Condition`, never at evaluation time
+
+Properties set by NuGet `buildTransitive` `.targets` (from packages like `Microsoft.Maui.Controls`)
+are assigned **after** our `.targets` are evaluated. A top-level `<PropertyGroup>` that reads such a
+property will see it blank.
+
+```xml
+<!-- WRONG: $(PublishReadyToRunCrossgen2ExtraArgs) may not be set yet. -->
+<PropertyGroup>
+  <_AndroidDoThing Condition=" $(PublishReadyToRunCrossgen2ExtraArgs.Contains('...')) ">true</_AndroidDoThing>
+</PropertyGroup>
+
+<!-- RIGHT: evaluated when the target runs, after everything is assigned. -->
+<Target Name="_AndroidDoThing" Condition=" $(PublishReadyToRunCrossgen2ExtraArgs.Contains('...')) ">
+```
+
+A helper property that merely aliases a condition is usually not worth it — inline the check in the
+target's `Condition`.
+
+## A target's `Condition` is evaluated *before* its `DependsOnTargets`
+
+So a `Condition` can never read a property that one of its dependencies sets — the dependency is
+never built. This is tempting when a decision has several inputs and you want to resolve it into a
+single property in the `Inputs` helper target; it silently never runs.
+
+Giving the helper the same `AfterTargets`/`BeforeTargets` hooks does work (targets sharing a hook
+run in declaration order), but it makes correctness depend on declaration order. Prefer keeping the
+whole decision inline in the `Condition`, even when it needs nested parentheses.
+
+## Test item emptiness with `->Count()`
+
+`'@(SomeItem)' == ''` batches the whole list into a string just to see whether it is empty. Use
+`'@(SomeItem->Count())' == '0'` instead.
+
+## Don't invent public properties
+
+Prefer keying off properties that already exist. Do not add a public `$(AndroidFooBar)` opt-in/
+opt-out knob unless a customer genuinely needs it — every public property is documentation,
+localization, and a compatibility commitment.
+
+When an internal escape hatch is needed (typically so a test can force a codepath), add a
+**private** `$(_Android*)` property that is **blank by default** — no `<PropertyGroup>` default for
+it anywhere — and `or` it into the existing condition:
+
+```xml
+Condition=" '$(PublishReadyToRun)' == 'true' and '$(_AndroidReadyToRunMainAssembly)' != 'false' and ('$(_AndroidReadyToRunMainAssembly)' == 'true' or ($(PublishReadyToRunCrossgen2ExtraArgs.Contains('--partial')) and '@(PublishReadyToRunPgoFiles->Count())' == '0')) "
+```
+
+Give the hatch three states rather than two: `true` forces the codepath on, `false` forces it off,
+and blank means "decide automatically". A force-on-only hatch leaves no way to build the baseline
+it is meant to be compared against.
+
+Public properties go in `Documentation/docs-mobile/building-apps/build-properties.md`; private
+`_`-prefixed ones must not.
+
+## Naming
+
+* Private targets, properties, and items are `_Android`-prefixed: `_AndroidGenerateMibcProfile`,
+  `$(_AndroidMibcProfile)`, `@(_AndroidMibcMainAssembly)`.
+* An `Inputs`-computing helper target is `<TargetName>Inputs`, not `_AndroidPrepareXxx` or similar.
+* Names should say what the thing *is*, not how it is used.
+
+## `--` is illegal inside an XML comment
+
+Writing `--partial`, `--map`, or any `--` sequence inside an `<!-- ... -->` block produces an XML
+parse error. Escape it, reword it, or move it out of the comment. Always validate after editing:
+
+```powershell
+try { [xml]$x = Get-Content path\to\File.targets; "ok" } catch { "INVALID: $($_.Exception.Message)" }
+```
+
+## Other verified semantics
+
+* If `Inputs` evaluates to empty and `Outputs` is non-empty, MSBuild skips the target for having no
+  inputs. Guard accordingly if an empty input list is legitimate.
+* `$(UndefinedProperty.Contains('x'))` safely evaluates to `false`; no null check is needed.
+* `@(X->Distinct())` is a valid item function and is the right way to dedupe overlapping item lists.
+* Add generated files to `@(FileWrites)` so `Clean` removes them.
+* Use `TaskFactory="TaskHostFactory"` and `Runtime="NET"` on `<UsingTask/>` for **internal**
+  build-time tasks (`xa-prep-tasks`, `BootstrapTasks`) only — never on tasks shipped to customers.

src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.CoreCLR.targets

@@ -7,6 +7,8 @@ This file contains the CoreCLR-specific MSBuild logic for .NET for Android.
 -->
 <Project>
 
+  <UsingTask TaskName="Xamarin.Android.Tasks.GenerateMibcProfile" AssemblyFile="$(_XamarinAndroidBuildTasksAssembly)" />
+
   <!-- Default property values for CoreCLR -->
   <PropertyGroup>
     <_AndroidRuntimePackRuntime>CoreCLR</_AndroidRuntimePackRuntime>
@@ -49,4 +51,69 @@ This file contains the CoreCLR-specific MSBuild logic for .NET for Android.
           Condition=" '%(ResolvedRuntimePack.FrameworkName)' == 'Microsoft.NETCore.App' And Exists('$(_DotnetRuntimeRepo)/artifacts/bin/microsoft.netcore.app.runtime.$(RuntimeIdentifier)/$(_DotNetRuntimeConfiguration)') " />
     </ItemGroup>
   </Target>
+
+  <!--
+    The crossgen2 "partial" switch restricts ReadyToRun compilation to the methods found in the
+    profile data passed via "mibc".  That is a good trade for framework assemblies, but it means
+    none of the application's own code gets precompiled unless it appears in a profile.
+
+    Generate a MIBC profile naming the methods of the main app assembly so that it is
+    ReadyToRun compiled, while the rest of the app remains partially compiled.
+
+    Everything below deliberately sticks to public MSBuild names.  `ILLink` and
+    `CreateReadyToRunImages` bracket the window where the trimmed assembly exists but crossgen2
+    has not run yet, and `@(PublishReadyToRunPgoFiles)` is the supported way to hand a profile to
+    crossgen2; `_PrepareForReadyToRunCompilation` copies it into its own private item group.
+
+    `$(_AndroidReadyToRunMainAssembly)` decides whether the profile is generated, in order:
+
+      1. An explicit `true` or `false` always wins.
+      2. Otherwise off when the app supplies its own `@(PublishReadyToRunPgoFiles)`.
+      3. Otherwise on when crossgen2 is running in partial mode.
+
+    An app that supplies its own profile, e.g. one recorded from a real startup trace with
+    `dotnet-pgo`, has already said exactly what it wants compiled, and the whole point of partial
+    mode is to compile only that.  Naming every method of the app assembly on top of it would
+    swamp that profile, so leave those builds alone.  Note this deliberately keys off the public
+    item: MAUI's own framework profiles go into `@(_ReadyToRunPgoFiles)`, so they do not
+    suppress this.
+  -->
+  <!-- $(TargetName) and $(IntermediateOutputPath) are not final until well after this file is
+       evaluated, so both the profile path and the main assembly are computed inside a target. -->
+  <Target Name="_AndroidGenerateMibcProfileInputs">
+    <PropertyGroup>
+      <_AndroidMibcProfile>$(IntermediateOutputPath)$(TargetName).mibc</_AndroidMibcProfile>
+      <!--
+        The main app assembly exactly as crossgen2 will see it.  ILLink writes the trimmed
+        assembly to $(IntermediateLinkDir), and this runs after it.  Without trimming
+        ($(AndroidLinkMode) of `None`, an explicit $(PublishTrimmed) of `false`, or
+        $(RunILLink) of `false`) ILLink never runs and crossgen2 compiles the compiler output
+        instead.  This mirrors when ILLink actually runs rather than probing for the trimmed
+        file, so a stale `linked` directory from an earlier build cannot be picked up.
+      -->
+      <_AndroidMibcMainAssembly Condition=" '$(PublishTrimmed)' == 'true' and '$(RunILLink)' != 'false' ">$(IntermediateLinkDir)$(TargetName)$(TargetExt)</_AndroidMibcMainAssembly>
+      <_AndroidMibcMainAssembly Condition=" '$(_AndroidMibcMainAssembly)' == '' ">@(IntermediateAssembly->'%(FullPath)')</_AndroidMibcMainAssembly>
+    </PropertyGroup>
+  </Target>
+
+  <!-- The decision is inline rather than resolved into a property by the target above, because
+       MSBuild evaluates a target's Condition *before* building its DependsOnTargets, so a
+       Condition can never read a property one of them sets. -->
+  <Target Name="_AndroidGenerateMibcProfile"
+      AfterTargets="ILLink"
+      BeforeTargets="CreateReadyToRunImages"
+      DependsOnTargets="_AndroidGenerateMibcProfileInputs"
+      Condition=" '$(PublishReadyToRun)' == 'true' and '$(_AndroidReadyToRunMainAssembly)' != 'false' and ('$(_AndroidReadyToRunMainAssembly)' == 'true' or ($(PublishReadyToRunCrossgen2ExtraArgs.Contains('--partial')) and '@(PublishReadyToRunPgoFiles->Count())' == '0')) "
+      Inputs="$(_AndroidMibcMainAssembly)"
+      Outputs="$(_AndroidMibcProfile)">
+    <GenerateMibcProfile
+        MainAssembly="$(_AndroidMibcMainAssembly)"
+        OutputFile="$(_AndroidMibcProfile)" />
+    <!-- MSBuild still evaluates ItemGroup/PropertyGroup elements of a target skipped as up to
+         date, so @(PublishReadyToRunPgoFiles) is populated on incremental builds too. -->
+    <ItemGroup Condition=" Exists('$(_AndroidMibcProfile)') ">
+      <PublishReadyToRunPgoFiles Include="$(_AndroidMibcProfile)" />
+      <FileWrites Include="$(_AndroidMibcProfile)" />
+    </ItemGroup>
+  </Target>
 </Project>

src/Xamarin.Android.Build.Tasks/Tasks/GenerateMibcProfile.cs

@@ -0,0 +1,42 @@
+#nullable enable
+
+using System.IO;
+using Microsoft.Android.Build.Tasks;
+using Microsoft.Build.Framework;
+
+namespace Xamarin.Android.Tasks;
+
+/// <summary>
+/// Generates a MIBC profile listing the methods of the "main app assembly" so that
+/// <c>crossgen2</c> in partial mode still ReadyToRun compiles it.
+///
+/// This runs after ILLink has trimmed the application, but before crossgen2 runs, so the profile
+/// only ever contains methods that survived trimming.
+/// </summary>
+public class GenerateMibcProfile : AndroidTask
+{
+	public override string TaskPrefix => "GMP";
+
+	/// <summary>
+	/// The "main app assembly", after trimming.
+	/// </summary>
+	[Required]
+	public string MainAssembly { get; set; } = "";
+
+	/// <summary>Path of the <c>.mibc</c> file to write.</summary>
+	[Required]
+	public string OutputFile { get; set; } = "";
+
+	public override bool RunTask ()
+	{
+		if (!File.Exists (MainAssembly)) {
+			Log.LogDebugMessage ($"Skipping MIBC profile generation, '{MainAssembly}' does not exist.");
+			return !Log.HasLoggedErrors;
+		}
+
+		int methods = MibcProfileWriter.Write ([MainAssembly], OutputFile, message => Log.LogDebugMessage ("{0}", message));
+		Log.LogDebugMessage ($"Wrote {methods} method(s) to '{OutputFile}'.");
+
+		return !Log.HasLoggedErrors;
+	}
+}