Gradle Java Projects

Setting a property replaces its value; calling the matching method adds to it. That distinction, setSrcDirs against srcDir in the Kotlin DSL (srcDirs = against srcDir in the Groovy DSL), is the way to read most of the source set API. A legacy project whose sources live in src/java instead of src/main/java is described to Gradle like this:

Both versions were run after moving the model’s sources to tidepool-model/src/java/io/tidepool/model (tests stay in src/test/java):

The build compiled the classes into the usual build/classes/java/main regardless of where the sources were. Adding a directory next to the default one uses srcDir("thirdParty/src/main/java"). A source set exists to give a set of sources its own classpath and its own output, so the guidance of the user manual is: if the sources need a unique classpath, produce classes that are handled differently from main and test, and are a natural part of the project, define a source set; generated sources that belong in the production JAR are better added to main (with the compile task depending on the generator).

Source: Gradle User Manual: Customizing file and directory locations, Compiling independent sources separately

Resources need no configuration at all: files in src/main/resources are copied by processResources into build/resources/main and packed into the JAR, and the task has no sources (NO-SOURCE in the listings below) when the directory is absent. Replacing tokens in resource files uses the expand and filter methods of the Copy family described on Working with Files; the Maven equivalent, resource filtering, is on Maven Resources & Filtering.

Three settings answer the question, with very different guarantees, and mixing them up is the classic Java-on-Gradle bug.

When nothing is configured, the compiler targets the language level of the JVM that runs Gradle (the javac behaviour with no flag). The model compiled with its options.release line removed produced Java 26 class files on this machine’s JDK 26 (major version: 70):

Source: Gradle User Manual: Targeting a specific Java version, Using Java release version, Using Java compatibility options

The difference between release and the compatibility properties shows with one line of code. List.reversed() exists since Java 21. A class in the model that calls it:

compiled with the compatibility properties set to 17:

The build succeeded and produced Java 17 class files that call a Java 21 method. Running them on a Java 17 JVM (JetBrains Runtime 17.0.14, with a small Check.java launched with java -cp tidepool-model-1.0.0.jar Check.java) fails at the call, while the same JAR runs on JDK 26:

The first listing is the Java 17 run and the second the JDK 26 run. With options.release = 17 (both DSLs were run) the same source does not compile, which is the point of the flag:

Gradle reports compiler diagnostics where they happen (in the task output) and again under "What went wrong"; the lines cannot find symbol and symbol: method reversed() are the whole story. With --continue the errors of every failing compile task are collected in one report.

Source: Gradle User Manual: Debugging compiling errors

The release flag also protects the consumer side. The Java plugins publish the target version of every project as the attribute org.gradle.jvm.version, and a project that compiles for an older Java than a dependency refuses it. With the CLI project set to options.release = 17 while the engine stays on 21, the compile classpath cannot be resolved (both DSLs gave the same message):

The Maven counterparts are maven.compiler.release and the toolchains (see Maven Compiling & Toolchains); in Ant the attributes are release, or source and target on <javac> (see Compiling Java with Ant).

The projects pass -Xlint:all through options.compilerArgs, so every warning category of javac is on. Other options that builds commonly add are -Werror (warnings fail the build), -parameters (keep parameter names in the class files, which some frameworks and annotation processors need), options.encoding = "UTF-8" (the default of the JDK 18 and later is already UTF-8, but older JDKs use the platform charset), and options.isFork = true with options.forkOptions to compile in a separate JVM. Javac warnings are printed in the task output. Builds that printed warnings also ended with an [Incubating] Problems report is available at ... line that points to an HTML report under build/reports/problems/; that line is left out of the listings.

The Javadoc of the model is checked by doclint. The records have no @param tags, so the javadoc task in the model script switches the missing group off with addBooleanOption("Xdoclint:all,-missing", true); without it, the task prints one warning per record component and still succeeds.

Two separate features keep compilation cheap, and both look at the binary interface of classes rather than at the files.

Compile avoidance concerns consumers of a project. The compile classpath of a task is fingerprinted by the ABI of the classes on it (the part of a class that other classes can see: public and protected members, signatures, constants), and a change that does not alter the ABI does not make dependents out of date. Changing a method body, a comment, private members, a resource or the name of a JAR leaves downstream compileJava tasks UP-TO-DATE. With the java-library plugin the consumer even compiles against the classes directory of the project, so a change of a resource or the work of the jar task is not part of the compile at all.

Incremental compilation concerns one compile task. Gradle recompiles the classes affected by a change (the changed ones and the ones that depend on them, by type references in bytecode) and leaves the others in the output directory untouched.

The first change to the engine is private: a new case in the switch inside predict. Nothing is visible to the CLI, so tidepool-cli:compileJava stays up to date even though the engine was recompiled:

The second change adds a public method to TideEngine. That is a change of the ABI, so the CLI is recompiled as well:

