Gradle Core Concepts

A Gradle project is recognised by the gradlew and gradlew.bat scripts in its root directory. For tidepool the files that Gradle itself reads are these (the source files of the three modules are omitted):

(The tree was written from find output; the ... lines stand for the Java packages.) Running a build also creates two directories next to the settings file that must not be committed: .gradle/ (project-specific caches, including the configuration cache) and build/ (the outputs of the root project; every subproject has its own build/ too). What each file is for:

Source: Gradle User Manual: Gradle Basics, Project structure

The settings file is a script, the first one Gradle evaluates. It gives the root project a name, declares where dependencies come from for the whole build and includes the subprojects.

rootProject.name overrides the default, which would be the name of the directory. include creates one project per name, and the name is also the directory that holds the project. With FAIL_ON_PROJECT_REPOS, a build script that declares its own repositories makes the build fail, which keeps all repository declarations in this one place. In Maven the same job is split between the parent POM’s <modules> and <repositories>; the Gradle equivalent of a <module> entry is include. The details of settings files are on the later page Settings & Build Scripts.

projects shows what Gradle made of this file. With Gradle 9.8.1 and the Kotlin DSL (the Groovy DSL printed the same text):

Projects are identified by a path: : is the root project, and :tidepool-cli is the subproject of that name. The first line of the output and the line Configuring : are explained in the section on the build phases below.

Source: Gradle User Manual: Settings File Basics

Each subproject has a build script that applies plugins and declares dependencies. The scripts use the version catalog, so no version number appears in them.

The catalog is a TOML file and is the same for both DSLs; the build scripts of the two other subprojects follow.

The plugins {} block applies the plugins. java-library adds the compile, test and jar tasks and the api and implementation configurations; application adds run, startScripts and the distribution tasks (distZip, distTar) on top of the Java plugin. A dependency written as api(project(":tidepool-model")) is a project dependency: it makes Gradle build tidepool-model first and put its JAR on the compile classpath of tidepool-engine and of everything that depends on tidepool-engine. implementation keeps a library off the compile classpath of consumers (so tidepool-cli sees Commons CSV only at run time). Dependencies are declared in more detail on Declaring Dependencies & Configurations and the catalog on Version Catalogs; Maven’s counterparts are described on Dependencies, Scopes & Mediation.

The root script has a different job: it holds what is common to the whole build and the tasks that belong to the build itself. It is the next section’s subject.

Source: Gradle User Manual: Build File Basics

gradle.properties supplies build settings. The one in the example turns on the configuration cache, which is why the outputs on this page say Configuration cache entry stored. and Reusing configuration cache.:

Every org.gradle.* property is covered on Build Environment & Properties. The configuration cache is off by default in Gradle 9.8.1 (making it the default is announced for Gradle 10, not released); Gradle 9.0 made it the preferred mode, and Gradle 8.1 made it stable. The examples on this page are compatible with it, except for the one that is shown failing on purpose.

Gradle does not execute tasks in the order in which they are written. It collects the requested tasks and everything they depend on into a directed acyclic graph and runs each task after its dependencies. --dry-run prints that order without executing any action:

Reading it from the bottom: release needs distZip, which needs startScripts and the jar of the CLI, which needs the compiled classes, which need the jars of tidepool-engine and tidepool-model, because the CLI depends on the engine and the engine’s api dependency on the model puts the model on the CLI’s compile classpath too. Nothing connects checkStations to the compilation, so Gradle is free to run them in any order (and with --parallel, at the same time); the order of independent tasks can differ between runs and between the two DSL runs.

Running the task, with the entry that --dry-run stored in the configuration cache:

The suffix after a task name says what Gradle did with it: no suffix means the task ran, NO-SOURCE means its inputs were empty and it was skipped (there is no src/main/resources), and the next run shows UP-TO-DATE for tasks whose inputs and outputs did not change:

checkStations has no declared inputs or outputs, so Gradle cannot tell that it need not run and always runs it; it is the one executed task of 9 actionable tasks: 1 executed, 8 up-to-date. release and the classes tasks are lifecycle tasks with no actions of their own: they are not counted among the actionable tasks, and release shows no outcome label at all. Declaring inputs and outputs is the subject of Incremental Build, the tasks themselves of Tasks and Writing Custom Tasks. The Maven counterpart of a task is a plugin goal, which Maven binds to a fixed lifecycle phase (Maven Build Lifecycle); the Ant counterpart is a target with a depends list (Ant Targets & Extension Points). The difference is that Gradle’s graph is built from the dependencies it discovers, including those between the projects, not from a lifecycle that was fixed in advance.

Running the application is also a task. The application plugin’s run task takes its arguments from --args, and the working directory is the project directory of tidepool-cli, hence the ..:

(-q suppresses the task lines, but not the println of the root script.)

Source: Gradle User Manual: Gradle Basics, Core concepts

Because the cache stores the task graph and the state of the tasks, the objects a task action refers to must be serialisable. A script-level variable is not. This version of the root script, written the obvious way, keeps the file reference in a variable of the script and uses it in the action:

With org.gradle.configuration-cache=true in gradle.properties, Gradle 9.8.1 runs the tasks and then fails the build when it tries to store the entry (the same shape in the Groovy DSL, with a def variable, was run too and succeeded, because a def in a Groovy script is a local variable of the script’s run method and is captured on its own; the problem is specific to the Kotlin script’s property):

(The lines for the report location and the generic hints were left out.) The fix is the form used in the example above: read the value into a local val inside the registration block, so that the action captures only the file reference, not the script. The configuration cache is the subject of Configuration Cache & Isolated Projects.

Source: Gradle User Manual: Configuration Cache Requirements, reducing captured references in ad-hoc tasks, Script-level variable capture (Kotlin DSL)