skip to content

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%

answer

  1. distributions.main.distributionBaseName
  2. lazy Property<String>, replaced baseName
  3. archiveBaseName/archiveVersion/archiveFileName on task
  4. version from project.version
  5. destinationDirectory = build/distributions

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.

solid answer

~40 s

The clean way is to configure the **distribution**, not the task: `distributions { main { distributionBaseName.set("myapp") } }`. Both `distZip` and `distTar` then derive their names from it, producing `myapp-1.2.3.zip`/`.tar`. `distributionBaseName` is a lazy `Property<String>` (Gradle 6.0+), replacing the older `baseName` string. The version suffix comes from `project.version`; you can suppress it with an empty version or override pieces. As a last resort you can reach into the task — `tasks.distZip { archiveBaseName.set("myapp") }` or `archiveFileName.set("myapp.zip")` — since these are `Zip`/`Tar` tasks exposing the standard `AbstractArchiveTask` naming properties (`archiveBaseName`, `archiveVersion`, `archiveClassifier`, `archiveExtension`, `archiveFileName`). Prefer the distribution-level property so both archives and `installDist` stay consistent.

code

kotlin · 12 lines
kotlin
version = "1.2.3"

distributions {
    main {
        distributionBaseName.set("myapp")   // myapp-1.2.3.zip / .tar
    }
}

// Per-archive override only if needed:
tasks.distZip {
    archiveClassifier.set("bin")            // myapp-1.2.3-bin.zip
}

go deeper

for a junior

Know that distributionBaseName controls the archive name and outputs are in build/distributions.

for a middle

Distinguish distribution-level distributionBaseName from task-level archiveBaseName/archiveFileName and the name formula.

for a senior

Explain the lazy Property migration (baseName -> distributionBaseName), classifier/version composition, and when a per-task override is justified.

for a principal

Define a repo-wide naming convention (base name, version, classifier) enforced via a convention plugin so release artifacts are uniform.

## Two layers of naming The distribution archives get their names from **two** places, and knowing which to touch is the whole question: ### 1. Distribution-level (preferred) The distribution plugin models each distribution with a `distributionBaseName` property: ```kotlin distributions { main { distributionBaseName.set("myapp") } } ``` `distributionBaseName` is a lazy `Property<String>` (since Gradle 6.0; it replaced the deprecated mutable `baseName` String). Setting it makes **both** `distZip` and `distTar` produce `myapp-<version>.zip` / `myapp-<version>.tar`, and keeps the unpacked `installDist` directory consistent too. This is why it's the recommended lever. ### 2. Task-level (`AbstractArchiveTask`) `distZip`/`distTar` are `Zip`/`Tar` tasks, which extend `AbstractArchiveTask`. That base type computes the final name from composable lazy properties: - `archiveBaseName` — the base (default: distributionBaseName) - `archiveAppendix` - `archiveVersion` — default `project.version` - `archiveClassifier` - `archiveExtension` — `zip` / `tar` - and the assembled `archiveFileName` (override to bypass the formula entirely) - `destinationDirectory` — default `build/distributions` ```kotlin tasks.distZip { archiveBaseName.set("myapp") archiveClassifier.set("bin") // -> myapp-1.2.3-bin.zip } ``` The full name formula is: `[baseName]-[appendix]-[version]-[classifier].[extension]`, omitting empty parts. ## Version suffix The `-<version>` comes from `project.version`. If `version` is unset, Gradle uses `"unspecified"`; set `version = "1.2.3"` in the build (or via `gradle.properties`). To drop the version from the name, set `archiveVersion` to empty. ## Rule of thumb Configure `distributionBaseName` for the common case; only drop to `archiveFileName`/`archiveBaseName` on the task when you need a per-archive override (e.g. a classifier on the zip only).

  • Why prefer distributionBaseName over setting archiveBaseName on each task?
    It sets the name once for both distZip and distTar and keeps the installDist directory name consistent, avoiding drift between archives.
  • How is the `-<version>` portion of the name determined, and how do you remove it?
    From `project.version` via the task's `archiveVersion`; set `archiveVersion` (or version) to empty to drop the suffix.

saying these in an interview costs you the question

  • Recommending the deprecated mutable `baseName` String property instead of the lazy `distributionBaseName`/`archiveBaseName` Property.
  • Assigning to lazy properties with `=` in Kotlin DSL instead of `.set(...)` (older Gradle), or forgetting they are providers.

context

resolving links…