Gradle Java Plugin

External

• https://docs.gradle.org/current/userguide/java_plugin.html

Internal

• Gradle Plugins

Overview

The Java plugin adds tasks to your project which will compile and unit test your Java source code, and bundle it into a JAR file. The Java plugin is convention based. This means that the plugin defines default values for many aspects of the project, such as where the Java source files are located. If you follow the convention in your project, you generally don’t need to do much in your build script to get a useful build. To use it, build.gradle must include:

apply plugin: 'java'

This is all you need to define a Java project, provided that plugin's conventions are followed.

The plugin adds "main" and "test" sourceSets, and initializes its variables as runtimeClasspath.

The plugin adds a "java" software component accessible via components.java. The artifact associated with the Java component is the generated JAR file, and the dependencies are those of the runtime configurations.

Java Plugin Concepts

SourceSet

Gradle Docs - Declaring your sources files via source sets

https://docs.gradle.org/current/dsl/org.gradle.api.tasks.SourceSet.html

Explore this, start here: https://docs.gradle.org/current/userguide/building_java_projects.html#sec:java_source_sets

The main Source Set

The main source set contains the production source code of the project, which is compiled and assembled into a JAR. The classes and resources attached to the main source set are packaged as the bytecode JAR artifact of the project.

src/main
     |
     +-- java
     |
     +--resources

The test Source Set

The test source set contains the test source code, which is compiled and executed using JUnit or TestNG. These are typically unit tests, but any test can be include in this source set as long as they all share the same compilation and runtime classpaths.

src/test
     |
     +-- java
     |
     +--resources

To add files from non-standard location to a source set:

sourceSets {
    main {
        resources {
            srcDirs "src/main/resources", "src/main/configs"
        }
    }
}

Artifacts

Also see:

Gradle Artifacts

Bytecode JAR

The Java plugin produces a byte code JAR by default, without any configuration. The jar task performs the mechanics of building the JAR. The JAR content is based on the classes and resources attached to the main source set. The JAR is placed in build/libs subdirectory, and its name, unless explicitly set as described in the "Custom JAR Name" section, is given by the following pattern:

[archiveBaseName]-[archiveAppendix]-[archiveVersion]-[archiveClassifier].[archiveExtension]

The mechanics of building the JAR is explained below in the jar task section.

The plugin creates by default a "thin" JAR, which only includes the project classes. A "fat" JAR, or an uber-JAR, is a self-sufficient archive which contains both classes and dependencies needed to run an application. To create a "fat" JAR, see:

Create a Fat JAR with Gradle

Source JAR

TODO

Testing with Gradle Java Plugin

Testing with Gradle Java Plugin

Plugin Conventions

Conventional Project Layout

https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout

The Java plugin expects to find the production source code under:

src/main/java

Tests are expected under:

src/test/java

All files under:

src/main/resources 

are considered resources and they will be include in the JAR, as resources.

The files available under:

src/test/resources

are considered test resources and will be included in the classpath used to run tests.

All output files are created under the:

build 

directory.

The JAR file is created in:

build/libs

Dependency Configurations

https://docs.gradle.org/current/userguide/java_plugin.html#tab:configurations

The Java plugin adds the following dependency configurations to the project. The configurations are assigned to tasks such as compileJava and test.

api

I am not sure how this got here, it is not reported by gradle dependencies. "This dependency configuration defines dependencies required to compile the production sources of the project which are part of the API exposed by the project."

compile

Deprecated, replaced by implementation. Dependencies for source set 'main'.

implementation

This dependency configuration defines dependencies required to compile the production sources of the project which are not part of the API exposed by the project.

compileOnly

Compile time only dependencies, not used at runtime.

compileClasspath

The compile classpath for source set 'main'. Extends compile, compileOnly and implementation. It is the compile classpath, used when compiling sources. Used by task compileJava.

annotationProcessor

Annotation processors used during compilation.

runtime

Deprecated by runtimeOnly.

"runtime" has a special signification when it comes to artifact publishing. It the project is used as a library, the "runtime" configuration is used to declare the artifacts of the library and their dependencies. The dependencies declared here are assumed to be the dependencies of the published artifact.

runtimeOnly

Runtime only dependencies.

testCompile

Deprecated. Superseded by testImplementation.

testImplementation

This dependency configuration defines dependencies required to compile and run the test source of the project. For example the project decided to write test code with the test framework JUnit.

testCompileOnly

Additional dependencies only for compiling tests, not used at runtime.

testRuntime

Deprecated . Includes all dependencies required to compile the project and tests and then run the tests. Replaced with testImplementation.

testRuntimeOnly

Extends runtimeOnly, everything available on runtimeOnly will also be available on testRuntimeOnly. Runtime only dependencies for running tests. Used by task test.

archives

The "archives" configuration is the standard configuration to assign artifacts to. The Java plugin automatically assigns the default jar to this configuration, as the only element. If a Maven plugin is present, it associates its "install" task with this configuration.

providedRuntime

?

Properties

The Java plugin adds a number of properties to your project. These properties have default values which are usually sufficient to get started.

Tasks

Build Tasks

clean

Deletes the build directory, removing all built files.

assemble

Compiles code and builds the JAR but does not run tests. Other plugins, such as the War Plugin, add more artifacts to this task.

jar

TODO

The Jar Task

The "jar" task assembles the production bytecode JAR artifact.

jar Task Configuration

TODO

Custom JAR Name

TODO

Verification Tasks

check

Compiles and tests the code.

Test Tasks

test

See:

Testing with Gradle Java Plugin