mobile-platforms

# Mobile Platforms Triage and fix .NET failures on Apple mobile (iOS, tvOS, MacCatalyst) and Android in dotnet/runtime. ## Why mobile is different Mobile platforms run .NET on devices and simulators/emulators where the host OS controls code execution. Apple forbids JIT in production (simulators allow it), requires code signing, and has six OS variants that often need identical handling. Android requires cross-compilation and APK packaging across four architectures. Both surface failures invisible on desktop: provisioning errors, emulator boot timeouts, app bundle signing, native toolchain mismatches. CoreCLR is the primary runtime. NativeAOT is the default publish framework for ahead-of-time compilation. Mono also runs in CI alongside CoreCLR. ## CI pipeline Mobile tests run in the `runtime-extra-platforms` pipeline (AzDO definition 154, org `dnceng-public`, project `public`), daily on `main` and on relevant PRs. Jobs follow `{platform} {config} {subset}`: | Platform | Job pattern | Variants | |---|---|---| | iOS Simulator | `iossimulator-{x64,arm64}` | CoreCLR, Mono, NativeAOT | | tvOS | `tvos_arm64` | CoreCLR, Mono, NativeAOT | | MacCatalyst | `maccatalyst-{x64,arm64}` | CoreCLR, Mono, NativeAOT, AppSandbox | | Android | `android-{arm,arm64,x64,x86}` | CoreCLR, Mono, NativeAOT | Suffixes: empty (libraries), `RuntimeTests`, `Smoke`, `AppSandbox`, `Interp`. ## Where to look Start from the failure type, not the platform. The tables below map failure symptoms to code paths. ### Build and packaging failures These happen before tests run. The app bundle fails to build, sign, or package. | Platform | Build targets | App builder task | |---|---|---| | Apple | `src/mono/msbuild/apple/build/` | `src/tasks/AppleAppBuilder/` | | Android | `src/mono/msbuild/android/build/` | `src/tasks/AndroidAppBuilder/` | Apple code signing uses `DevTeamProvisioning`: `-` for simulators, `adhoc` for MacCatalyst. If a signing error mentions provisioning profiles, check whether the right value is passed in the pipeline YAML. ### Test failures The test itself fails or crashes on the device/emulator. | Platform | Test runner | Test targets | |---|---|---| | Apple | `src/libraries/Common/tests/AppleTestRunner/` | `eng/testing/tests.ioslike.targets` | | Android | `src/libraries/Common/tests/AndroidTestRunner/` | `eng/testing/tests.android.targets` | Common cause: a test assumes desktop behavior (process spawning, filesystem layout, JIT availability). Check whether the test has platform-specific skip conditions using `PlatformDetection`. ### NativeAOT compilation failures NativeAOT on mobile has a different target resolution path than desktop. `Directory.Build.targets` evaluates before NuGet package targets, so properties like `_IsApplePlatform` from `Microsoft.DotNet.ILCompiler` are not available in `eng/toolAot.targets`. For Apple mobile library tests, `ILCompilerTargetsPath` must be set to `$(CoreCLRBuildIntegrationDir)Microsoft.DotNet.ILCompiler.SingleEntry.targets` with `_IlcReferencedAsPackage=false`. Key files: `eng/targetingpacks.targets`, `eng/toolAot.targets`. ### Native interop crashes Stack traces pointing into native code or P/Invoke calls. | Platform | Native libs | |---|---| | Apple | `src/native/libs/System.Security.Cryptography.Native.Apple/`, `src/native/libs/System.Native/ios/` | | Android | `src/native/libs/` (shared with Linux/Bionic) | ### Pipeline YAML When the job definition itself is wrong (e.g., missing a platform, wrong build args): | Platform | Pipeline files | |---|---| | Apple (ioslike) | `eng/pipelines/extra-platforms/runtime-extra-platforms-ioslike.yml` | | Apple (simulator) | `eng/pipelines/extra-platforms/runtime-extra-platforms-ioslikesimulator.yml` | | Apple (maccatalyst) | `eng/pipelines/extra-platforms/runtime-extra-platforms-maccatalyst.yml` | | Android | `eng/pipelines/extra-platforms/runtime-extra-platforms-android.yml` | | Android (emulator) | `eng/pipelines/extra-platforms/runtime-extra-platforms-androidemulator.yml` | ## Platform gotchas Things that have caused confusion before and will again: - **Apple has six OS variants**: `ios`, `iossimulator`, `tvos`, `tvossimulator`, `maccatalyst` (x64 + arm64). A fix for one variant almost always needs to cover all six. Missing one causes the next pipeline run to fail on a different job. - **dsymutil outputs errors to stdout**, not stderr. `2>/dev/null` does not suppress its errors; use `>/dev/null 2>&1`. - **Android has four architectures**: `android-arm`, `android-arm64`, `android-x64`, `android-x86`. x86 is 32-bit and can expose different issues than the 64-bit targets. - **MSBuild evaluation order**: `Directory.Build.targets` runs before NuGet package `.targets`. Properties from packages are not available in `eng/toolAot.targets`. ## Failure triage Classify every failure as **infrastructure** or **code** before acting. Follow the repository's [GitHub publication authorization rules](../../copilot-instructions.md#github-publication-authorization) for all proposed issues, updates, and comments below. In an interactive session, explicit advance permission covering the proposed publication is sufficient; do not ask again. An executing workflow's documented publication contract may also authorize the proposed publication within its currently authorized actions; follow any approval conditions it requires. Otherwise, in interactive and coding sessions, present the complete draft and obtain explicit approval before publishing. Without authorization, leave the draft locally. A workflow's authorization covers only its declared outputs and action limits, not every reporting action described in this skill. ### Infrastructure failures Caused by the test environment, not code. Indicators: - Timeout with no test output (emulator/simulator boot failure) - "device not found", "provisioning profile", "code signing" errors - Network errors during Helix payload download - Machine-specific: same test passes on other machines - "No space left on device", Helix agent crashes Prepare an update for an existing tracking issue with a table entry: | Build | Date | Machine | Job | Error | |---|---|---|---|---| | [#buildNumber](link) | YYYY-MM-DD | machineName | jobName | brief error | If no matching issue exists, draft one with `area-Infrastructure` and platform labels (`os-ios`, `os-tvos`, `os-maccatalyst`, `os-android`). For already tracked known issues, check whether the root cause is actionable. If a code or configuration fix is feasible, prepare the fix and recommend a PR; open it only when publication is authorized. If the issue is purely infrastructure (device provisioning, network), draft occurrence data for the tracking issue instead. ### Code failures Caused by recent commits. Indicators: - Test was passing in previous builds - Error references managed code - Recent commit touched platform-sensitive code Investigate code failures by starting with `git log --oneline --since='3 days ago'` on the relevant path. If nothing matches, widen the window or check for intermittent patterns across recent builds. Common patterns: - New API missing mobile platform handling - `#if` conditional compilation missing a mobile target - P/Invoke change without a mobile native implementation - Test assuming desktop behavior (process spawning, JIT, filesystem paths) ## Self-improvement When a mobile fix workflow discovers new patterns or workarounds, draft a comment on the tracking issue (or a new issue labeled `area-Infrastructure-mono`) so the team can later incorporate it into this document. Publish only with the authorization described above. Include findings about: - New failure patterns not yet documented - Code paths that turned out to be relevant - Recurring infrastructure issues and their workarounds - Platform gotchas discovered during investigation Keep PRs focused on the mobile failure being fixed. Unrelated skill edits make review and blame harder, so avoid editing this file in PRs that are not fixing or documenting mobile platform work.