Chapter 70. Building Java Libraries

The JVM component plugins rely on a software model which describes how an application is built and how components of the model relate to each other. The software model is organized around key concepts:

To use the JVM component plugins, include the following in your build script:

plugins {
    id 'jvm-component'
    id 'java-lang'
}

A library is created by declaring a JvmLibrarySpec under the components element of the model:

model {
    components {
        main(JvmLibrarySpec)
    }
}

> gradle build
:compileMainJarMainJava
:processMainJarMainResources
:createMainJar
:mainJar
:assemble
:check UP-TO-DATE
:build

BUILD SUCCESSFUL

This example creates a library named main, which will implicitly create a JavaSourceSet named java. The conventions of the legacy Java plugin are observed, where Java sources are expected to be found in src/main/java, while resources are expected to be found in src/main/resources.

Source sets represent logical groupings of source files in a library. A library can define multiple source sets and all sources will be compiled and included in the resulting binaries. When a library is added to a build, the following source sets are added by default.

It is possible to configure an existing source set through the sources container:

components {
    main {
        sources {
            java {
                // configure the "java" source set
            }
        }
    }
}

It is also possible to create an additional source set, using the JavaSourceSet type:

components {
    main {
        sources {
            mySourceSet(JavaSourceSet) {
                // configure the "mySourceSet" source set
            }
        }
    }
}

By default, when the plugins above are applied, no new tasks are added to the build. However, when libraries are defined, conventional tasks are added which build and package each binary of the library.

For each binary of a library, a single lifecycle task is created which executes all tasks associated with building the binary. To build all binaries, the standard build lifecycle task can be used.

For each source set added to a library, tasks are added to compile or process the source files for each binary.

For each binary in a library, a packaging task is added to create the jar for that binary.

Gradle provides a report that you can run from the command-line that shows details about the components and binaries that your project produces. To use this report, just run gradle components. Below is an example of running this report for one of the sample projects:

> gradle components
:components

------------------------------------------------------------
Root project
------------------------------------------------------------

JVM library 'main'
------------------

Source sets
    Java source 'main:java'
        srcDir: src/main/java
    Java source 'main:mySourceSet'
        srcDir: src/main/mySourceSet
    JVM resources 'main:resources'
        srcDir: src/main/resources

Binaries
    Jar 'mainJar'
        build using task: :mainJar
        targetPlatform: java7
        tool chain: JDK 7 (1.7)
        Jar file: build/jars/mainJar/main.jar

Note: currently not all plugins register their components, so some components may not be visible here.

BUILD SUCCESSFUL

Total time: 1 secs

The JVM component plugins support API dependencies between components. Having an API dependency means that if A depends on B, then the API of B is required to compile A. Gradle will then make sure that the dependency is built before the dependent component, and that the dependency appears on the compile classpath. API dependencies are (by nature) not transitive. Runtime (transitive) dependency management is not implemented yet.

Currently the plugin supports two kinds of dependencies:

Dependencies onto external components are not yet supported.

Dependencies are declared on a SourceSet:

model {
    components {
        core(JvmLibrarySpec)

        server(JvmLibrarySpec) {
            sources {
                java {
                    dependencies {
                        library 'core'
                    }
                }
            }
        }
    }
}

> gradle serverJar
:compileCoreJarCoreJava
:processCoreJarCoreResources
:createCoreJar
:coreJar
:compileServerJarServerJava
:createServerJar
:serverJar

BUILD SUCCESSFUL

This example declares an API dependency for the java source set of the server library onto the core library of the same project. However, it is possible to create a dependency on a library in a different project as well:

client(JvmLibrarySpec) {
     sources {
         java {
             dependencies {
                 project ':util' library 'main'
             }
         }
     }
 }

> gradle clientJar
:util:compileMainJarMainJava
:util:createMainJar
:util:mainJar
:compileClientJarClientJava
:createClientJar
:clientJar

BUILD SUCCESSFUL

When the target project only defines a single library, the library selector can be omitted altogether:

dependencies {
    project ':util'
}

The DependencySpecContainer class provides a complete reference of the dependencies DSL.

The Java plugin, in addition to the target platform resolution, supports resolution of custom variants. Custom variants can be defined on custom binary types, as long as they extends JarBinarySpec. Users interested in testing this incubating feature can check out the documentation of the Variant annotation.