Knowledge Map
Gradle
Every keyword from basic builds to custom plugins and optimisation internals — with a plain-English sentence on what each one does.
168
Concepts
20
Groups
112
Must-know
Fundamental
Core concepts, files, tasks, dependencies & Android DSLBuild Script
The file (build.gradle or build.gradle.kts) where you configure how a project or module gets compiled and packaged.
Project
Gradle's top-level object representing a module — every build.gradle file belongs to exactly one Project.
Task
A single unit of work Gradle can run — like compiling code, running tests, or packaging a JAR.
Plugin
A bundled set of tasks and configuration that extends Gradle — the Android plugin adds compileDebug, assembleRelease, etc.
Build Lifecycle
The three fixed phases Gradle always runs in order: Initialization, Configuration, then Execution.
Initialization Phase
Gradle reads settings.gradle to discover which projects exist and sets up the Project hierarchy.
Configuration Phase
Every build script runs top-to-bottom and all tasks are registered and wired together — nothing executes yet.
Execution Phase
Only the tasks that are actually needed run in dependency order — skipped tasks report UP-TO-DATE.
Groovy DSL vs Kotlin DSL
Two languages for writing build scripts — .gradle uses Groovy, .gradle.kts uses Kotlin with type safety and autocomplete.
settings.gradle(.kts)
The root file that tells Gradle the project name and which submodules (app, library, etc.) to include in the build.
build.gradle(.kts)
The build script for a single module — defines plugins, dependencies, and compilation settings for that module.
gradle.properties
A flat key-value file for build-wide settings like JVM heap size, Android flags, or custom project variables.
local.properties
Machine-specific file (gitignored) that stores the SDK path and any secrets that shouldn't be committed.
gradle-wrapper.properties
Pins the exact Gradle version the project uses so every developer and CI machine builds with the same tooling.
gradlew / gradlew.bat
Shell scripts that download and run the pinned Gradle version — always use these instead of a locally installed Gradle.
libs.version.toml
The Version Catalog file — a central place to declare all dependency versions so every module reads from one source.
.gradle/ cache
Gradle's local cache folder storing downloaded dependencies and task output — safe to delete to force a fresh build.
dependencies {}
The block in build.gradle where you declare every library your module needs, along with the configuration it belongs to.
implementation
Adds a library to your module for compilation and runtime but hides it from modules that depend on you — the default choice.
api
Like implementation but also exposes the library to any module that depends on you — use sparingly in library modules.
testImplementation
A dependency only available during unit tests — it's stripped from the final APK entirely.
androidTestImplementation
A dependency only for instrumented tests that run on a device or emulator — not included in the release build.
compileOnly
Available at compile time but not bundled into the output — used for annotation processors or provided-at-runtime libs.
runtimeOnly
Not available at compile time but included at runtime — useful when a library is only needed for its runtime side effects.
kapt / ksp
Kotlin annotation processing tools — kapt is the older Kotlin-apt bridge, ksp is the faster modern replacement.
Transitive Dependencies
Libraries that your direct dependencies pull in automatically — they appear in your build even though you didn't declare them.
BOM (Bill of Materials)
A special dependency that aligns all versions of a library family (like Firebase or Compose) so they're always compatible.
repositories {}
The block declaring where Gradle should look for dependencies — Gradle searches them top to bottom until it finds the artifact.
google()
Google's Maven repository — required for all Android, Jetpack, and Firebase libraries.
mavenCentral()
The main public repository for open-source JVM libraries — the successor to the old jcenter().
maven { url }
Adds any custom Maven repository by URL — used for private registries, GitHub Packages, or Sonatype staging.
mavenLocal()
Reads from your local ~/.m2 folder — useful for testing locally published library changes before releasing them.
dependencyResolutionManagement
Centralizes repository declarations in settings.gradle so all modules share one consistent list of sources.
includeBuild()
Substitutes a published library with a local project on disk — lets you develop a library and its consumer side by side.
android {}
The top-level block added by the Android Gradle Plugin where all Android-specific build settings live.
compileSdk
The Android API level used to compile your code — sets the ceiling of APIs you can reference in source.
minSdk
The minimum Android version your app supports — devices below this version won't see your app on the Play Store.
targetSdk
The API level your app was tested and designed for — affects which runtime behaviours Android applies to your app.
defaultConfig {}
Shared configuration that applies to all build variants — applicationId, versionCode, versionName, and test runner.
applicationId
Your app's globally unique identifier on the Play Store and device — changing it creates a completely new app listing.
versionCode
An integer the Play Store uses to compare app versions — must increase with every release you upload.
versionName
The human-readable version string shown to users — follows SemVer like "2.1.0" but is not enforced by the store.
namespace
The package namespace for the generated R class and BuildConfig — decoupled from applicationId since AGP 7.3.
buildTypes {}
Defines named build configurations — debug and release come built-in, but you can add staging, qa, etc.
debug
The default development build type — debuggable, uses a debug keystore, and has minification disabled for fast builds.
release
The production build type — minification enabled, signed with your release keystore, and optimized for size and speed.
productFlavors {}
Defines app variants with different code or resources — commonly used for free vs paid, or dev vs production backends.
Build Variant
The combination of a product flavor and build type — e.g. freeDebug or paidRelease — each is a separately buildable target.
flavorDimensions
Named axes for product flavors — lets you combine flavors from multiple dimensions like tier + environment.
buildConfigField
Injects a typed constant into the generated BuildConfig class so you can change values per build type or flavor.
resValue
Generates an Android resource value (string, bool, int) at build time — useful for variant-specific strings or URLs.
applicationIdSuffix
Appends a string to the applicationId for a build type — lets you install debug and release side by side on one device.
Intermediate
Tasks, signing, modules, build optimisation & Version CatalogTask Registration
tasks.register("myTask") is the lazy way to declare a task — it's only created if actually needed during the build.
dependsOn
Declares that one task must complete before another — the primary way to wire tasks into a dependency chain.
finalizedBy
Runs a second task after the first finishes, even if the first failed — great for cleanup or report generation.
mustRunAfter / shouldRunAfter
Controls execution order when two tasks both run without forcing one to trigger the other.
inputs / outputs
Declaring what a task reads and writes lets Gradle skip it entirely when nothing has changed — the basis of UP-TO-DATE.
UP-TO-DATE
Gradle's skip signal — a task reports this when its inputs and outputs haven't changed since the last run.
doFirst {} / doLast {}
Adds an action block that runs at the very start or very end of an existing task without replacing its main logic.
TaskProvider<T>
A lazy handle to a registered task — Gradle only configures the task when you actually call .get() or it runs.
Task Graph
The directed acyclic graph of all tasks and their dependencies that Gradle resolves before execution begins.
Lifecycle Tasks
Umbrella tasks like assemble, build, check, and clean that group related tasks under a single convenient entry point.
Incremental Build
Gradle skips tasks whose inputs and outputs haven't changed — reducing full rebuilds to only what actually needs rerunning.
Build Cache
Stores task outputs by a fingerprint of their inputs — lets Gradle restore results from a previous run or another machine.
Configuration Cache
Serializes the entire task graph after configuration so the configuration phase can be skipped on subsequent builds.
Parallel Execution
Runs independent tasks simultaneously across CPU cores — enabled with org.gradle.parallel=true in gradle.properties.
Lazy Configuration
Only configuring tasks when they're actually needed — avoids wasting time setting up tasks that will never run.
org.gradle.daemon
A long-running background process that keeps the JVM warm between builds — dramatically cuts startup overhead.
org.gradle.jvmargs
Sets the JVM heap size for the Gradle daemon — increase -Xmx for large projects to avoid out-of-memory build failures.
--build-cache flag
Enables the build cache for a single run from the command line without changing gradle.properties permanently.
Build Scan
An online report of every detail of a build — task timings, dependencies, and test results — hosted on scans.gradle.com.
What is the Configuration Cache
Gradle stores the configured task graph so later builds can skip the configuration phase entirely.
Enabling it
Set org.gradle.configuration-cache=true in gradle.properties to turn it on for the project.
Compatibility problems
Build logic and plugins must be configuration-cache safe or Gradle will report incompatible access patterns.
--configuration-cache flag
Use the command-line flag to test behavior without permanently enabling it in project properties.
--rerun
Force reconfiguration and task reruns when you need to bypass stale cache effects during troubleshooting.
Isolated Projects
A deeper optimization model that configures each project in isolation for stronger parallelism guarantees.
Build cache vs Configuration cache
Build cache stores task outputs, while configuration cache stores the configured graph and task wiring.
signingConfigs {}
Declares a named signing identity — keystore path, alias, and passwords — that build types reference to sign APKs or AABs.
storeFile / storePassword
The path to the JKS keystore file and its password — never hardcode these; read them from environment variables or local.properties.
keyAlias / keyPassword
The name and password of the specific key entry inside the keystore — an app can have multiple keys in one store.
maven-publish plugin
The standard Gradle plugin for publishing library artifacts to a Maven repository — local or remote.
publishing {}
Configures what gets published (the artifact) and where it goes (the repository) inside the maven-publish plugin.
MavenPublication
Describes a single publishable artifact — its group, artifactId, version, and any attached sources or javadoc JARs.
signing plugin
Signs published artifacts with a GPG key — required by Maven Central before any library can be publicly released.
AAB vs APK task
bundleRelease produces an AAB for the Play Store; assembleRelease produces a classic APK for direct distribution.
include()
Registers a submodule in settings.gradle — Gradle won't discover or build a module unless it's listed here.
project(":module")
References another module as a dependency — Gradle then builds that module first if its output is needed.
subprojects {}
A block in the root build.gradle that applies configuration to every submodule at once — avoid overusing it.
allprojects {}
Like subprojects but also applies to the root project — almost always better handled via convention plugins now.
Convention Plugin
A reusable Gradle plugin in the build-logic module that replaces repeated allprojects/subprojects configuration.
build-logic module
A special Gradle module containing convention plugins that the rest of the project's modules apply — the modern pattern.
Composite Build
Connects separate Gradle projects together as if they were one build — replaces the old includeBuild for library dev.
project.ext
An extension map for passing custom variables between Gradle files — largely replaced by Version Catalogs and convention plugins.
libs.versions.toml
The TOML file where every dependency version, library alias, and plugin alias is centrally declared for the whole project.
[versions]
The section in the TOML file naming version strings — referenced by both libraries and plugins to stay in sync.
[libraries]
Maps short aliases (libs.retrofit) to full Maven coordinates — modules use the alias instead of the full string.
[plugins]
Aliases for Gradle plugin IDs and their versions — applied in build scripts via alias(libs.plugins.android.application).
[bundles]
Groups multiple library aliases into one bundle alias — add the whole bundle in one line instead of listing each lib.
libs.* accessor
The type-safe Kotlin DSL accessor Gradle generates from the TOML — autocomplete for every dependency alias.
versionRef
Points a library or plugin at a named version string in [versions] — change the version in one place to update everywhere.
com.android.application
The AGP plugin for an app module — adds Android-specific tasks like packaging the APK, merging manifests, and dexing.
com.android.library
The AGP plugin for a library module — produces an AAR artifact instead of an APK for other modules to consume.
com.android.dynamic-feature
The plugin for a Play Feature Delivery module that can be downloaded on-demand after install.
compileOptions {}
Sets the Java source and target compatibility — use VERSION_17 for modern projects to unlock the latest language features.
kotlinOptions {}
Configures the Kotlin compiler inside AGP — set jvmTarget to match your compileOptions Java version.
buildFeatures {}
Toggles optional AGP features like ViewBinding, DataBinding, Compose support, and BuildConfig generation.
sourceSets {}
Configures where Gradle looks for source files and resources — lets you add extra source directories to a variant.
aaptOptions {}
Configures the Android Asset Packaging Tool — control resource crunching, ignored patterns, and more.
packagingOptions {}
Handles duplicate file conflicts when merging JARs — use pickFirst, exclude, or merge to resolve clashes.
Advanced
Custom plugins, code quality, dependency management & CIPlugin interface
The Gradle interface you implement with a single apply(Project) method to add tasks and config to any project.
buildSrc
A special directory Gradle automatically compiles before the main build — the old home for shared build logic and plugins.
PrecompScript Plugin
A convention plugin written as a plain .gradle.kts file in build-logic — simpler than a full Plugin class for most cases.
Extension
A configuration object you add to the Project so users of your plugin can configure it via a named DSL block.
project.extensions.create()
Registers your custom Extension object so build scripts can configure your plugin using a typed DSL block.
DefaultTask
The base class to extend when writing a custom task — gives you input/output wiring and action infrastructure.
@InputFile / @OutputFile
Annotations on task properties that tell Gradle exactly what a task reads and writes for incremental build tracking.
@TaskAction
Marks the method in a custom task class that Gradle should call when the task is executed.
Worker API
Runs task work in isolated workers — enables true parallelism within a single task and classloader isolation.
Plugin publishing
Pushes your custom plugin to the Gradle Plugin Portal so any project in the world can apply it by ID.
includeBuild()
In settings.gradle.kts, includes another Gradle build so it participates as part of the current build graph.
Local substitution
Composite builds automatically substitute dependency coordinates with local projects for fast library iteration.
--include-build flag
Temporarily include an external build from the CLI without changing settings files.
Shared convention plugins
Host shared build logic in a build-logic project and include it via includeBuild("build-logic").
Composite vs buildSrc
buildSrc is an implicit composite; explicit build-logic composites are preferred for scalability and isolation.
Dependency cycles
Composite participants must form an acyclic graph or Gradle fails the build with cycle errors.
Dependency Conflicts
When two libraries need different versions of the same dependency — Gradle picks the highest by default.
force
Forces every configuration to use a specific version of a dependency regardless of what any library requests.
exclude()
Drops a specific transitive dependency from a library — use it when a pulled-in library conflicts with another.
resolutionStrategy {}
A block for fine-grained control over how Gradle resolves version conflicts, forces versions, or fails on dynamic versions.
dependencyInsight task
A built-in task (./gradlew dependencyInsight) that explains exactly why a specific version of a library was chosen.
dependencies task
Prints the full resolved dependency tree for every configuration — use it to hunt for version conflicts or unexpected transitive libs.
Capability Conflict
When two different libraries provide the same capability — Gradle fails the build and asks you to choose one explicitly.
Rich Version
Declares a dependency with strict, preferred, and rejected version ranges instead of a single pinned version.
Component Metadata Rule
Patches the metadata of a published artifact — adds missing capabilities, fixes wrong variants, or corrects bad POM files.
Lint
Android's static analysis tool — catches bugs, performance issues, and accessibility problems before the app runs.
lintOptions {}
Configures which lint checks are errors vs warnings, which to ignore, and whether to fail the build on lint errors.
Detekt
A Kotlin static analysis plugin that enforces code style, detects code smells, and measures complexity.
Ktlint
A Kotlin formatter and linter that enforces consistent code style — can auto-fix most violations with --format.
JaCoCo
A code coverage plugin that measures how much of your code is exercised by tests and generates HTML reports.
Spotless
A multi-language formatter plugin that applies Ktlint, Google Java Format, or custom rules in one place.
SonarQube / SonarCloud
An external platform that aggregates lint, coverage, and security findings into a quality gate for CI pipelines.
Dependency Guard
Snapshots your resolved dependency list and fails the build if any dependency changes unexpectedly — prevents supply chain drift.
R8
The compiler that shrinks, obfuscates, and optimizes your code in one pass — replaces the older ProGuard tool.
minifyEnabled
Turns on R8 for a build type — set to true in release to shrink code, false in debug for faster builds.
shrinkResources
Removes unused drawable, layout, and string resources from the final APK — requires minifyEnabled to be on.
ProGuard rules
Configuration lines that tell R8 what not to remove or rename — critical for reflection, serialization, and third-party libraries.
-keep
A ProGuard directive that prevents R8 from removing or renaming a class or member during obfuscation.
proguard-rules.pro
Your app's custom keep rules file — add entries here when a library breaks after enabling minification.
consumer-rules.pro
Keep rules inside a library module that are automatically applied to any app that depends on that library.
Full Mode R8
An aggressive R8 mode that inlines methods across class boundaries for extra shrinking — may require more keep rules.
Gradle Wrapper in CI
Always use ./gradlew on CI — it ensures the build uses the exact Gradle version pinned in the project, not the server's.
Remote Build Cache
A shared cache server that lets CI machines restore task outputs from previous runs — dramatically cuts CI build time.
--no-daemon flag
Disables the Gradle daemon for a single run — useful on CI where ephemeral machines don't benefit from a warm daemon.
Environment Variables in Builds
Reading secrets (keystore passwords, API keys) from CI environment variables instead of committing them to the repo.
--stacktrace / --info
Debug flags that print full exception traces or verbose logging — essential for diagnosing cryptic CI build failures.
Gradle Enterprise
Develocity's commercial platform offering remote build caching, build scan history, and predictive test selection.
Test Distribution
Splits test execution across multiple agents in parallel — drastically reduces test suite runtime on CI.
Dependency Verification
Gradle checks each downloaded artifact against a checksum manifest to guard against tampered or corrupted libraries.
Toolchains
Tells Gradle to automatically download and use a specific JDK version for compilation, regardless of the developer's installed JDK.
Configuration
A named group of dependencies (like implementation or testRuntimeClasspath) — Gradle resolves each configuration independently.
Artifact Transform
A pipeline step that converts an artifact from one type to another — e.g. transforming a JAR into a dex file on the fly.
Variant Aware Resolution
Gradle selects the correct variant of a library (debug AAR vs release AAR) based on attributes like build type and ABI.
Attribute
A typed key-value pair attached to configurations and variants — Gradle matches them during resolution to pick the right artifact.
GradleProperty<T>
A lazy, connectable value holder for task inputs/outputs — supports mapping and flat-mapping without eagerly resolving.
FileCollection
A lazy set of files that Gradle evaluates only when needed — used for task inputs that resolve at execution time.
NamedDomainObjectContainer
A container for named, configurable objects — how buildTypes, productFlavors, and sourceSets are stored internally.
Isolated Projects
An experimental Gradle mode that prevents build scripts from accessing other project state — required for true parallelism.
No concepts found matching your search.