<!--
~ Copyright 2012 the original author or authors.
~
~ Licensed under the Apache License, Version 2.0 (the "License");
~ you may not use this file except in compliance with the License.
~ You may obtain a copy of the License at
~
~ http://www.apache.org/licenses/LICENSE-2.0
~
~ Unless required by applicable law or agreed to in writing, software
~ distributed under the License is distributed on an "AS IS" BASIS,
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~ See the License for the specific language governing permissions and
~ limitations under the License.
-->

<chapter id='distribution_plugin'>
    <title>The Distribution Plugin</title>
    <note>
        <para>
            The distribution plugin is currently <link linkend="feature_lifecycle">incubating</link>. Please be aware that the DSL and other configuration may change in later Gradle versions.
        </para>
    </note>

    <para>
        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.
	</para>

    <section id="sec:distribution_usage">
        <title>Usage</title>
        <para>To use the distribution plugin, include the following in your build script:</para>
        <sample id="useDistributionPlugin" dir="userguide/distribution" title="Using the distribution plugin">
            <sourcefile file="build.gradle" snippet="use-plugin"/>
        </sample>
        <para>
            The plugin adds an extension named “<literal>distributions</literal>” of type <apilink class="org.gradle.api.distribution.DistributionContainer" /> to the project.
            It also creates a single distribution in the distributions container extension named “<literal>main</literal>”.
            If your build only produces one distribution you only need to configure this distribution (or use the defaults).
        </para>
        <para>
            You can run “<userinput>gradle distZip</userinput>” to package the main distribution as a ZIP, or “<userinput>gradle distTar</userinput>” to create
            a TAR file. To build both types of archives just run <userinput>gradle assembleDist</userinput>.
            The files will be created at “<literal><replaceable>$buildDir</replaceable>/distributions/<replaceable>$project.name</replaceable>-<replaceable>$project.version</replaceable>.<replaceable>«ext»</replaceable></literal>”.
        </para>
        <para>
            You can run “<userinput>gradle installDist</userinput>” to assemble the uncompressed distribution into “<literal><replaceable>$buildDir</replaceable>/install/<replaceable>main</replaceable></literal>”.
        </para>
    </section>

    <section id="sec:distribution_tasks">
        <title>Tasks</title>
        <para>The Distribution plugin adds the following tasks to the project:</para>
        <table>
            <title>Distribution plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>distZip</literal>
                </td>
                <td>
                    <literal>-</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.tasks.bundling.Zip"/>
                </td>
                <td>
                    Creates a ZIP archive of the distribution contents
                </td>
            </tr>
            <tr>
                <td>
                   <literal>distTar</literal>
                </td>
                <td>
                   <literal>-</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.tasks.bundling.Tar"/>
                </td>
                <td>
                    Creates a TAR archive of the distribution contents
                </td>
            </tr>
            <tr>
                <td>
                    <literal>assembleDist</literal>
                </td>
                <td>
                    <literal>distTar</literal>, <literal>distZip</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.Task"/>
                </td>
                <td>
                    Creates ZIP and TAR archives with the distribution contents
                </td>
            </tr>
            <tr>
                <td>
                    <literal>installDist</literal>
                </td>
                <td>
                    <literal>-</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.tasks.Sync"/>
                </td>
                <td>
                    Assembles the distribution content and installs it on the current machine
                </td>
            </tr>
        </table>
        <para>For each extra distribution set you add to the project, the distribution plugin adds the following tasks:</para>
        <table>
            <title>Multiple distributions - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal><replaceable>${distribution.name}</replaceable>DistZip</literal>
                </td>
                <td>
                    <literal>-</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.tasks.bundling.Zip"/>
                </td>
                <td>
                    Creates a ZIP archive of the distribution contents
                </td>
            </tr>
            <tr>
                <td>
                    <literal><replaceable>${distribution.name}</replaceable>DistTar</literal>
                </td>
                <td>
                    <literal>-</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.tasks.bundling.Tar"/>
                </td>
                <td>
                    Creates a TAR archive of the distribution contents
                </td>
            </tr>
            <tr>
                <td>
                    <literal>assemble<replaceable>${distribution.name.capitalize()}</replaceable>Dist</literal>
                </td>
                <td>
                    <literal><replaceable>${distribution.name}</replaceable>DistTar</literal>, <literal><replaceable>${distribution.name}</replaceable>DistZip</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.Task"/>
                </td>
                <td>
                    Assembles all distribution archives
                </td>
            </tr>
            <tr>
                <td>
                    <literal>install<replaceable>${distribution.name.capitalize()}</replaceable>Dist</literal>
                </td>
                <td>
                    <literal>-</literal>
                </td>
                <td>
                    <apilink class="org.gradle.api.tasks.Sync"/>
                </td>
                <td>
                    Assembles the distribution content and installs it on the current machine
                </td>
            </tr>
        </table>
        <sample id="multipleDistribution" dir="userguide/distribution" title="Adding extra distributions">
            <sourcefile file="build.gradle" snippet="custom-distribution"/>
        </sample>
        <para>
            This will add following tasks to the project:
            <itemizedlist>
                <listitem>customDistZip</listitem>
                <listitem>customDistTar</listitem>
                <listitem>assembleCustomDist</listitem>
                <listitem>installCustomDist</listitem>
            </itemizedlist>
        </para>
        <para>
            Given that the project name is “<literal>myproject</literal>” and version “<literal>1.2</literal>”, running “<userinput>gradle customDistZip</userinput>” will produce a
            ZIP file named “<literal>myproject-custom-1.2.zip</literal>”.
        </para>
        <para>
            Running “<userinput>gradle installCustomDist</userinput>” will install the distribution contents into “<literal><replaceable>$buildDir</replaceable>/install/custom</literal>”.
        </para>
    </section>
    <section id="sec:distribution_contents">
      <title>Distribution contents</title>
        <para>
            All of the files in the “<literal>src/<replaceable>$distribution.name</replaceable>/dist</literal>” directory will automatically be included in the distribution.
            You can add additional files by configuring the <apilink class="org.gradle.api.distribution.Distribution" /> object that is part of the container.
        </para>
        <sample id="configureDistribution" dir="userguide/distribution" title="Configuring the main distribution">
            <sourcefile file="build.gradle" snippet="configure-distribution"/>
        </sample>
        <para>
            In the example above, the content of the “<literal>src/readme</literal>” directory will be included in the distribution
            (along with the files in the “<literal>src/main/dist</literal>” directory which are added by default).
        </para>
        <para>
            The “<literal>baseName</literal>” property has also been changed. This will cause the distribution archives to be created with a different name.
        </para>
    </section>
    <section id="sec:publishing_distributions">
        <title>Publishing distributions</title>
        <para>
            The distribution plugin adds the distribution archives as candidate for default publishing artifacts.
            With the <literal>maven</literal> plugin applied the distribution zip file will be published when running uploadArchives
            if no other default artifact is configured
        </para>
        <sample id="publishDistribution" dir="userguide/distribution" title="publish main distribution">
            <sourcefile file="build.gradle" snippet="publish-distribution"/>
        </sample>
    </section>
</chapter>