The runs happened in this order in one project (a first compile, then the private change, then the public one). The third experiment shows the incremental compiler with --info: adding a method to the Height record in the model recompiled two classes, not four:

The lines to look for are Incremental compilation of 2 classes completed (the class that changed and the one that depends on it) and, when compilation is not incremental, Full recompilation is required because ... followed by the reason. The known reasons, from the user manual, include a changed annotation of source retention, a changed Java constant, a changed resource that an annotation processor reads, a custom executable or javaHome on the task, and the build after a compile error. The analysis is kept in the project directory and is an output of the task in the build cache.

Source: Gradle User Manual: Compilation avoidance, Incremental Java compilation, Using classes instead of jar for compilation

Maven recompiles a whole module when the compiler plugin detects a change, and Ant’s <javac> compares the time stamp of each source file with its class file; neither knows about the ABI of dependencies (see Maven Compiling & Toolchains). Both ran the same experiments in the Groovy DSL build with identical task states.

Annotation processors are the part of the compile classpath that Gradle treats as a separate world. A processor must be declared in the annotationProcessor configuration of the source set; Gradle ignores processors that are only on the compile classpath, because implementation details of a processor matter for the result of the compilation and must therefore be part of the up-to-date check. The library that holds the annotations is still declared in implementation or compileOnly, as the user manual’s Dagger example shows.

The CLI uses picocli. The picocli-codegen processor reads the @Command and @Parameters annotations at compile time and writes the reflection configuration that GraalVM native image needs. It takes the output location from an option (-Aproject), which the build passes as a compiler argument:

The listing is the result of ./gradlew :tidepool-cli:dependencies --configuration annotationProcessor (cut after the dependency tree). The processor wrote three files into the class output:

(The second listing is the head of reflect-config.json; the file continues with picocli’s own help mixin.) With -Xlint:all every compile of the CLI prints one more line:

A processor "claims" annotations by returning true from its process method. The picocli processor writes its files without claiming the annotations, so the lint check prints this line even though the processor ran; the generated files are the proof. If you do not want to see it, leave processing out of the lint categories (-Xlint:all,-processing).

Whether a processor is incremental decides how much of the compile avoidance and incremental compilation above survives. Changing Main.java in the CLI and compiling again with --info shows the reason in one line:

picocli-codegen is not incremental, so every change of a CLI source file is a full recompilation of the CLI project (which has one class). The incremental annotation processing support of Gradle applies to processors that opt in by listing themselves in META-INF/gradle/incremental.annotation.processors as isolating, aggregating or dynamic. Processors in the first category look at each annotated type on its own and generate files for it; the aggregating ones combine several types into one output, and Gradle always reprocesses all annotated files for them. All of them must create files through the Filer API, must read only annotations with class or runtime retention, and must not depend on compiler-internal types. The user manual keeps a table of the popular processors that support the feature.

Source: Gradle User Manual: Incremental annotation processing, Making an annotation processor incremental, Compilation avoidance, annotation processors

The same job in Maven is done with annotationProcessorPaths of the compiler plugin (see Maven Compiling & Toolchains), and in Ant with <compilerarg> and a processor path (see Compiling Java with Ant).

Every Jar, War and Ear task has a manifest property. The model script sets two attributes with the values of the project; the manifest of the resulting JAR is

and the file list of the JAR (class files, directories and the manifest, with the fixed time stamp explained below):

Class-Path and Main-Class attributes go into the manifest the same way, but for a program the application plugin writes start scripts and a lib directory (below), which is the form that works with any set of dependencies. Gradle writes Manifest-Version: 1.0 itself. A library that wants to be usable as an automatic module without a module-info.java should add Automatic-Module-Name, because the module name derived from the file name is unstable.

Source: Gradle User Manual: Packaging and publishing, Modifying the JAR manifest

java { withSourcesJar() } and java { withJavadocJar() } add the tasks sourcesJar and javadocJar, attach them to assemble, and publish them as the variants sourceElements and javadocElements, which is what Maven Central expects of a release (see Publishing). The libs directory of the model after a build:

The second listing is the end of the content of the sources JAR (the last rows of unzip -l). The Javadoc JAR contains the javadoc task output, with the -Xdoclint:all,-missing setting of the script.

Source: Gradle User Manual: The Java Plugin, the java extension

Since Gradle 9.0.0 all archive tasks (Jar, War, Ear, Zip, Tar) produce reproducible archives by default: the order of the entries is deterministic, every entry has a fixed time stamp (the first of February 1980 for ZIP-based archives such as JARs, as in the unzip -l output above, and the second of January 1970 for TAR archives, which tar -tvf shows for the distTar output of this build), directories have the permissions 0755 and files 0644. That is why the same sources give the same JAR. A hash taken after a build, and again after clean and a rebuild two seconds later:

