Gradle Example

This is a simple Gradle project demonstrating local and remote dependency resolution and building an executable jar.

Running the example

This project uses the Gradle Wrapper to automatically bootstrap the build chain. The only requirement for running this example is to have a JDK installed and on the path. Check out SDKMAN! for easy Java version management.

In the root of this project, run:

./gradlew shadowJar
java -jar build/libs/gradle-example-all.jar

The first command compiles the project and packages it into a fat jar. The second runs that jar and prints out the greetings.

About the example

The build.gradle in this project demonstrates two main features, dependency management and using the Shadow Jar plugin to create an executable jar.

Dependencies

This project demonstrates loading dependencies from a Maven repository and from libraries included in the project. The repositories are declared in the repositories block:

repositories {
    mavenCentral()
    flatDir {
        dirs 'lib'
    }
}

The mavenCentral() declaration enables fetching dependencies from the standard Maven Central repository.

The flatDir declaration configures the lib/ directory as a repository. Gradle will make any jars it finds in that directory available as project dependencies. This is useful for libraries that are not published in a repository but should be only be used as a last resort.

The dependencies block is where the project dependencies are specified:

dependencies {
    implementation 'org.codehaus.groovy:groovy:3.+'

    // Groovy module dependency
    implementation 'org.codehaus.groovy:groovy-json:3.+'

    // Strictly exact version of Maven dependency
    implementation 'com.codevineyard:hello-world:1.0.1!!'

    // Dependency from local jar
    implementation ':simple-jar'
}

This project is implemented in Groovy, and uses the Groovy Json module. These are declared in the first two dependencies. The version of 3.+ means Gradle will use any Groovy version starting with a 3.

The next dependency has a strict version requirement: 1.0.1!!. This means that Gradle will only consider exactly version 1.0.1 as valid for this project. If that version cannot be found in a repository, the build will fail.

Finally, the project uses a class in the simple-jar.jar file in the lib/ directory. Since this library isn't hosted in any repository, the dependency uses a name automatically generated by Gradle.

There are more version rules available, but 99 times out of 100 a simple version number is all that is required. You can check which versions Gradle is using by running ./gradlew dependencies.

Shadow Jar

The Shadow Jar plugin is designed to create a single jar file including all of a project's dependencies. This means an application can be packaged into a single file, with no classpath management needed.

Creating the fat jar is done using the shadowJar task:

./gradlew shadowJar

All of the project's runtime dependencies are packaged into a single jar file. You can check the contents of the jar from the command line:

unzip -l build/libs/gradle-example-all.jar

Since this is a Groovy project, there are a lot of classes related to Groovy's dynamic enhancement of the JDK included as well.

Using just the Shadow Jar plugin is sufficient to create a bundled jar with all dependencies. We can make it more useful, however, with the application plugin. This is used to specify the main class:

application {
    mainClassName = 'com.adjectivecolournoun.gradle.Greetz'
}

Now the jar manifest has a Main-Class entry added to it allowing it to be run directly:

java -jar build/libs/gradle-example-all.jar

The only requirement is a Java runtime environment. Everything else needed is bundled into the jar file.