Chapter 37. The Distribution Plugin

Table of Contents

37.1. Usage
37.2. Tasks
37.3. Distribution contents
37.4. Publishing distributions

The distribution plugin is currently incubating. Please be aware that the DSL and other configuration may change in later Gradle versions.

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.

37.1. Usage

To use the distribution plugin, include the following in your build script:

Example 37.1. Using the distribution plugin

build.gradle

apply plugin: 'distribution'

The plugin adds an extension named “distributions” of type DistributionContainer to the project. It also creates a single distribution in the distributions container extension named “main”. If your build only produces one distribution you only need to configure this distribution (or use the defaults).

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 “$buildDir/distributions/$project.name-$project.version.«ext»”.

You can run “gradle installDist” to assemble the uncompressed distribution into “$buildDir/install/main”.

37.2. Tasks

The Distribution plugin adds the following tasks to the project:

Table 37.1. Distribution plugin - tasks

Task name Depends on Type Description

distZip

-

Zip

Creates a ZIP archive of the distribution contents

distTar

-

Tar

Creates a TAR archive of the distribution contents

assembleDist

distTar, distZip

Task

Creates ZIP and TAR archives with the distribution contents

installDist

-

Sync

Assembles the distribution content and installs it on the current machine

For each extra distribution set you add to the project, the distribution plugin adds the following tasks:

Table 37.2. Multiple distributions - tasks

Task name Depends on Type Description

${distribution.name}DistZip

-

Zip

Creates a ZIP archive of the distribution contents

${distribution.name}DistTar

-

Tar

Creates a TAR archive of the distribution contents

assemble${distribution.name.capitalize()}Dist

${distribution.name}DistTar, ${distribution.name}DistZip

Task

Assembles all distribution archives

install${distribution.name.capitalize()}Dist

-

Sync

Assembles the distribution content and installs it on the current machine

Example 37.2. Adding extra distributions

build.gradle

apply plugin: 'distribution'

version = '1.2'
distributions {
    custom {}
}

This will add following tasks to the project:

  • customDistZip

  • customDistTar

  • assembleCustomDist

  • installCustomDist

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 “$buildDir/install/custom”.

37.3. 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 37.3. Configuring the main distribution

build.gradle

apply plugin: 'distribution'

distributions {
    main {
        baseName = 'someName'
        contents {
            from { 'src/readme' }
        }
    }
}

apply plugin:'maven'

uploadArchives {
    repositories {
        mavenDeployer {
            repository(url: "file://some/repo")
        }
    }
}


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 “baseName” property has also been changed. This will cause the distribution archives to be created with a different name.

37.4. Publishing distributions

The distribution plugin adds the distribution archives as candidate for default publishing artifacts. With the maven plugin applied the distribution zip file will be published when running uploadArchives if no other default artifact is configured

Example 37.4. publish main distribution

build.gradle

apply plugin:'maven'

uploadArchives {
    repositories {
        mavenDeployer {
            repository(url: "file://some/repo")
        }
    }
}