A Gradle script is a program, not a fixed data layout: Groovy or Kotlin code run against an object that Gradle supplies. What makes it a recognisable file format is the set of file names, the object each script configures and the standard blocks and notations, listed here. The plain-text files beside the scripts are on the properties, catalog and wrapper page.
Sources: the Gradle User Manual (current, Gradle 9) chapters Build Lifecycle, Settings File Basics, Init Scripts, Migrating build logic from Groovy to Kotlin, Using Plugins, Centralizing Repositories, The Java Library Plugin, Declaring Dependencies, Declaring Versions and Declaring Repositories; the DSL reference pages for Project and Settings.
Script kinds
| File | Configures | When it runs |
|---|---|---|
Init scripts: -I/--init-script files, $GRADLE_USER_HOME/init.gradle(.kts), *.init.gradle(.kts) in $GRADLE_USER_HOME/init.d/ and $GRADLE_HOME/init.d/ | The Gradle object | First, in the initialisation phase, before the settings file. All found scripts run, those in one folder alphabetically. |
settings.gradle, settings.gradle.kts | A Settings object | Initialisation phase, before any build script. Optional for a single project, required for a multi-project build. Normally in the root folder. |
build.gradle, build.gradle.kts | A Project object | Configuration phase, one per participating project. |
Groovy scripts end .gradle, Kotlin scripts .gradle.kts; a
multi-project build may mix the two by project. After configuration, the execution
phase runs the selected tasks.
Groovy and Kotlin
| What | Groovy DSL | Kotlin DSL |
|---|---|---|
| Strings | single or double quotes | double quotes only |
| Method calls | parentheses may be left out | parentheses always |
| Property assignment | = may be left out | = always |
| Extra properties | ext | extra |
Build script blocks
Script blocks of the Project object:
| Block | Configures |
|---|---|
plugins { } | Plugins: id("…"), with version "…" for plugins that must be resolved, and optional apply false (declare without applying). Must come before any other block; Kotlin may name core plugins directly (java, `java-library`). |
buildscript { } | The build script’s classpath. |
repositories { } | The project’s repositories; see repositories. |
dependencies { } | The project’s dependencies; see configurations. |
configurations { } | The dependency configurations. |
artifacts { } | The project’s published artifacts. |
allprojects { } | This project and each of its sub-projects. |
subprojects { } | The sub-projects. |
ant { } | The project’s AntBuilder (deprecated). |
Gradle’s own plugins add the blocks application,
checkstyle, codenarc, distribution,
eclipse, idea, jacoco, java,
pmd, publishing, signing,
visual-studio and xcode.
Project properties: allprojects, ant,
artifacts, buildDir, buildFile,
buildscript, childProjects, configurations,
defaultTasks, dependencies, dependencyLocking,
description, extensions, gradle,
group, layout, logger, logging,
name, normalization, parent, path,
pluginManager, plugins, project,
projectDir, properties, repositories,
resources, rootDir, rootProject,
state, status, subprojects,
tasks, version.
Settings script
| Entry | Meaning |
|---|---|
pluginManagement { } | Plugin resolution settings; must be the first block in the file. |
plugins { } | Settings plugins (the block is allowed in settings files). |
rootProject.name | Name of the root project; there is one root project per build. |
include(…) | Adds projects by hierarchy path, : separating levels. |
includeFlat(…) | Adds projects by name, relative to the root project’s parent folder. |
includeBuild(…) | Adds a build to the composite build. |
dependencyResolutionManagement { repositories { } } | Repositories for every project (incubating), with repositoriesMode: PREFER_PROJECT (default; a project’s own repositories win), PREFER_SETTINGS (settings win; project repositories give a warning) or FAIL_ON_PROJECT_REPOS (a project repository is a build error). |
buildCache | Build cache configuration. |
caches | Settings for caches in the user home (incubating). |
apply | Applies plugins or scripts. |
Dependency configurations
Those of the java and java-library plugins. Declarable ones
are written in dependencies { }; resolvable ones are the classpaths built
from them; consumable ones are what other projects receive.
| Configuration | Kind | Role |
|---|---|---|
api | declarable | Exposed to consumers for both compilation and run time. |
implementation | declarable | Internal: kept off consumers’ compile classpath but available at run time. |
compileOnly | declarable | Needed only to compile. |
compileOnlyApi | declarable | Needed to compile this library and its consumers, not at run time. |
runtimeOnly | declarable | Needed only at run time. |
testImplementation | declarable | For compiling tests. |
testCompileOnly | declarable | Only for compiling tests. |
testRuntimeOnly | declarable | Only for running tests. |
annotationProcessor | declarable | Annotation processors used during compilation. |
compileClasspath, runtimeClasspath | resolvable | Main code’s compile and run classpaths. |
testCompileClasspath, testRuntimeClasspath | resolvable | Test code’s compile and run classpaths. |
apiElements, runtimeElements | consumable | What consumers need to compile against and to run with the library. |
Dependency notation
| Form | Example |
|---|---|
Module string group:name:version | implementation("org.codehaus.groovy:groovy:3.0.5") |
| Another project in the build | implementation(project(":utils")) |
| Files | runtimeOnly(files("libs/a.jar", "libs/b.jar")), runtimeOnly(fileTree("libs") { include("*.jar") }) |
| Version catalog entry | implementation(libs.guava) (see the catalog) |
Version forms
| Form | Example | Meaning |
|---|---|---|
| Exact | 1.3, 1.3.0-beta3 | That version. |
| Prefix | 1.+, 1.3.+, + | Any version starting so; + alone, any version. |
| Maven-style range | [1.0,), [1.1, 2.0), (1.2, 1.5] | [ ] inclusive, ( ) exclusive, missing bound unbounded; reversed brackets also exclude: ]1.2, 1.5] = (1.2, 1.5], [1.1, 2.0[ = [1.1, 2.0). |
| Latest status | latest.release, latest.integration | Highest version with that status. |
| Rich version | version { strictly("[1.7, 1.8["); prefer("1.7.25") } | strictly (also written 1.7.15!!; strongest, may downgrade), require (minimum that may be raised), prefer (softest), reject (excluded versions). |
Repositories
| Call | Repository |
|---|---|
mavenCentral() | Maven Central, https://repo.maven.apache.org/maven2/. |
google() | Google’s Maven repository, https://maven.google.com/, with Android artifacts. |
gradlePluginPortal() | The Gradle Plugin Portal, where plugins are looked up by default. |
mavenLocal() | The local Maven repository. |
maven { url = uri(…) } | A Maven repository at any URL or local path. |
ivy { url = uri(…) } | An Ivy repository, with a flexible module layout. |
flatDir { dirs("libs") } | Plain folders of files, with no metadata. |