The two hashes are identical. Builds that depend on the old behaviour (file order from the file system, real time stamps and permissions) can restore it per task with isReproducibleFileOrder = false, isPreserveFileTimestamps = true and useFileSystemPermissions() (the properties are called reproducibleFileOrder and preserveFileTimestamps in the Groovy DSL). In Gradle 8.14 those archives were not reproducible unless the build opted in (not run here); the Maven counterpart is project.build.outputTimestamp, see Maven Security & Reproducible Builds.

Source: Gradle User Manual: Upgrading to Gradle 9.0.0, reproducible archives, Gradle 9.0.0 release notes, Gradle User Manual: Working with Files, timestamp for files inside archives

Gradle has no built-in fat JAR; the standard answer is a Jar task that unpacks the runtime classpath into the archive. The CLI script above contains it, because the way it handles the runtime classpath is the part that breaks under the configuration cache: the classpath must be a lazy Provider (or a closure) that is evaluated at execution time, not a configurations.runtimeClasspath.get() call made while the build is being configured. The dependsOn(configurations.runtimeClasspath) line is not optional: zipTree of a JAR file carries no task dependency, so without it Gradle does not build the JARs of the other two projects first, and after a clean the task fails with Cannot expand ZIP '…/tidepool-engine-1.0.0.jar' as it does not exist (reproduced on 9.8.1). The manual’s uber JAR example has the same line.

The JAR holds the classes of the CLI, of the other two projects and of the three libraries (unzip -l counts 758 class files), and the manifest names io.tidepool.cli.Main. archiveClassifier is the right property for the -all suffix (not archiveAppendix), because the classifier is what publishing uses to tell artifacts apart. duplicatesStrategy = DuplicatesStrategy.EXCLUDE keeps the first copy of a file that appears in several JARs, which is how files such as META-INF/LICENSE collide. The recipe copies files from JARs without merging them, so it breaks on libraries that use META-INF/services files, signed JARs, or multi-release JARs; those need the Shadow plugin (a third-party plugin), or the Maven Shade plugin on the Maven side. The Maven comparison, with relocation and service-file merging, is on Uber JARs with Shade & Assembly, and the Ant one (<zipgroupfileset>) is in Packaging Archives with Ant. The question to ask first is whether a fat JAR is needed at all; the next section’s distribution is usually the better artifact for a command line program.

Source: Gradle User Manual: Packaging and publishing, uber JARs, Gradle User Manual: Working with Files, creating uber or fat JARs

run is a JavaExec task with the runtime classpath of main. Arguments go through --args, which keeps the command line free of Gradle’s own option parsing:

The working directory of run is the project directory of the CLI, which is why the data file is ../data/stations.csv. A failing program makes the build fail with the exit code of the process, and the output of the program comes before Gradle’s message:

(The first line is the program’s own message on the error stream.) ./gradlew run --debug-jvm starts the JVM suspended with the debug agent listening, which is how an IDE debugger attaches. run can be reconfigured like any task, for example tasks.run { args("..."); workingDir = ...; jvmArgs(...) }. With a toolchain configured in the java extension (see Gradle Toolchains), run uses the toolchain’s JVM, not the one that runs Gradle.

Source: Gradle User Manual: The Application Plugin, building JVM applications, Tasks

installDist produces a directory that can be copied anywhere, and it contains no Gradle:

The lib directory holds the project JAR, the JARs of the two other projects and the libraries from the runtime classpath, the bin directory holds the two scripts, and data is the file added by the distributions block. distZip packs exactly this tree below a directory named after the distribution and its version:

The script sets the CLASSPATH to the JARs of lib in the order of the runtime classpath, takes the default JVM options from the application block, lets users add options through two environment variables (JAVA_OPTS and, here, TIDEPOOL_OPTS, which is the upper-cased application name with _OPTS), finds Java through JAVA_HOME or the java on the PATH, and passes all arguments to the main class. The relevant lines of the generated Unix script:

Running the installed script from the distribution directory, with the data file that ships in it. The JVM options of the first run set an English locale through JAVA_OPTS, the same mechanism a user would use for a heap setting; the second run shows the program’s own error path and its exit status:

(Both lines of program output were produced by those two commands in this order; the third line is the exit status that the shell printed.) The start scripts are generated from templates under the Apache 2.0 licence, and the startScripts task accepts custom templates. The Windows template was reworked in Gradle 9.5.0 (not run here, because no Windows machine was involved), so a build that customizes it or calls gradlew.bat from another batch file should read the upgrade notes.

Source: Gradle User Manual: The Application Plugin, Tasks, The distribution, Customizing start script generation, Application extension

The Maven counterpart is a runnable JAR with a lib directory built by the JAR and dependency plugins, or the Assembly plugin (see Maven Packaging: JARs, WARs & Manifests); in Ant it is a <jar> with a Class-Path plus a hand-written script (see Packaging Archives with Ant). The shared view of publishing and distribution formats is on Repositories & Publishing Across Tools.