Table of Contents
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.
To use the Distribution Plugin, include the following in your build script:
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/${project.name}
.
The Distribution Plugin adds a number of tasks to your project, as shown below.
distZip
— type:Zip
Creates a ZIP archive of the distribution contents.
distTar
— type:Task
Creates a TAR archive of the distribution contents.
assembleDist
— type:Task
Depends on:
distTar
,distZip
Creates ZIP and TAR archives of the distribution contents.
installDist
— type: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
— type:Zip
Creates a ZIP archive of the distribution contents.
distributionNameDistTar
— type:Tar
Creates a TAR archive of the distribution contents.
assembleDistributionNameDist
— type:Task
Depends on:
distributionNameDistTar
,distributionNameDistZip
Creates ZIP and TAR archives of the distribution contents.
installDistributionNameDist
— type: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
:
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
.
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: Configuring the main distribution
build.gradle
distributions { main { baseName = 'someName' 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 baseName
property has also been changed. This will cause the distribution archives to be created with a different name.
A distribution can be published using the Ivy Publish Plugin or Maven Publish Plugin, or via the original publishing mechanism using the uploadArchives
task.
To publish a distribution to an Ivy repository with the Ivy Publish Plugin, simply 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: Adding distribution archives to an Ivy publication
build.gradle
apply plugin: '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: Adding distribution archives to a Maven publication
build.gradle
apply plugin: 'maven-publish'
publishing {
publications {
myDistribution(MavenPublication) {
artifact distZip
artifact customDistTar
}
}
}
The Distribution Plugin adds the distribution archives as default publishing artifact candidates. With the Maven Plugin applied, the distribution ZIP file will be published when running uploadArchives
if no other default artifact is configured.
Example: Publishing the distribution ZIP with the Maven Plugin
build.gradle
apply plugin:'maven' uploadArchives { repositories { mavenDeployer { repository(url: "file://some/repo") } } }