gradle-build-performance

name	gradle-build-performance
description	Debug and optimize Android/Gradle build performance. Use when builds are slow, investigating CI/CD performance, analyzing build scans, or identifying compilation bottlenecks.

Gradle Build Performance

When to Use

• Build times are slow (clean or incremental)
• Investigating build performance regressions
• Analyzing Gradle Build Scans
• Identifying configuration vs execution bottlenecks
• Optimizing CI/CD build times
• Enabling Gradle Configuration Cache
• Reducing unnecessary recompilation
• Debugging kapt/KSP annotation processing

Example Prompts

• "My builds are slow, how can I speed them up?"
• "How do I analyze a Gradle build scan?"
• "Why is configuration taking so long?"
• "Why does my project always recompile everything?"
• "How do I enable configuration cache?"
• "Why is kapt so slow?"

---

Workflow

1. Measure Baseline — Clean build + incremental build times
2. Generate Build Scan — ./gradlew assembleDebug --scan
3. Identify Phase — Configuration? Execution? Dependency resolution?
4. Apply ONE optimization — Don't batch changes
5. Measure Improvement — Compare against baseline
6. Verify in Build Scan — Visual confirmation

---

Quick Diagnostics

Generate Build Scan

./gradlew assembleDebug --scan

Profile Build Locally

./gradlew assembleDebug --profile
# Opens report in build/reports/profile/

Build Timing Summary

./gradlew assembleDebug --info | grep -E "^\:.*"
# Or view in Android Studio: Build > Analyze APK Build

---

Build Phases

Phase	What Happens	Common Issues
Initialization	settings.gradle.kts evaluated	Too many include() statements
Configuration	All build.gradle.kts files evaluated	Expensive plugins, eager task creation
Execution	Tasks run based on inputs/outputs	Cache misses, non-incremental tasks

Identify the Bottleneck

Build scan → Performance → Build timeline

• Long configuration phase: Focus on plugin and buildscript optimization
• Long execution phase: Focus on task caching and parallelization
• Dependency resolution slow: Focus on repository configuration

---

12 Optimization Patterns

1. Enable Configuration Cache

Caches configuration phase across builds (AGP 8.0+):

# gradle.properties
org.gradle.configuration-cache=true
org.gradle.configuration-cache.problems=warn

2. Enable Build Cache

Reuses task outputs across builds and machines:

# gradle.properties
org.gradle.caching=true

3. Enable Parallel Execution

Build independent modules simultaneously:

# gradle.properties
org.gradle.parallel=true

4. Increase JVM Heap

Allocate more memory for large projects:

# gradle.properties
org.gradle.jvmargs=-Xmx4g -XX:+UseParallelGC

5. Use Non-Transitive R Classes

Reduces R class size and compilation (AGP 8.0+ default):

# gradle.properties
android.nonTransitiveRClass=true

6. Migrate kapt to KSP

KSP is 2x faster than kapt for Kotlin:

// Before (slow)
kapt("com.google.dagger:hilt-compiler:2.51.1")

// After (fast)
ksp("com.google.dagger:hilt-compiler:2.51.1")

7. Avoid Dynamic Dependencies

Pin dependency versions:

// BAD: Forces resolution every build
implementation("com.example:lib:+")
implementation("com.example:lib:1.0.+")

// GOOD: Fixed version
implementation("com.example:lib:1.2.3")

8. Optimize Repository Order

Put most-used repositories first:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()      // First: Android dependencies
        mavenCentral() // Second: Most libraries
        // Third-party repos last
    }
}

9. Use includeBuild for Local Modules

Composite builds are faster than project() for large monorepos:

// settings.gradle.kts
includeBuild("shared-library") {
    dependencySubstitution {
        substitute(module("com.example:shared")).using(project(":"))
    }
}

10. Enable Incremental Annotation Processing

# gradle.properties
kapt.incremental.apt=true
kapt.use.worker.api=true

11. Avoid Configuration-Time I/O

Don't read files or make network calls during configuration:

// BAD: Runs during configuration
val version = file("version.txt").readText()

// GOOD: Defer to execution
val version = providers.fileContents(file("version.txt")).asText

12. Use Lazy Task Configuration

Avoid create(), use register():

// BAD: Eagerly configured
tasks.create("myTask") { ... }

// GOOD: Lazily configured
tasks.register("myTask") { ... }

---

Common Bottleneck Analysis

Slow Configuration Phase

Symptoms: Build scan shows long "Configuring build" time

Causes & Fixes:

Cause	Fix
Eager task creation	Use tasks.register() instead of tasks.create()
buildSrc with many dependencies	Migrate to Convention Plugins with includeBuild
File I/O in build scripts	Use providers.fileContents()
Network calls in plugins	Cache results or use offline mode

Slow Compilation

Symptoms: :app:compileDebugKotlin takes too long

Causes & Fixes:

Cause	Fix
Non-incremental changes	Avoid build.gradle.kts changes that invalidate cache
Large modules	Break into smaller feature modules
Excessive kapt usage	Migrate to KSP
Kotlin compiler memory	Increase kotlin.daemon.jvmargs

Cache Misses

Symptoms: Tasks always rerun despite no changes

Causes & Fixes:

Cause	Fix
Unstable task inputs	Use @PathSensitive, @NormalizeLineEndings
Absolute paths in outputs	Use relative paths
Missing @CacheableTask	Add annotation to custom tasks
Different JDK versions	Standardize JDK across environments

---

CI/CD Optimizations

Remote Build Cache

// settings.gradle.kts
buildCache {
    local { isEnabled = true }
    remote<HttpBuildCache> {
        url = uri("https://cache.example.com/")
        isPush = System.getenv("CI") == "true"
        credentials {
            username = System.getenv("CACHE_USER")
            password = System.getenv("CACHE_PASS")
        }
    }
}

Gradle Enterprise / Develocity

For advanced build analytics:

// settings.gradle.kts
plugins {
    id("com.gradle.develocity") version "3.17"
}

develocity {
    buildScan {
        termsOfUseUrl.set("https://gradle.com/help/legal-terms-of-use")
        termsOfUseAgree.set("yes")
        publishing.onlyIf { System.getenv("CI") != null }
    }
}

Skip Unnecessary Tasks in CI

# Skip tests for UI-only changes
./gradlew assembleDebug -x test -x lint

# Only run affected module tests
./gradlew :feature:login:test

---

Android Studio Settings

File → Settings → Build → Gradle

• Gradle JDK: Match your project's JDK
• Build and run using: Gradle (not IntelliJ)
• Run tests using: Gradle

File → Settings → Build → Compiler

• Compile independent modules in parallel: ✅ Enabled
• Configure on demand: ❌ Disabled (deprecated)

---

Verification Checklist

After optimizations, verify:

• Configuration cache enabled and working
• Build cache hit rate > 80% (check build scan)
• No dynamic dependency versions
• KSP used instead of kapt where possible
• Parallel execution enabled
• JVM memory tuned appropriately
• CI remote cache configured
• No configuration-time I/O

---

References

• Optimize Build Speed
• Gradle Configuration Cache
• Gradle Build Cache
• Migrate from kapt to KSP
• Gradle Build Scans