skip to content

distZip and distTar Archives

4 roadmaps5 questions

The distZip and distTar archives the application plugin produces and how they hang off assemble. Asked because these are the artifacts CI usually publishes.

on this pageshow

explore

questions

5

What are the distZip and distTar tasks, and where do they come from in a Gradle build?

level: juniorimportance: must knowfreq 60%

answer

  1. application plugin applies distribution plugin
  2. build/distributions/*.zip and *.tar
  3. archive contains bin/ + lib/
  4. assembleDist aggregates both
  5. jar + runtime deps + start scripts

basics

~10 s

distZip and distTar are tasks added by Gradle's application (and distribution) plugin. They bundle your app's jar, dependencies, and start scripts into a redistributable .zip or .tar archive in build/distributions.

solid answer

~30 s

Applying the `application` plugin (which itself applies the `distribution` plugin) registers `distZip` and `distTar`. They package the **main distribution** — the project jar, its runtime dependency jars, and the generated Unix/Windows start scripts — into `build/distributions/<name>-<version>.zip` and `.tar`. The layout inside the archive is `<root>/bin` (start scripts) and `<root>/lib` (jars). The aggregate `assembleDist` task depends on both, and `build` triggers `assembleDist`. You typically hand someone the zip; they unzip and run the script in `bin/`. The archive name derives from `distributions.main.distributionBaseName` (defaulting to the project name).

code

kotlin · 10 lines
kotlin
plugins {
    application
}

application {
    mainClass.set("com.example.App")
}

// ./gradlew distZip  ->  build/distributions/<project>-<version>.zip
// ./gradlew distTar  ->  build/distributions/<project>-<version>.tar

go deeper

for a junior

Name the tasks, the plugin that adds them, and that outputs land in build/distributions.

for a middle

Explain the bin/lib layout, that runtime deps and start scripts are included, and the assembleDist aggregation.

for a senior

Tie distZip/distTar to the distribution plugin's CopySpec model and how application configures the main distribution from runtimeClasspath.

for a principal

Position distribution archives in a release/packaging strategy vs. fat jars or container images, and how to standardize them across many service repos.

## Where they come from The `distZip` and `distTar` tasks are not built into the Gradle core; they are contributed by the **distribution plugin**. The **application plugin** automatically applies the distribution plugin, so most people meet `distZip`/`distTar` through `application`. The distribution plugin lets you define one or more *distributions* (a named bundle of files); the application plugin configures the `main` distribution to contain everything needed to run your program. ## What goes inside For the `main` distribution the application plugin wires in: - the project's own jar (the output of the `jar` task), - all **runtime** dependency jars (resolved from the `runtimeClasspath` configuration), - the generated start scripts produced by the `startScripts` task (a Unix shell script and a Windows `.bat`). The archive root is a single directory (so unzipping doesn't litter the current folder), and inside it: - `bin/` — the start scripts, - `lib/` — all the jars. ## The tasks themselves `distZip` is of type `Zip` and `distTar` is of type `Tar`; they are pre-configured `CopySpec`-based archive tasks. Outputs land in `build/distributions/`. The file name is `${distributionBaseName}-${version}.zip` (or `.tar`). ## Aggregation and lifecycle The distribution plugin adds an aggregate **`assembleDist`** task that depends on `distZip` + `distTar`, and hooks `assembleDist` into the standard `assemble`/`build` lifecycle. So `./gradlew build` produces the archives as a side effect, and `./gradlew assembleDist` builds just the distribution archives. ```kotlin plugins { application } application { mainClass.set("com.example.App") } // distZip, distTar, assembleDist, installDist now exist ``` Run `./gradlew distZip` and look in `build/distributions/`. Unzip, then run `bin/<app>`.

  • Which task aggregates distZip and distTar, and is it run by `build`?
    `assembleDist` depends on both; the distribution plugin wires `assembleDist` into `assemble`/`build`, so `./gradlew build` produces the archives.
  • What is the internal layout of the produced archive?
    A single root directory containing `bin/` (start scripts) and `lib/` (the project jar plus all runtime dependency jars).

saying these in an interview costs you the question

  • Saying distZip/distTar come from the `java` plugin — they come from the distribution plugin (applied transitively by `application`).
  • Claiming the archive is a single fat jar — it is a folder of jars plus scripts, not an uber-jar.

context

resolving links…

open as a page

How do you control the file name of the distZip/distTar archives, e.g. set a custom base name instead of the project name?

level: middleimportance: must knowfreq 45%

basics

~10 s

Set distributions.main.distributionBaseName (the modern API). The archive becomes <baseName>-<version>.zip/.tar. You can also override archiveFileName directly on the distZip/distTar task, but configuring the distribution is preferred.

open as a page

How are distZip and distTar wired into the build lifecycle, and how does assembleDist fit in?

level: middleimportance: should knowfreq 35%

basics

~10 s

The distribution plugin adds assembleDist, which depends on distZip and distTar. It wires assembleDist into assemble/build, so ./gradlew build produces both archives. Run assembleDist to build only the distribution archives.

open as a page

How can you add extra files (README, license, config) to the distZip/distTar archive without touching the application plugin's defaults?

level: seniorimportance: should knowfreq 30%

basics

~10 s

Use distributions.main.contents { ... }, which is a CopySpec. from("...") adds files (e.g. into a etc/ or root folder) on top of the default bin/lib that the application plugin already supplies.

open as a page

How do you make distTar produce a compressed, reproducible archive, and what knobs control compression?

level: seniorimportance: nice to knowfreq 18%

basics

~10 s

Configure the distTar task: set compression = Compression.GZIP to produce a .tgz-style gzip tar, and set isReproducibleFileOrder = true and isPreserveFileTimestamps = false for byte-stable, reproducible archives.

open as a page