skip to content

How does `distributionBaseName` interact with the project version to determine archive file names, and how do you control versionless archive names?

level: middleimportance: should knowfreq 35%

answer

  1. name = baseName-version.ext
  2. baseName defaults to project name
  3. version from project.version
  4. unspecified version => versionless
  5. install dir omits version

basics

~10 s

The archive name is <distributionBaseName>-<version>.zip. distributionBaseName defaults to the project name and version comes from project.version. If the version is unset (unspecified), the archive is just <baseName>.zip.

solid answer

~30 s

Each generated archive task derives its `archiveBaseName` from the distribution's `distributionBaseName` (a `Property<String>` defaulting to the project name for `main`). The full file name is composed by the underlying `Zip`/`Tar` task as `archiveBaseName-archiveVersion.ext`, where `archiveVersion` comes from `project.version`. If `project.version` is the default `unspecified`, Gradle omits the version segment entirely, yielding `<baseName>.zip`. You can force a versionless or custom name by configuring the archive task directly — e.g. `distZip { archiveVersion.set("") }` or `archiveFileName.set("app.zip")`. The exploded install directory is `build/install/<distributionBaseName>` and does NOT include the version.

code

kotlin · 6 lines
kotlin
version = "2.0.1"
distributions {
    main { distributionBaseName.set("toolkit") }
}
// distZip -> build/distributions/toolkit-2.0.1.zip
// installDist -> build/install/toolkit/  (no version)

go deeper

for a junior

Know the archive name is base name plus version.

for a middle

Explain that base name comes from distributionBaseName/project name and version from project.version, including the unspecified behavior.

for a senior

Show how to override via archiveVersion/archiveFileName and why pinning the base name aids release tooling.

for a principal

Discuss standardizing artifact naming across many modules for publishing and downstream CI consumption.

## The naming formula The distribution plugin's archive tasks are ordinary `Zip`/`Tar` `AbstractArchiveTask`s. Their output file name is assembled from parts: ``` <archiveBaseName>-<archiveAppendix>-<archiveVersion>-<archiveClassifier>.<archiveExtension> ``` Most parts are empty by default. The two that matter here: - **`archiveBaseName`** ← bound to the distribution's `distributionBaseName` (defaults to the project name for `main`). - **`archiveVersion`** ← bound to `project.version`. So with `version = "1.4.0"` and project `report-tool`, `distZip` produces `report-tool-1.4.0.zip`. ## The `unspecified` version case If you never set `project.version`, Gradle's default value is the literal `unspecified`, and archive tasks treat that as "no version" — the version segment (and its separating dash) is dropped. Result: `report-tool.zip`. This trips people up: setting `version = ""` vs leaving it default both yield a versionless name, but an explicit non-empty version is always appended. ## Controlling the name explicitly ```kotlin distributions { main { distributionBaseName.set("report-tool") } } tasks.named<Zip>("distZip") { archiveVersion.set("") // force versionless // or: archiveFileName.set("report-tool-latest.zip") } ``` Setting `archiveFileName` overrides the whole composed name. Prefer adjusting `archiveVersion`/`archiveClassifier` when you want the convention to still apply. ## Install directory naming `installDist` writes to `build/install/<distributionBaseName>/` — the **version is not included** in the install path. So renaming for releases is an archive concern, not an install concern. ## Why this matters for releases Reproducible, predictable artifact names matter for publishing and for downstream CI that globs `build/distributions/*.zip`. Pinning `distributionBaseName` (instead of relying on the project name) decouples the artifact name from a directory rename.

  • How do you produce a versionless archive name?
    Either leave `project.version` at its default `unspecified`, or set `archiveVersion.set("")` on the `distZip`/`distTar` task, or override `archiveFileName` entirely.
  • Does the `installDist` output directory include the version?
    No. It is `build/install/<distributionBaseName>/`; only the archive file name carries the version.

saying these in an interview costs you the question

  • Claiming the install directory includes the version — it does not.
  • Saying you must set `archiveFileName` to add a version — the version is appended automatically from `project.version`.

context

resolving links…