Generating Baseline Profiles

Generating Baseline Profiles — ship the AOT compilation hint list and prove it moved the needle

Baseline Profiles ship an AOT compilation hint list inside the APK so ART pre-compiles hot Compose code paths on install instead of relying on JIT during the first runs. Cited gains: roughly 30% faster cold startup and 40% smoother first-scroll on the journeys that were profiled. Compose ships unbundled from the platform, so every Compose UI app benefits — there is no version of Android where Compose is already AOT-compiled by the system image.

This skill is the measurement spine for the rest of the performance work. Profiles are generated with BaselineProfileRule from androidx.benchmark:benchmark-macro-junit4 and measured with MacrobenchmarkRule from the same artifact. Generation and measurement are two distinct @Test files in a separate :baselineprofile module that AGP 8.2+ scaffolds via New Module → Baseline Profile Generator.

When to use this skill

• Cold startup is slow and the developer wants AOT-compiled hot paths on first launch.
• First-scroll on a LazyColumn / LazyVerticalGrid is janky on real devices even after stability fixes.
• Preparing a release build and the developer needs a perf baseline before shipping.
• Verifying that a stability or strong-skipping fix actually moved cold-startup or frame-timing numbers — Macrobenchmark is the ground truth.
• The user mentions "baseline profile", "macrobenchmark", "TTFD", "time-to-fully-drawn", "StartupTimingMetric", "FrameTimingMetric", "CompilationMode", aosp_cf_x86_64_phone-userdebug, or "ReportDrawn".

When NOT to use this skill

• Still in early prototyping with no release-ready user journeys yet — Baseline Profiles encode hot paths, and there are no hot paths to encode while screens are still churning.
• The developer wants per-composable recomposition counts — that is ../../recomposition/debugging-recompositions/SKILL.md (debug Layout Inspector) or ../tracing-recompositions-at-runtime/SKILL.md (release @TraceRecomposition).
• The developer wants a CI gate against stability regressions — that is ../../stability/enforcing-stability-in-ci/SKILL.md. Baseline Profiles measure runtime; stabilityCheck measures compile-time skippability.
• Numbers are being collected from a debug build — debug builds run interpreted with Live Literals and produce non-representative numbers. See ../testing-compose-in-release-mode/SKILL.md.

Prerequisites

• AGP 8.2+ so the New Module → Baseline Profile Generator template is available (it scaffolds the androidx.baselineprofile Gradle plugin and a :baselineprofile module).
• A physical low-end test device or a Cuttlefish emulator (aosp_cf_x86_64_phone-userdebug). High-end pixel devices mask perf wins; emulators with default API images are not representative.
• A release variant configured (isMinifyEnabled = true, isShrinkResources = true, proguard-android-optimize.txt). Debug builds are not measurable. See ../../build/configuring-r8-for-compose/SKILL.md for R8 setup if missing.
• <profileable android:shell="true"/> in the app AndroidManifest.xml under <application> so the Macrobenchmark process can attach simpleperf. The android: namespace prefix is required — without it, manifest merger fails.
• At least one scroll journey identified beyond startup — a feed list, a paginated grid, opening a detail screen. Profiling startup alone leaves first-scroll uncompiled.
• Familiarity with ../../stability/diagnosing-compose-stability/SKILL.md and ../../recomposition/debugging-recompositions/SKILL.md if startup is dominated by avoidable recomposition rather than initial composition.

Workflow

1. Add the Baseline Profile Generator module

In Android Studio: File → New → New Module → Baseline Profile Generator. Pick the target application module. AGP scaffolds:

• A new :baselineprofile module with the androidx.baselineprofile Gradle plugin applied.
• A BaselineProfileGenerator.kt skeleton with a BaselineProfileRule @Test.
• A StartupBenchmarks.kt skeleton with a MacrobenchmarkRule @Test.
• The androidx.baselineprofile plugin applied in the app module too, so ./gradlew :app:generateBaselineProfile is wired up.

If editing manually instead of using the template, add to :baselineprofile/build.gradle.kts:

plugins {
    id("com.android.test")
    id("org.jetbrains.kotlin.android")
    id("androidx.baselineprofile")
}
android { targetProjectPath = ":app" }
dependencies {
    implementation("androidx.benchmark:benchmark-macro-junit4:1.3.0")
    implementation("androidx.test.ext:junit:1.2.1")
    implementation("androidx.test.uiautomator:uiautomator:2.3.0")
    implementation("androidx.test.espresso:espresso-core:3.6.1")
}

And to :app/build.gradle.kts:

plugins { id("androidx.baselineprofile") }
dependencies { baselineProfile(project(":baselineprofile")) }

