ahaodev/gradle-build-performance

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("androidx.room:room-compiler:2.6.1")

// After (fast)
ksp("androidx.room:room-compiler:2.6.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