Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท Plugins

The Java, Java Library and Application Plugins

Learn what the Gradle java, java-library and application plugins add: source sets, task lifecycle, api versus implementation, toolchains, jar and run tasks.

If you build JVM software with Gradle, you will almost always apply one of three core plugins: java, java-library or application. They are layered. java gives you compilation, testing and jars. java-library adds the api configuration for libraries that expose types to other projects. application adds run and distribution tasks for programs with a main method.

This lesson explains what each plugin contributes, how source sets and the task graph fit together, and when to use api instead of implementation. The overview of plugins is a good warm-up if you have not read it.

The real Gradle cannot run on this site. Build files are shown read-only; the Java programs marked "stand-in" run on the site and model the ideas.

The java plugin

Kotlin
plugins {
    java
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.11.4")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.test {
    useJUnitPlatform()
}

Applying java creates two source sets by convention:

Source set Folder Purpose
main src/main/java, src/main/resources production code
test src/test/java, src/test/resources tests

For each source set Gradle creates tasks and configurations named after it: compileJava, processResources, classes, compileTestJava, test. The jar task packs main into build/libs/<name>-<version>.jar, and build depends on both assemble (make the outputs) and check (verify them, including test).

The toolchain block tells Gradle which JDK to compile with, independent of the JDK that runs Gradle. If it is not installed, Gradle can download a matching one when a resolver plugin is configured. This keeps builds reproducible across developer machines and CI.

The task lifecycle as a graph

flowchart LR
    A[compileJava] --> B[processResources]
    B --> C[classes]
    C --> D[jar]
    C --> E[compileTestJava]
    E --> F[test]
    D --> G[assemble]
    F --> H[check]
    G --> I[build]
    H --> I

Tasks are nodes; the arrows say "must run before". Gradle runs only what the requested task needs.

If you run ./gradlew test, Gradle runs compileJava, processResources, classes, compileTestJava and test, and skips jar. If you run ./gradlew build, it runs everything. This ordering is a directed acyclic graph; the stand-in below sorts one.

Java Stand-in: ordering a task graph

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Compare the three lines: jar never appears in the plan for test. That is Gradle's "run only what is needed" rule.

The application plugin

Kotlin
plugins {
    application
}

application {
    mainClass = "com.example.App"
    applicationDefaultJvmArgs = listOf("-Xmx256m")
}

It adds:

  • run: compiles and starts the main class (./gradlew run --args="hello"),
  • distZip and distTar: archives with start scripts for Linux/macOS and Windows plus all runtime jars,
  • installDist: the same layout unpacked in build/install/<name>/, handy for testing the scripts.

The application plugin applies java for you.

The java-library plugin and api vs implementation

Use java-library for code that other projects depend on. It creates the api configuration, so you can decide what leaks into the compile classpath of consumers.

Kotlin
plugins {
    `java-library`
}

dependencies {
    api("org.apache.commons:commons-lang3:3.17.0")     // exposed in public signatures
    implementation("com.google.guava:guava:33.4.0-jre") // internal detail
}

Rule of thumb: if a type from a library appears in a public method signature, field or superclass of your module, declare it api. Otherwise use implementation. The benefits of implementation:

  • consumers do not see the library on their compile classpath, so they cannot accidentally depend on it,
  • changing an internal dependency does not force consumers to recompile,
  • builds are faster.

Both end up on the runtime classpath of consumers either way.

Java Stand-in: what consumers can see

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Other settings you will use

  • java { withSourcesJar(); withJavadocJar() } adds sourcesJar and javadocJar, which publishing needs (see publishing to Maven).
  • tasks.withType<JavaCompile> { options.encoding = "UTF-8"; options.compilerArgs.add("-Xlint:all") } configures every compile task.
  • sourceSets { create("integrationTest") { ... } } creates an extra source set; the test suites lesson uses a higher-level API for that.
  • tasks.jar { manifest { attributes("Main-Class" to "com.example.App") } } makes a runnable jar, though the application plugin plus distZip is usually better.

Common mistakes

  1. Using compile or runtime. These configurations were removed in Gradle 7. Use implementation, api, runtimeOnly, compileOnly.
  2. Everything is api. It works but slows rebuilds and leaks internals.
  3. Missing mainClass. run fails with "mainClass is not set".
  4. Forgetting useJUnitPlatform(). JUnit 5 tests silently do not run.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which task do you get from the application plugin but not from plain java?

    application adds run, installDist, distZip and distTar. compileJava, jar and test come from the java plugin.
  2. 2. When must a dependency be declared with api?

    api exposes the dependency to consumers' compile classpath. It is needed when public signatures use its types. Otherwise implementation hides it.
  3. 3. Running ./gradlew test, which of these tasks does NOT run?

    test needs compiled classes and test classes, but not a packaged jar, so Gradle skips jar.
  4. 4. What is the purpose of the java toolchain block?

    A toolchain makes builds reproducible by pinning the Java language version for compilation and tests.

Summary

  • java gives you source sets (main, test), compilation, test, jar, build.
  • application adds run and distribution tasks; java-library adds api.
  • Use api only for dependencies visible in your public API; default to implementation.
  • Tasks form a graph, and Gradle runs just the tasks a request needs.
  • Pin the JDK with a toolchain.

Next: Writing custom plugins