# The Distribution Plugin

version 9.3.0-20251208194200+0000

The Distribution Plugin facilitates building archives that serve as distributions of the project. Distribution archives typically contain the executable application and other supporting files, such as documentation.

## Base Plugin

The distribution plugin is split into the `distribution` and `distribution-base` plugins.

The `distribution-base` plugin adds an extension named `distributions` of type DistributionContainer to the project.

The `distribution` plugin applies the `distribution-base` plugin and creates a single distribution in the distributions container extension named `main`.

If your build produces only one distribution, you only need to configure the distribution or rely on the defaults.

## Usage

To use the Distribution Plugin, include the following in your build script:

Example 1. Using the Distribution Plugin
build.gradle.kts

    plugins {
        distribution
    }

build.gradle

    plugins {
        id 'distribution'
    }

You can run `gradle distZip` to package the main distribution as a ZIP, or `gradle distTar` to create a TAR file. To build both types of archives just run `gradle assembleDist`. The files will be created at `layout.buildDirectory.dir("distributions/${project.name}-${project.version}.«ext»")`.

You can run `gradle installDist` to assemble the uncompressed distribution into `layout.buildDirectory.dir("install/${project.name}")`.

## Tasks

The Distribution Plugin adds a number of tasks to your project, as shown below.

`distZip` — Zip

  Creates a ZIP archive of the distribution contents.

`distTar` — Task

  Creates a TAR archive of the distribution contents.

`assembleDist` — Task

  Depends on: `distTar`, `distZip`

  Creates ZIP and TAR archives of the distribution contents.

`installDist` — Sync

  Assembles the distribution content and installs it on the current machine.

For each additional distribution you add to the project, the Distribution Plugin adds the following tasks, where distributionName comes from Distribution.getName():

`distributionNameDistZip` — Zip

  Creates a ZIP archive of the distribution contents.

`distributionNameDistTar` — Tar

  Creates a TAR archive of the distribution contents.

`assembleDistributionNameDist` — Task

  Depends on: `distributionNameDistTar`, `distributionNameDistZip`

  Creates ZIP and TAR archives of the distribution contents.

`installDistributionNameDist` — Sync

  Assembles the distribution content and installs it on the current machine.

The following sample creates a `custom` distribution that will cause four additional tasks to be added to the project: `customDistZip`, `customDistTar`, `assembleCustomDist`, and `installCustomDist`:

Example 2. Adding extra distributions
build.gradle.kts

    distributions {
        create("custom") {
            // configure custom distribution
        }
    }

build.gradle

    distributions {
        custom {
            // configure custom distribution
        }
    }

Given that the project name is `myproject` and version `1.2`, running `gradle customDistZip` will produce a ZIP file named `myproject-custom-1.2.zip`.

Running `gradle installCustomDist` will install the distribution contents into `layout.buildDirectory.dir("install/custom")`.

## Distribution contents

All of the files in the `src/$distribution.name/dist` directory will automatically be included in the distribution. You can add additional files by configuring the Distribution object that is part of the container.

Example 3. Configuring the main distribution
build.gradle.kts

    distributions {
        main {
            distributionBaseName = "someName"
            distributionClassifier = "classifier"
            contents {
                from("src/readme")
            }
        }
    }

build.gradle

    distributions {
        main {
            distributionBaseName = 'someName'
            distributionClassifier = 'classifier'
            contents {
                from 'src/readme'
            }
        }
    }

In the example above, the content of the `src/readme` directory will be included in the distribution (along with the files in the `src/main/dist` directory which are added by default).

The `distributionBaseName` and `distributionClassifier` properties have also been changed. This will cause the distribution archives to be created with a different name.

Example 4. Adding Files and Directories
build.gradle.kts

    distributions {
        main {
            distributionBaseName = "someName"
            contents {
                into("bin/config") {
                    from("config")
                }
                into("lib/samples") {
                    from("samples")
                }
            }
        }
    }

build.gradle

    distributions {
        main {
            distributionBaseName = 'someName'
            contents {
                into('bin/config') {
                    from 'config'
                }
                into('lib/samples') {
                    from 'samples'
                }
            }
        }
    }

In the example above, CopySpec defines the contents, ensuring the `bin/config` directory is automatically created if it doesn’t already exist, and the contents of the `config` directory are copied into it. The same process applies to the `lib/samples` directory.

Gradle provides a robust set of APIs to simplify handling files, managing file dependencies, generating reports, and more. CopySpec is simply one example.

File operations are covered in Working With Files.

## Publishing

A distribution can be published using the Ivy Publish Plugin or Maven Publish Plugin.

### Using the Ivy/Maven Publish Plugins

To publish a distribution to an Ivy repository with the Ivy Publish Plugin, add one or both of its archive tasks to an IvyPublication. The following sample demonstrates how to add the ZIP archive of the `main` distribution and the TAR archive of the `custom` distribution to the `myDistribution` publication:

Example 5. Adding distribution archives to an Ivy publication
build.gradle.kts

    plugins {
        `ivy-publish`
    }

    publishing {
        publications {
            create<IvyPublication>("myDistribution") {
                artifact(tasks.distZip.get())
                artifact(tasks["customDistTar"])
            }
        }
    }

build.gradle

    plugins {
        id 'ivy-publish'
    }

    publishing {
        publications {
            myDistribution(IvyPublication) {
                artifact distZip
                artifact customDistTar
            }
        }
    }

Similarly, to publish a distribution to a Maven repository using the Maven Publish Plugin, add one or both of its archive tasks to a MavenPublication as follows:

Example 6. Adding distribution archives to a Maven publication
build.gradle.kts

    plugins {
        `maven-publish`
    }

    publishing {
        publications {
            create<MavenPublication>("myDistribution") {
                artifact(tasks.distZip)
                artifact(tasks["customDistTar"])
            }
        }
    }

build.gradle

    plugins {
        id 'maven-publish'
    }

    publishing {
        publications {
            myDistribution(MavenPublication) {
                artifact distZip
                artifact customDistTar
            }
        }
    }