See references/macrobenchmark-harness.md for the full Gradle + manifest setup including <profileable>.

2. Write the generator with both startup AND scroll

The generator is a @Test using BaselineProfileRule.collect. MUST cover startup plus at least one scroll — startup-only profiles leave first-scroll cold.

@RunWith(AndroidJUnit4::class)
class BaselineProfileGenerator {
    @get:Rule val rule = BaselineProfileRule()

    @Test
    fun startupAndScroll() = rule.collect(packageName = "com.example") {
        startActivityAndWait()
        val feed = device.findObject(By.res("feed"))
        feed.setGestureMargin(device.displayWidth / 5)
        feed.fling(Direction.DOWN)
        feed.fling(Direction.DOWN)
        device.findObject(By.res("feed_item_0"))?.click()
        device.wait(Until.hasObject(By.res("detail")), 3_000)
        device.pressBack()
    }
}

Use Modifier.testTag("feed") in the Compose source so By.res("feed") resolves. A gesture margin of displayWidth / 5 keeps flings off the system gesture area.

3. Generate the profile

./gradlew :app:generateBaselineProfile

For a specific variant: ./gradlew :app:generateReleaseBaselineProfile.

Output lands at:

app/src/<variant>/generated/baselineProfiles/baseline-prof.txt

(e.g. app/src/release/generated/baselineProfiles/baseline-prof.txt. On older AGP layouts the file may instead land at app/src/main/generated/baselineProfiles/baseline-prof.txt — AGP writes the variant-specific path; merge to main for shipping if all variants share a profile.)

4. Verify the profile shipped in the APK

Build → Analyze APK on the release .apk / .aab and confirm:

assets/dexopt/baseline.prof
assets/dexopt/baseline.profm

If those files are missing, the profile was generated but not packaged — usually because baselineProfile(project(":baselineprofile")) was not added to the app module's dependencies. Without these files in the APK, ART has nothing to AOT-compile and the perf gain is zero.

5. Measure with Macrobenchmark — startup

A separate @Test, in the same :baselineprofile module, using MacrobenchmarkRule. The compilation mode must be CompilationMode.Partial(BaselineProfileMode.Require) so the test fails loudly if the profile is missing rather than silently measuring an unprofiled build.

@RunWith(AndroidJUnit4::class)
class StartupBenchmarks {
    @get:Rule val rule = MacrobenchmarkRule()

    @Test
    fun startupCompilationBaselineProfiles() = rule.measureRepeated(
        packageName = "com.example",
        metrics = listOf(StartupTimingMetric()),
        iterations = 10,
        startupMode = StartupMode.COLD,
        compilationMode = CompilationMode.Partial(BaselineProfileMode.Require),
    ) {
        pressHome()
        startActivityAndWait()
    }
}

For an A/B comparison, add a sibling @Test with compilationMode = CompilationMode.None and compare medians. This is the only way to prove the profile moved the number.

6. Measure with Macrobenchmark — scroll

@Test
fun feedScrollPerformance() = rule.measureRepeated(
    packageName = "com.example",
    metrics = listOf(FrameTimingMetric()),
    iterations = 5,
    compilationMode = CompilationMode.Partial(BaselineProfileMode.Require),
) {
    startActivityAndWait()
    val feed = device.findObject(By.res("feed"))
    feed.setGestureMargin(device.displayWidth / 5)
    feed.fling(Direction.DOWN)
    feed.fling(Direction.DOWN)
}

FrameTimingMetric reports frameDurationCpuMs percentiles (P50 / P90 / P95 / P99) and frameOverrunMs (negative = on time, positive = missed deadline). The headline number is P95 frameOverrunMs — the worst-case missed-deadline frame in the high tail of a scroll.

7. Wire ReportDrawn for accurate TTFD

StartupTimingMetric reports timeToInitialDisplay by default. For timeToFullDisplay (TTFD) — the number that actually matches user perception — the app must call ReportDrawn once the first meaningful screen state is rendered. Without it, TTFD falls back to timeToInitialDisplay and undercounts.

import androidx.activity.compose.ReportDrawn
import androidx.activity.compose.ReportDrawnWhen
import androidx.activity.compose.ReportDrawnAfter

@Composable
fun Feed(state: FeedState) {
    ReportDrawnWhen { state.items.isNotEmpty() }
    LazyColumn { items(state.items, key = { it.id }) { SnackRow(it) } }
}

• ReportDrawn — fire immediately on composition (use when the first frame is the meaningful frame).
• ReportDrawnWhen { predicate } — fire when the predicate first turns true (typical case: state hydrated).
• ReportDrawnAfter { suspend block } — fire after the suspend block completes (typical case: an explicit awaitFirstFrame()).