Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท Testing and Publishing

Gradle Versioning, Fat Jars, Distributions and Releases

Learn how to version Gradle builds with SemVer and snapshots, set jar manifests, build fat jars, application distributions, reproducible archives and a safe release flow.

When you ship software, the build must answer three questions reliably: what version is this, what exactly is inside the artifact, and can I build the same thing again. Gradle gives you the tools: the version property, manifest attributes, archive tasks, the application distribution and options that make archives reproducible.

This lesson covers version numbers, runnable and fat jars, distributions, and a simple release workflow. It follows publishing to Maven.

Gradle cannot run on this site. Build files are read-only; Java stand-ins for version logic run on Piston.

Version numbers

The version property of the project is used in jar names (shop-1.4.0.jar), the POM and the manifest.

Kotlin
group = "com.example.shop"
version = "1.4.0-SNAPSHOT"

Semantic Versioning (MAJOR.MINOR.PATCH) is the common scheme:

  • MAJOR: incompatible API changes,
  • MINOR: new, backward-compatible features,
  • PATCH: backward-compatible bug fixes.

A suffix -SNAPSHOT marks work in progress. Repositories treat snapshots as mutable, so consumers get the latest build. Release versions are immutable: never publish different content under the same release number.

Instead of editing the script for every release, read the version from gradle.properties:

TEXT
# gradle.properties
version=1.4.0-SNAPSHOT

and publish releases from CI with -Pversion=1.4.0. Some teams derive the version from Git tags with a plugin, so the tag v1.4.0 becomes the version automatically.

Java Stand-in: comparing semantic versions

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.

Note that 1.10.0 is greater than 1.9.2; comparing version strings as text would get this wrong, which is why Gradle has its own version ordering rules.

The jar task and the manifest

Kotlin
tasks.jar {
    archiveBaseName = "shop-core"
    manifest {
        attributes(
            "Implementation-Title" to project.name,
            "Implementation-Version" to project.version,
            "Main-Class" to "shop.cli.Main"
        )
    }
}

A plain jar contains only your classes and resources, not your dependencies. Running java -jar shop.jar fails with NoClassDefFoundError if dependencies are missing.

Fat (uber) jars

A fat jar bundles your classes plus every runtime dependency into one file. You can write it with core Gradle:

Kotlin
tasks.register<Jar>("fatJar") {
    archiveClassifier = "all"
    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
    manifest { attributes("Main-Class" to "shop.cli.Main") }
    from(sourceSets.main.get().output)
    from({
        configurations.runtimeClasspath.get()
            .filter { it.name.endsWith(".jar") }
            .map { zipTree(it) }
    })
}

Be aware of problems with this simple approach: duplicate resources such as META-INF/services files overwrite each other, and signed jars break. The popular Shadow plugin (com.gradleup.shadow) merges service files, relocates packages and handles these cases:

Kotlin
plugins { id("com.gradleup.shadow") version "9.0.0" }

tasks.shadowJar {
    mergeServiceFiles()
    relocate("com.google.common", "shop.shaded.guava")
}

Spring Boot has its own bootJar, which uses a nested-jar layout instead of unpacking.

Distributions

For command-line programs the application plugin builds better artifacts than a fat jar: a zip with bin/ start scripts and lib/ jars. Everything is kept as separate jars, so licenses and signatures stay intact.

Kotlin
plugins { application }

application { mainClass = "shop.cli.Main" }

distributions {
    main {
        contents {
            from("docs") { into("docs") }
            from("LICENSE")
        }
    }
}

./gradlew distZip creates build/distributions/shop-1.4.0.zip; ./gradlew installDist unpacks it to build/install/shop, so you can try build/install/shop/bin/shop.

Reproducible archives

If you build the same commit twice, the zip bytes should be identical. By default timestamps and file order differ. Fix this for all archives:

Kotlin
tasks.withType<AbstractArchiveTask>().configureEach {
    isPreserveFileTimestamps = false
    isReproducibleFileOrder = true
}

Reproducible output improves caching, makes checksums meaningful and lets you verify that a binary comes from a given source.

A simple release workflow

  1. Make sure the main branch is green (./gradlew check).
  2. Pick the version, for example 1.4.0, tag it: git tag v1.4.0.
  3. CI builds with -Pversion=1.4.0, runs check, then publish and attaches the distribution to a release page.
  4. Bump the development version to the next snapshot (1.5.0-SNAPSHOT).

The same job should run ./gradlew build --no-daemon --warning-mode=fail so deprecation warnings are caught before they break an upgrade.

Java Stand-in: building a release file name

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.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the -SNAPSHOT suffix mean?

    Snapshots signal development builds that may be overwritten, while release versions must never change.
  2. 2. Why can a plain jar fail with NoClassDefFoundError when run with java -jar?

    The jar task packages your classes only. Use a fat jar or an application distribution to ship dependencies.
  3. 3. Why is installDist useful?

    installDist writes the distribution layout to build/install, so you can test bin scripts without unzipping.
  4. 4. Which settings make archives reproducible?

    Removing timestamps and fixing file order makes repeated builds produce identical bytes.

Summary

  • Use SemVer; -SNAPSHOT means mutable, releases are immutable.
  • A plain jar has no dependencies; choose a fat jar (Shadow) or an application distribution.
  • Prefer distZip for CLI tools and keep jars intact.
  • Make archives reproducible for caching and verification.
  • Release by tagging, building in CI with -Pversion, publishing and bumping to the next snapshot.

Next: Incremental builds and the build cache