<!--
  ~ Copyright 2010 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='java_plugin' xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>The Java Plugin</title>

    <para>The Java plugin adds Java compilation, testing and bundling capabilities to a project. It serves as the basis
        for many of the other Gradle plugins.
    </para>

    <section>
        <title>Usage</title>
        <para>To use the Java plugin, include in your build script:</para>
        <sample id="useJavaPlugin" dir="java/quickstart" title="Using the Java plugin">
            <sourcefile file="build.gradle" snippet="use-plugin"/>
        </sample>
    </section>

    <section>
        <title>Source sets</title>
        <para>The Java plugin introduces the concept of a <firstterm>source set</firstterm>. A source set is simply a group of
            source files which are compiled and executed together. These source files may include Java source files and
            resource files. Other plugins add the ability to include Groovy and Scala source files in a source set.
            A source set has an associated compile classpath, and runtime classpath.
        </para>
        <para>
            One use for source sets is to group source files into logical groups which describe their purpose. For example,
            you might use a source set to define an integration test suite, or you might use separate source sets to define
            the API and implementation classes of your project.
        </para>
        <para>The Java plugin defines two standard source sets, called <literal>main</literal> and <literal>test</literal>.
            The <literal>main</literal> source set contains your production source code, which is compiled and assembled
            into a JAR file. The <literal>test</literal> source set contains your unit test source code, which is
            compiled and executed using JUnit or TestNG.
        </para>
    </section>

    <section>
        <title>Tasks</title>
        <para>The Java plugin adds a number of tasks to your project, as shown below.</para>

        <table>
            <title>Java plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>compileJava</literal>
                </td>
                <td>All tasks which produce the compile classpath. This includes the <literal>jar</literal> task for
                    project dependencies included in the <literal>compile</literal> configuration.
                </td>
                <td><apilink class="org.gradle.api.tasks.compile.JavaCompile"/></td>
                <td>Compiles production Java source files using javac.</td>
            </tr>
            <tr>
                <td>
                    <literal>processResources</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.Copy"/></td>
                <td>Copies production resources into the production classes directory.</td>
            </tr>
            <tr>
                <td>
                    <literal>classes</literal>
                </td>
                <td>
                    <literal>compileJava</literal> and <literal>processResources</literal>.
                    Some plugins add additional compilation tasks.
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
                <td>Assembles the production classes directory.</td>
            </tr>
            <tr>
                <td>
                    <literal>compileTestJava</literal>
                </td>
                <td>
                    <literal>compile</literal>, plus all tasks which produce the test compile classpath.
                </td>
                <td><apilink class="org.gradle.api.tasks.compile.JavaCompile"/></td>
                <td>Compiles test Java source files using javac.</td>
            </tr>
            <tr>
                <td>
                    <literal>processTestResources</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.Copy"/></td>
                <td>Copies test resources into the test classes directory.</td>
            </tr>
            <tr>
                <td>
                    <literal>testClasses</literal>
                </td>
                <td>
                    <literal>compileTestJava</literal> and <literal>processTestResources</literal>.
                    Some plugins add additional test compilation tasks.
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
                <td>Assembles the test classes directory.</td>
            </tr>
            <tr>
                <td>
                    <literal>jar</literal>
                </td>
                <td>
                    <literal>compile</literal>
                </td>
                <td><apilink class="org.gradle.api.tasks.bundling.Jar"/></td>
                <td>Assembles the JAR file</td>
            </tr>
            <tr>
                <td>
                    <literal>javadoc</literal>
                </td>
                <td><literal>compile</literal></td>
                <td><apilink class="org.gradle.api.tasks.javadoc.Javadoc"/></td>
                <td>Generates API documentation for the production Java source, using Javadoc </td>
            </tr>
            <tr>
                <td>
                    <literal>test</literal>
                </td>
                <td>
                    <literal>compile</literal>,
                    <literal>compileTest</literal>,
                    plus all tasks which produce the test runtime classpath.
                </td>
                <td><apilink class="org.gradle.api.tasks.testing.Test"/></td>
                <td>Runs the unit tests using JUnit or TestNG.</td>
            </tr>
            <tr>
                <td>
                    <literal>uploadArchives</literal>
                </td>
                <td>
                    The tasks which produce the artifacts in the <literal>archives</literal> configuration, including <literal>jar</literal>.
                </td>
                <td><apilink class="org.gradle.api.tasks.Upload"/></td>
                <td>Uploads the artifacts in the <literal>archives</literal> configuration, including the JAR file.</td>
            </tr>
            <tr>
                <td>
                    <literal>clean</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.Delete"/></td>
                <td>Deletes the project build directory.</td>
            </tr>
            <tr>
                <td>
                    <literal>clean<replaceable>TaskName</replaceable></literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.Delete"/></td>
                <td>Deletes the output files produced by the specified task. For example <literal>cleanJar</literal>
                    will delete the JAR file created by the <literal>jar</literal> task, and
                    <literal>cleanTest</literal> will delete the test results created by the <literal>test</literal> task.
                </td>
            </tr>
        </table>

        <para>For each source set you add to the project, the Java plugin adds the following compilation tasks:</para>
        <table id="java_source_set_tasks">
            <title>Java plugin - source set tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>compile<replaceable>SourceSet</replaceable>Java</literal>
                </td>
                <td>
                    All tasks which produce the source set's compile classpath.
                </td>
                <td><apilink class="org.gradle.api.tasks.compile.JavaCompile"/></td>
                <td>Compiles the given source set's Java source files using javac.</td>
            </tr>
            <tr>
                <td>
                    <literal>process<replaceable>SourceSet</replaceable>Resources</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.Copy"/></td>
                <td>Copies the given source set's resources into the classes directory.</td>
            </tr>
            <tr>
                <td>
                    <literal><replaceable>sourceSet</replaceable>Classes</literal>
                </td>
                <td>
                    <literal>compile<replaceable>SourceSet</replaceable>Java</literal> and
                    <literal>process<replaceable>SourceSet</replaceable>Resources</literal>.
                    Some plugins add additional compilation tasks for the source set.
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
                <td>Assembles the given source set's classes directory.</td>
            </tr>
        </table>

        <para>The Java plugin also adds a number of tasks which form a lifecycle for the project:</para>

        <table>
            <title>Java plugin - lifecycle tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>assemble</literal>
                </td>
                <td>
                    All archive tasks in the project, including <literal>jar</literal>. Some plugins add additional
                    archive tasks to the project.
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
                <td>Assembles all the archives in the project.</td>
            </tr>
            <tr>
                <td>
                    <literal>check</literal>
                </td>
                <td>
                    All verification tasks in the project, including <literal>test</literal>. Some plugins add
                    additional verification tasks to the project.
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
                <td>Performs all verification tasks in the project.</td>
            </tr>
            <tr>
                <td>
                    <literal>build</literal>
                </td>
                <td>
                    <literal>check</literal> and <literal>assemble</literal>
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
                <td>Performs a full build of the project.</td>
            </tr>
            <tr>
                <td>
                    <literal>buildNeeded</literal>
                </td>
                <td>
                    <literal>build</literal> and <literal>build</literal> tasks in all project lib dependencies of the
                    <literal>testRuntime</literal> configuration.
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
                <td>Performs a full build of the project and all projects it depends on.</td>
            </tr>
            <tr>
                <td>
                    <literal>buildDependents</literal>
                </td>
                <td>
                    <literal>build</literal> and <literal>build</literal> tasks in all projects with a project lib
                    dependency on this project in a <literal>testRuntime</literal> configuration.
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
                <td>Performs a full build of the project and all projects which depend on it.</td>
            </tr>
            <tr>
                <td>
                    <literal>build<replaceable>ConfigurationName</replaceable></literal>
                </td>
                <td>
                    The tasks which produce the artifacts in configuration <replaceable>ConfigurationName</replaceable>.
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
                <td>Assembles the artifacts in the specified configuration.
                    The task is added by the Base plugin which is implicitly applied by the Java plugin.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>upload<replaceable>ConfigurationName</replaceable></literal>
                </td>
                <td>
                    The tasks which uploads the artifacts in configuration <replaceable>ConfigurationName</replaceable>.
                </td>
                <td><apilink class="org.gradle.api.tasks.Upload"/></td>
                <td>Assembles and uploads the artifacts in the specified configuration.
                    The task is added by the Base plugin which is implicitly applied by the Java plugin.
                </td>
            </tr>
        </table>

        <para>The following diagram shows the relationships between these tasks.</para>

        <figure>
            <title>Java plugin - tasks</title>
            <imageobject>
                <imagedata fileref="img/javaPluginTasks.png"/>
            </imageobject>
        </figure>
    </section>

    <section>
        <title>Project layout</title>
        <para>The Java plugin assumes the project layout shown below. None of these directories need exist or have
            anything in them. The Java plugin will compile whatever it finds, and handles anything which is missing.
        </para>

        <table id='javalayout'>
            <title>Java plugin - default project layout</title>
            <thead>
                <tr>
                    <td>Directory</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <xi:include href="javaProjectMainLayout.xml"/>
            <xi:include href="javaProjectTestLayout.xml"/>
            <xi:include href="javaProjectGenericLayout.xml"/>
        </table>

        <section>
            <title>Changing the project layout</title>
            <para>You configure the project layout by configuring the appropriate source set. This is discussed in
                more detail in the following sections. Here is a brief example which changes the main Java and resource
                source directories.
            </para>
            <sample id="customJavaSourceLayout" dir="java/customizedLayout" title="Custom Java source layout">
                <sourcefile file="build.gradle" snippet="define-main"/>
            </sample>
        </section>
    </section>

    <section id="sec:java_plugin_and_dependency_management">
        <title>Dependency management</title>
        <para>The Java plugin adds a number of dependency configurations to your project, as shown below. It assigns
            those configurations to tasks such as <literal>compileJava</literal> and <literal>test</literal>.
        </para>
        <table id='tab:configurations'>
            <title>Java plugin - dependency configurations</title>
            <thead>
                <tr>
                    <td>Name</td>
                    <td>Extends</td>
                    <td>Used by tasks</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td>compile</td>
                <td>-</td>
                <td>compileJava</td>
                <td>Compile time dependencies</td>
            </tr>
            <tr>
                <td>runtime</td>
                <td>compile</td>
                <td>-</td>
                <td>Runtime dependencies</td>
            </tr>
            <tr>
                <td>testCompile</td>
                <td>compile</td>
                <td>compileTestJava</td>
                <td>Additional dependencies for compiling tests.</td>
            </tr>
            <tr>
                <td>testRuntime</td>
                <td>runtime, testCompile</td>
                <td>test</td>
                <td>Additional dependencies for running tests only.</td>
            </tr>
            <tr>
                <td>archives</td>
                <td>-</td>
                <td>uploadArchives</td>
                <td>Artifacts (e.g. jars) produced by this project.</td>
            </tr>
            <tr>
                <td>default</td>
                <td>runtime</td>
                <td>-</td>
                <td>The default configuration used by a project dependency on this project. Contains the artifacts and
                    dependencies required by this project at runtime.
                </td>
            </tr>
        </table>
        <figure>
            <title>Java plugin - dependency configurations</title>
            <imageobject>
                <imagedata fileref="img/javaPluginConfigurations.png"/>
            </imageobject>
        </figure>
        <para>For each source set you add to the project, the Java plugins adds the following dependency configurations:</para>
        <table id="java_source_set_configurations">
            <title>Java plugin - source set dependency configurations</title>
            <thead>
                <tr>
                    <td>Name</td>
                    <td>Extends</td>
                    <td>Used by tasks</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td><replaceable>sourceSet</replaceable>Compile</td>
                <td>-</td>
                <td>compile<replaceable>SourceSet</replaceable>Java</td>
                <td>Compile time dependencies for the given source set</td>
            </tr>
            <tr>
                <td><replaceable>sourceSet</replaceable>Runtime</td>
                <td><replaceable>sourceSet</replaceable>Compile</td>
                <td>-</td>
                <td>Runtime time dependencies for the given source set</td>
            </tr>
        </table>
    </section>

    <section>
        <title>Convention properties</title>
        <para>
            The Java plugin adds a number of convention properties to the project, shown below. You can use these properties
            in your build script as though they were properties of the project object (see
            <xref linkend="sub:more_about_convention_objects"/>).
        </para>

        <table id='javaconventionDir'>
            <title>Java plugin - directory properties</title>
            <thead>
                <tr>
                    <td>Property name</td>
                    <td>Type</td>
                    <td>Default value</td>
                    <td>Description</td>
                </tr>
            </thead>
            <xi:include href="reportingBasePluginProperties.xml"/>
            <tr>
                <td>
                    <literal>testResultsDirName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <literal>test-results</literal>
                </td>
                <td>
                    The name of the directory to generate test result .xml files into, relative to the build directory.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>testResultsDir</literal>
                </td>
                <td>
                    <classname>File</classname> (read-only)
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/<replaceable>testResultsDirName</replaceable></literal>
                </td>
                <td>
                    The directory to generate test result .xml files into.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>testReportDirName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <literal>tests</literal>
                </td>
                <td>
                    The name of the directory to generate the test report into, relative to the reports directory.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>testReportDir</literal>
                </td>
                <td>
                    <classname>File</classname> (read-only)
                </td>
                <td>
                    <literal><replaceable>reportsDir</replaceable>/<literal>testReportDirName</literal></literal>
                </td>
                <td>
                    The directory to generate the test report into.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>libsDirName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <literal>libs</literal>
                </td>
                <td>
                    The name of the directory to generate libraries into, relative to the build directory.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>libsDir</literal>
                </td>
                <td>
                    <classname>File</classname> (read-only)
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/<replaceable>libsDirName</replaceable></literal>
                </td>
                <td>
                    The directory to generate libraries into.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>distsDirName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <literal>distributions</literal>
                </td>
                <td>
                    The name of the directory to generate distributions into, relative to the build directory.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>distsDir</literal>
                </td>
                <td>
                    <classname>File</classname> (read-only)
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/<replaceable>distsDirName</replaceable></literal>
                </td>
                <td>
                    The directory to generate distributions into.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>docsDirName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <literal>docs</literal>
                </td>
                <td>
                    The name of the directory to generate documentation into, relative to the build directory.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>docsDir</literal>
                </td>
                <td>
                    <classname>File</classname> (read-only)
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/<replaceable>docsDirName</replaceable></literal>
                </td>
                <td>
                    The directory to generate documentation into.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>dependencyCacheDirName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <literal>dependency-cache</literal>
                </td>
                <td>
                    The name of the directory to use to cache source dependency information, relative to the build directory.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>dependencyCacheDir</literal>
                </td>
                <td>
                    <classname>File</classname> (read-only)
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/<replaceable>dependencyCacheDirName</replaceable></literal>
                </td>
                <td>
                    The directory to use to cache source dependency information.
                </td>
            </tr>
        </table>

        <table id='javaconventionNonDir'>
            <title>Java plugin - other properties</title>
            <thead>
                <tr>
                    <td>Property name</td>
                    <td>Type</td>
                    <td>Default value</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>sourceSets</literal>
                </td>
                <td><apilink class="org.gradle.api.tasks.SourceSetContainer"/> (read-only)</td>
                <td>Not null</td>
                <td>Contains the project's source sets.</td>
            </tr>
            <tr>
                <td>
                    <literal>sourceCompatibility</literal>
                </td>
                <td><apilink class="org.gradle.api.JavaVersion"/>. Can also set using a String or a Number, e.g.
                    <literal>'1.5'</literal> or <literal>1.5</literal>.
                </td>
                <td>Value of the current used JVM</td>
                <td>Java version compatibility to use when compiling Java source.</td>
            </tr>
            <tr>
                <td>
                    <literal>targetCompatibility</literal>
                </td>
                <td><apilink class="org.gradle.api.JavaVersion"/>. Can also set using a String or Number, e.g.
                    <literal>'1.5'</literal> or <literal>1.5</literal>.
                </td>
                <td>
                    <literal><replaceable>sourceCompatibility</replaceable></literal>
                </td>
                <td>Java version to generate classes for.</td>
            </tr>
            <tr>
                <td>
                    <literal>archivesBaseName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td><literal><replaceable>projectName</replaceable></literal></td>
                <td>The basename to use for archives, such as JAR or ZIP files.</td>
            </tr>
            <tr>
                <td>
                    <literal>manifest</literal>
                </td>
                <td><apilink class="org.gradle.api.java.archives.Manifest"/></td>
                <td>an empty manifest</td>
                <td>The manifest to include in all JAR files.</td>
            </tr>
        </table>

        <para>
            These properties are provided by convention objects of type <apilink class="org.gradle.api.plugins.JavaPluginConvention"/>,
            <apilink class="org.gradle.api.plugins.BasePluginConvention"/> and
            <apilink class="org.gradle.api.plugins.ReportingBasePluginConvention"/>.
        </para>
    </section>

    <section id="sec:source_sets">
        <title>Working with source sets</title>
        <para>You can access the source sets of a project using the <literal>sourceSets</literal> property. This
            is a container for the project's source sets, of type <apilink class="org.gradle.api.tasks.SourceSetContainer"/>.
            There is also a <literal>sourceSets { }</literal> script block, which you can pass a closure to configure the
            source set container. The source set container works pretty much the same way as other containers, such
            as <literal>tasks</literal>.
        </para>
        <sample id="defineSourceSet" dir="userguide/java/sourceSets" title="Accessing a source set">
            <sourcefile file="build.gradle" snippet="access-source-set"/>
        </sample>
        <para>To configure an existing source set, you simply use one of the above access methods to set the
            properties of the source set. The properties are described below. Here is an example which configures the
            main Java and resources directories:</para>
        <sample id="configureSourceSet" dir="java/customizedLayout" title="Configuring the source directories of a source set">
            <sourcefile file="build.gradle" snippet="define-main"/>
        </sample>

        <section>
            <title>Source set properties</title>
            <para>The following table lists some of the important properties of a source set.
                You can find more details in the API documentation for <apilink class="org.gradle.api.tasks.SourceSet"/>.
            </para>
            <table>
                <title>Java plugin - source set properties</title>
                <thead>
                    <tr>
                        <td>Property name</td>
                        <td>Type</td>
                        <td>Default value</td>
                        <td>Description</td>
                    </tr>
                </thead>
                <tr>
                    <td>
                        <literal>name</literal>
                    </td>
                    <td>
                        <classname>String</classname> (read-only)
                    </td>
                    <td>
                        Not null
                    </td>
                    <td>
                        The name of the source set, used to identify it.
                    </td>
                </tr>
                <tr>
                    <td>
                        <literal>output</literal>
                    </td>
                    <td>
                        <apilink class="org.gradle.api.tasks.SourceSetOutput"/> (read-only)
                    </td>
                    <td>
                        Not null
                    </td>
                    <td>
                        The output files of the source set, containing its compiled classes and resources.
                    </td>
                </tr>
                <tr>
                    <td>
                        <literal>output.classesDir</literal>
                    </td>
                    <td>
                        <classname>File</classname>
                    </td>
                    <td>
                        <literal><replaceable>buildDir</replaceable>/classes/<replaceable>name</replaceable></literal>
                    </td>
                    <td>
                        The directory to generate the classes of this source set into.
                    </td>
                </tr>
                <tr>
                    <td>
                        <literal>output.resourcesDir</literal>
                    </td>
                    <td>
                        <classname>File</classname>
                    </td>
                    <td>
                        <literal><replaceable>buildDir</replaceable>/resources/<replaceable>name</replaceable></literal>
                    </td>
                    <td>
                        The directory to generate the resources of this source set into.
                    </td>
                </tr>
                <tr>
                    <td>
                        <literal>compileClasspath</literal>
                    </td>
                    <td>
                        <apilink class="org.gradle.api.file.FileCollection"/>
                    </td>
                    <td>
                        <literal>compile<replaceable>SourceSet</replaceable></literal> configuration.
                    </td>
                    <td>
                        The classpath to use when compiling the source files of this source set.
                    </td>
                </tr>
                <tr>
                    <td>
                        <literal>runtimeClasspath</literal>
                    </td>
                    <td>
                        <apilink class="org.gradle.api.file.FileCollection"/>
                    </td>
                    <td>
                        <literal>output</literal> + <literal>runtime<replaceable>SourceSet</replaceable></literal> configuration.
                    </td>
                    <td>
                        The classpath to use when executing the classes of this source set.
                    </td>
                </tr>
                <tr>
                    <td>
                        <literal>java</literal>
                    </td>
                    <td>
                        <apilink class="org.gradle.api.file.SourceDirectorySet"/> (read-only)
                    </td>
                    <td>
                        Not null
                    </td>
                    <td>
                        The Java source files of this source set. Contains only <filename>.java</filename> files
                        found in the Java source directories, and excludes all other files.
                    </td>
                </tr>
                <tr>
                    <td>
                        <literal>java.srcDirs</literal>
                    </td>
                    <td>
                        <classname>Set&lt;File></classname>. Can set using anything described in <xref linkend="sec:specifying_multiple_files"/>.
                    </td>
                    <td>
                        <literal>[<replaceable>projectDir</replaceable>/src/<replaceable>name</replaceable>/java]</literal>
                    </td>
                    <td>
                        The source directories containing the Java source files of this source set.
                    </td>
                </tr>
                <tr>
                    <td>
                        <literal>resources</literal>
                    </td>
                    <td>
                        <apilink class="org.gradle.api.file.SourceDirectorySet"/> (read-only)
                    </td>
                    <td>
                        Not null
                    </td>
                    <td>
                        The resources of this source set. Contains only resources, and excludes any
                        <filename>.java</filename> files found in the resource source directories. Other plugins,
                        such as the Groovy plugin, exclude additional types of files from this collection.
                    </td>
                </tr>
                <tr>
                    <td>
                        <literal>resources.srcDirs</literal>
                    </td>
                    <td>
                        <classname>Set&lt;File></classname>. Can set using anything described in <xref linkend="sec:specifying_multiple_files"/>.
                    </td>
                    <td>
                        <literal>[<replaceable>projectDir</replaceable>/src/<replaceable>name</replaceable>/resources]</literal>
                    </td>
                    <td>
                        The source directories containing the resources of this source set.
                    </td>
                </tr>
                <tr>
                    <td>
                        <literal>allJava</literal>
                    </td>
                    <td>
                        <apilink class="org.gradle.api.file.SourceDirectorySet"/> (read-only)
                    </td>
                    <td>
                        <literal>java</literal>
                    </td>
                    <td>
                        All <filename>.java</filename> files of this source set. Some plugins, such as the Groovy plugin,
                        add additional Java source files to this collection.
                    </td>
                </tr>
                <tr>
                    <td>
                        <literal>allSource</literal>
                    </td>
                    <td>
                        <apilink class="org.gradle.api.file.SourceDirectorySet"/> (read-only)
                    </td>
                    <td>
                        <literal>resources + java</literal>
                    </td>
                    <td>
                        All source files of this source set. This include all resource files and all Java source files.
                        Some plugins, such as the Groovy plugin, add additional source files to this collection.
                    </td>
                </tr>
            </table>
        </section>

        <section>
            <title>Defining new source sets</title>
            <para>To define a new source set, you simply reference it in the <literal>sourceSets { }</literal> block. Here's an example:
            </para>
            <sample id="defineSourceSet" dir="userguide/java/sourceSets" title="Defining a source set">
                <sourcefile file="build.gradle" snippet="define-source-set"/>
            </sample>
            <para>
                When you define a new source set, the Java plugin adds some dependency configurations for the
                source set, as shown in <xref linkend="java_source_set_configurations"/>. You can use these configurations to
                define the compile and runtime dependencies of the source set.
            </para>
            <sample id="sourceSetDependencies" dir="userguide/java/sourceSets" title="Defining source set dependencies">
                <sourcefile file="build.gradle" snippet="source-set-dependencies"/>
            </sample>
            <para>
                The Java plugin also adds a number of tasks which assemble the classes for the
                source set, as shown in <xref linkend="java_source_set_tasks"/>. For example, for a source set called
                <literal>intTest</literal>, you can run <userinput>gradle intTestClasses</userinput> to compile the
                int test classes.
            </para>
            <sample id="compileSourceSet" dir="userguide/java/sourceSets" title="Compiling a source set">
                <output args="intTestClasses"/>
            </sample>
        </section>

        <section>
            <title>Some source set examples</title>
            <para>Adding a JAR containing the classes of a source set:</para>
            <sample id="configureSourceSet" dir="userguide/java/sourceSets" title="Assembling a JAR for a source set">
                <sourcefile file="build.gradle" snippet="jar"/>
            </sample>
            <para>Generating Javadoc for a source set:</para>
            <sample id="configureSourceSet" dir="userguide/java/sourceSets" title="Generating the Javadoc for a source set">
                <sourcefile file="build.gradle" snippet="javadoc"/>
            </sample>
            <para>Adding a test suite to run the tests in a source set:</para>
            <sample id="configureSourceSet" dir="userguide/java/sourceSets" title="Running tests in a source set">
                <sourcefile file="build.gradle" snippet="test"/>
            </sample>
        </section>
    </section>

    <section id='sec:javadoc'>
        <title>Javadoc</title>
        <para>The <literal>javadoc</literal> task is an instance of <apilink class="org.gradle.api.tasks.javadoc.Javadoc"/>.
            It supports the core javadoc options and the options of the standard doclet described in the
            <ulink url='http://download.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#referenceguide'>reference documentation</ulink>
            of the Javadoc executable.
            For a complete list of supported Javadoc options consult the API documentation of the following classes:
            <apilink class="org.gradle.external.javadoc.CoreJavadocOptions"/> and <apilink class="org.gradle.external.javadoc.StandardJavadocDocletOptions"/>.
        </para>
        <table>
            <title>Java plugin - Javadoc properties</title>
            <thead>
                <tr>
                    <td>Task Property</td>
                    <td>Type</td>
                    <td>Default Value</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>classpath</literal>
                </td>
                <td><apilink class="org.gradle.api.file.FileCollection"/></td>
                <td><literal>sourceSets.main.output + sourceSets.main.compileClasspath</literal></td>
            </tr>
            <tr>
                <td><literal>source</literal></td>
                <td><apilink class="org.gradle.api.file.FileTree"/>. Can set using anything described in <xref linkend="sec:specifying_multiple_files"/>.</td>
                <td><literal>sourceSets.main.allJava</literal></td>
            </tr>
            <tr>
                <td>
                    <literal>destinationDir</literal>
                </td>
                <td><classname>File</classname></td>
                <td><filename><replaceable>docsDir</replaceable>/javadoc</filename></td>
            </tr>
            <tr>
                <td>
                    <literal>title</literal>
                </td>
                <td><classname>String</classname></td>
                <td>The name and version of the project</td>
            </tr>
        </table>
    </section>

    <section id='sec:clean'>
        <title>Clean</title>
        <para>The <literal>clean</literal> task is an instance of <apilink class="org.gradle.api.tasks.Delete"/>. It
            simply removes the directory denoted by its <literal>dir</literal>
            property.
        </para>
        <table>
            <title>Java plugin - Clean properties</title>
            <thead>
                <tr>
                    <td>Task Property</td>
                    <td>Type</td>
                    <td>Default Value</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>dir</literal>
                </td>
                <td><classname>File</classname></td>
                <td><filename><replaceable>buildDir</replaceable></filename></td>
            </tr>
        </table>
    </section>

    <section id='sec:resources'>
        <title>Resources</title>
        <para>The Java plugin uses the <apilink class="org.gradle.api.tasks.Copy"/> task for resource handling. It adds an
            instance for each source set in the project. You can find out more about the copy task in
            <xref linkend="sec:copying_files"/>.
        </para>
        <table>
            <title>Java plugin - ProcessResources properties</title>
            <thead>
                <tr>
                    <td>Task Property</td>
                    <td>Type</td>
                    <td>Default Value</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>srcDirs</literal>
                </td>
                <td><classname>Object</classname>. Can set using anything described in <xref linkend="sec:specifying_multiple_files"/>.</td>
                <td><literal><replaceable>sourceSet</replaceable>.resources</literal></td>
            </tr>
            <tr>
                <td>
                    <literal>destinationDir</literal>
                </td>
                <td><classname>File</classname>. Can set using anything described in <xref linkend="sec:locating_files"/>.</td>
                <td><literal><replaceable>sourceSet</replaceable>.output.resourcesDir</literal></td>
            </tr>
        </table>
    </section>

    <section id='sec:compile'>
        <title>CompileJava</title>
        <para>The Java plugin adds a <apilink class="org.gradle.api.tasks.compile.JavaCompile"/> instance for each
            source set in the project. Some of the most common configuration options are shown below.
        </para>
        <table>
            <title>Java plugin - Compile properties</title>
            <thead>
                <tr>
                    <td>Task Property</td>
                    <td>Type</td>
                    <td>Default Value</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>classpath</literal>
                </td>
                <td><apilink class="org.gradle.api.file.FileCollection"/></td>
                <td><literal><replaceable>sourceSet</replaceable>.compileClasspath</literal></td>
            </tr>
            <tr>
                <td>
                    <literal>source</literal>
                </td>
                <td><apilink class="org.gradle.api.file.FileTree"/>. Can set using anything described in <xref linkend="sec:specifying_multiple_files"/>.</td>
                <td><literal><replaceable>sourceSet</replaceable>.java</literal></td>
            </tr>
            <tr>
                <td>
                    <literal>destinationDir</literal>
                </td>
                <td><classname>File</classname>.</td>
                <td><literal><replaceable>sourceSet</replaceable>.output.classesDir</literal></td>
            </tr>
        </table>

        <para>The compile task delegates to Ant's javac task. Setting <literal>options.useAnt</literal> to <literal>false</literal>
            activates Gradle's direct compiler integration, bypassing the Ant task. In a future Gradle release, this will become the default.
        </para>

        <para>By default, the Java compiler runs in the Gradle process. Setting <literal>options.fork</literal> to <literal>true</literal>
            causes compilation to occur in a separate process. In the case of the Ant javac task, this means that a new process will be
            forked for each compile task, which can slow down compilation. Conversely, Gradle's direct compiler integration (see above) will
            reuse the same compiler process as much as possible. In both cases, all fork options specified
            with <literal>options.forkOptions</literal> will be honored.
        </para>
    </section>

    <section id='sec:java_test'>
        <title>Test</title>
        <para>The <literal>test</literal> task is an instance of <apilink class="org.gradle.api.tasks.testing.Test"/>.
            It automatically detects and executes all unit tests in the <literal>test</literal> source set.
            It also generates a report once test execution is complete. JUnit and TestNG are both supported.
            Have a look at <apilink class="org.gradle.api.tasks.testing.Test"/> for the complete API.
        </para>

        <section>
            <title>Test execution</title>
            <para>Tests are executed in a separate JVM, isolated from the main build process. The <apilink class="org.gradle.api.tasks.testing.Test"/> task's
                API allows you some control over how this happens.
            </para>
            <para>There are a number of properties which control how the test process is launched. This includes
                things such as system properties, JVM arguments, and the Java executable to use. The task also provides a
                <literal>debug</literal> property, which when set to true, starts the test process in debug mode,
                suspended and listening on port 5005. This makes it very easy to debug your tests.  You may also enable
                this using a system property as specified below.
            </para>
            <para>You can specify whether or not to execute your tests in parallel. Gradle provides parallel test execution
                by running multiple test processes concurrently. Each test process executes only a single test at a time, so you
                generally don't need to do anything special to your tests to take advantage of this.
                The <literal>maxParallelForks</literal> property specifies the maximum number of test processes to run
                at any given time. The default is 1, that is, do not execute the tests in parallel.
            </para>
            <para>The test process sets the <literal>org.gradle.test.worker</literal> system property to a unique
                identifier for that test process, which you can use, for example, in files names or other
                resource identifiers.
            </para>
            <para>You can specify that test processes should be restarted after it has executed a certain number of
                test classes. This can be a useful alternative to giving your test process a very large
                heap.
                The <literal>forkEvery</literal> property specifies the
                maximum number of test classes to execute in a test process. The default is to execute an unlimited number
                of tests in each test process.</para>
            <para>The task has an <literal>ignoreFailures</literal> property to control the behavior when tests fail.
                Test always executes every test that it detects. It stops the build afterwards if <literal>ignoreFailures</literal>
                is false and there are failing tests. The default value of <literal>ignoreFailures</literal> is false.
            </para>
            <para>The <literal>testLogging</literal> property allows to configure which test events are going to be logged and at
                which detail level. By default, a concise message will be logged for every failed test. See
                <apilink class="org.gradle.api.tasks.testing.logging.TestLoggingContainer"/> for how to tune test logging to your
                preferences.
            </para>
        </section>

        <section id="test_filtering">

            <title>Test filtering</title>

            <para>Starting with Gradle 1.10, it is possible to include only specific tests, based on the test name pattern.
                Filtering is a different mechanism than test class inclusion / exclusion that will be described in the next few paragraphs
                (<literal>-Dtest.single</literal>, <literal>test.include</literal> and friends).
                The latter is based on files, e.g. the physical location of the test implementation class.
                File-level test selection does not support many interesting scenarios that are possible with test-level filtering.
                Some of them Gradle handles now and some will be satisfied in the future releases:
                <itemizedlist>
                    <listitem>Filtering at the level of specific test methods; executing a single test method</listitem>
                    <listitem>Filtering based on custom annotations (future)</listitem>
                    <listitem>Filtering based on test hierarchy; executing all tests that extend ceratain base class (future)</listitem>
                    <listitem>Filtering based on some custom runtime rule, e.g. particular value of a system property or some static state (future)</listitem>
                </itemizedlist>
            </para>

            <para>
                Test filtering feature has following characteristic:
                <itemizedlist>
                    <listitem>Fully qualified class name or fully qualified method name is supported,
                        e.g. "org.gradle.SomeTest", "org.gradle.SomeTest.someMethod"</listitem>
                    <listitem>Wildcard '*' is supported for matching any characters</listitem>
                    <listitem>Command line option "--tests" is provided to conveniently set the test filter.
                        Especially useful for the classic 'single test method execution' use case.
                        When the command line option is used, the inclusion filters declared in the build script are ignored.
                    </listitem>
                    <listitem>Gradle tries best to filter the tests given limitations of particular test framework API.
                        Some advanced, synthetic tests may not be fully compatible with filtering.
                        However, vast majority of tests and use cases should be handled neatly.
                    </listitem>
                    <listitem>Test filtering supersedes the file-based test selection. The latter may be completely replaced in future.
                        We will grow the the test filtering api and add more kinds of filters.
                    </listitem>
                </itemizedlist>
            </para>

            <para>
                <sample id="testfiltering" dir="testing/filtering" title="Filtering tests in the build script">
                    <sourcefile file="build.gradle" snippet="test-filtering"/>
                </sample>
                For more details and examples please see the <apilink class="org.gradle.api.tasks.testing.TestFilter"/> reference.
            </para>

            <para>
                Some examples of using the command line option:

                <itemizedlist>
                    <listitem>
                        <para><literal>gradle test --tests org.gradle.SomeTest.someSpecificFeature</literal></para>
                    </listitem>
                    <listitem>
                        <para><literal>gradle test --tests SomeTest.someSpecificFeature</literal></para>
                    </listitem>
                    <listitem>
                        <para><literal>gradle test --tests SomeSpecificTest</literal></para>
                    </listitem>
                    <listitem>
                        <para><literal>gradle test --tests all.in.specific.package*</literal></para>
                    </listitem>
                    <listitem>
                        <para><literal>gradle test --tests *IntegTest</literal></para>
                    </listitem>
                    <listitem>
                        <para><literal>gradle test --tests *IntegTest*ui*</literal></para>
                    </listitem>
                    <listitem>
                        <para><literal>gradle someTestTask --tests *UiTest someOtherTestTask --tests *WebTest*ui</literal></para>
                    </listitem>
                </itemizedlist>
            </para>
        </section>

        <section>
            <title>System properties</title>
            <para>There are two system properties that can affect test execution.  Both of these are based off
                  of the name of the test task with a suffix. If you are interested in selecting specific tests for execution
                make sure you read the previous paragraph on test filtering because the latter feature is more robust.
            </para>
            <para>Setting a system property of <replaceable>taskName.single</replaceable> = <replaceable>testNamePattern</replaceable>
                  will only execute tests that match the specified <replaceable>testNamePattern</replaceable>.
                  The <replaceable>taskName</replaceable> can be a full multi-project path like &quot;:sub1:sub2:test&quot;
                  or just the task name.  The <replaceable>testNamePattern</replaceable> will be used to form an include
                  pattern of &quot;**/testNamePattern*.class&quot;.
                  If no tests with this pattern can be found an exception is thrown. This is to shield you from false security.
                  If tests of more then one subproject are executed, the pattern is applied to each subproject. An exception
                  is thrown if no tests can be found for a particular subproject. In such a case you can use the path notation of the
                  pattern, so that the pattern is applied only to the test task of a specific subproject. Alternatively you can specify the fully
                  qualified task name to be executed. You can also specify multiple patterns. Examples:
                  <itemizedlist>
                      <listitem>
                          <para><literal>gradle -Dtest.single=ThisUniquelyNamedTest test</literal></para>
                      </listitem>
                      <listitem>
                          <para><literal>gradle -Dtest.single=a/b/ test</literal></para>
                      </listitem>
                      <listitem>
                          <para><literal>gradle -DintegTest.single=*IntegrationTest integTest</literal></para>
                      </listitem>
                      <listitem>
                          <para><literal>gradle -Dtest.single=:proj1:test:Customer build</literal></para>
                      </listitem>
                      <listitem>
                          <para><literal>gradle -DintegTest.single=c/d/ :proj1:integTest</literal></para>
                      </listitem>
                  </itemizedlist>
            </para>
            <para>Setting a system property of <literal>taskName.debug</literal> will run the tests in debug mode,
                  suspended and listening on port 5005.  For example:
                  <literal>gradle test -Dtest.single=ThisUniquelyNamedTest -Dtest.debug</literal>
            </para>
        </section>

        <section>
            <title>Test detection</title>
            <para>The <literal>Test</literal> task detects which classes are test classes by inspecting the compiled test classes.
                By default it scans all <filename>.class</filename> files. You can set custom includes / excludes, only those
                classes will be scanned. Depending on the test framework used (JUnit / TestNG) the test class detection
                uses different criteria.
            </para>
            <para>
                When using JUnit, we scan for both JUnit 3 and 4 test classes. If any of the following criteria match, the
                class is considered to be a JUnit test class:
                <itemizedlist>
                    <listitem>
                        <para>Class or a super class extends <classname>TestCase</classname> or <classname>GroovyTestCase</classname></para>
                    </listitem>
                    <listitem>
                        <para>Class or a super class is annotated with <classname>@RunWith</classname></para>
                    </listitem>
                    <listitem>
                        <para>Class or a super class contain a method annotated with <classname>@Test</classname></para>
                    </listitem>
                </itemizedlist>
            </para>
            <para>
                When using TestNG, we scan for methods annotated with <classname>@Test</classname>.
            </para>
            <para>
                Note that abstract classes are not executed. Gradle also scan up the inheritance tree into jar files
                on the test classpath.
            </para>
            <para>
                In case you don't want to use the test class detection, you can disable it by setting
                <literal>scanForTestClasses</literal> to false. This will make the test task only use the includes /
                excludes to find test classes.

                If <literal>scanForTestClasses</literal> is disabled and no include or exclude patterns are specified, the
                respective defaults are used. For include this is <literal>"**/*Tests.class", "**/*Test.class"</literal>
                and the for exclude it is <literal>"**/Abstract*.class"</literal>.
            </para>
        </section>

        <section id="test_grouping">
            <title>Test grouping</title>
            <para>JUnit and TestNG allows sophisticated groupings of test methods. </para>
            <para>For grouping JUnit test classes and methods JUnit 4.8 introduces the concept of categories.
                <footnote>
                    <para>The JUnit wiki contains a detailed description on how to work with JUnit categories:
                        <ulink url='https://github.com/junit-team/junit/wiki/Categories'/>.
                    </para>
                </footnote>
                The <literal>test</literal> task allows the specification of the JUnit categories you want to include and exclude.
            </para>
            <sample id="junitcategories" dir="testing/junit/categories" title="JUnit Categories">
                <sourcefile file="build.gradle" snippet="test-categories"/>
            </sample>
            <para>The TestNG framework has a quite similar concept. In TestNG you can specify different test groups.
                <footnote>
                    <para>The TestNG documentation contains more details about test groups:
                        <ulink url='http://testng.org/doc/documentation-main.html#test-groups'/>.
                    </para>
                </footnote> The test groups that should be included or excluded from the test execution can be configured in the test task. </para>
            <sample id="testnggrouping" dir="testing/testng/groups" title="Grouping TestNG tests">
                <sourcefile file="build.gradle" snippet="test-config"/>
            </sample>
        </section>
        <section id="test_reporting">
            <title>Test reporting</title>

            <para>The <literal>Test</literal> task generates the following results by default.</para>
            <itemizedlist>
                <listitem><para>An HTML test report.</para></listitem>
                <listitem><para>The results in an XML format that is compatible with the Ant JUnit report task. This format is supported by many
                    other tools, such as CI servers.</para></listitem>
                <listitem><para>Results in an efficient binary format. The task generates the other results from these binary results.</para></listitem>
            </itemizedlist>

            <para>You can disable the HTML test report using the <apilink class="org.gradle.api.tasks.testing.Test" method="setTestReport"/> method. The other
                results currently cannot be disabled.
            </para>

            <para>There is also a stand-alone <apilink class="org.gradle.api.tasks.testing.TestReport"/> task type which can generate the HTML test
                report from the binary results generated by one or more <classname>Test</classname> task instances. To use this task type, you need
                to define a <literal>destinationDir</literal> and the test results to include in the report. Here is a sample which generates a
                combined report for the unit tests from subprojects:
            </para>
            <sample id="subProjectsTestReport" dir="testing/testReport" title="Creating a unit test report for subprojects">
                <sourcefile file="build.gradle" snippet="test-report"/>
            </sample>

            <para>You should note that the <literal>TestReport</literal> type combines the results from multiple test
                tasks, but it does not aggregate the results of individual test classes. This means that if a given test class is executed by
                multiple test tasks, then the test report will include only one execution of that class and discard the other executions of that
                class. This will be addressed in a future Gradle version.
            </para>
            <section id="testNgParameterizedReporting">
                <title>TestNG parameterized methods and reporting</title>
                <para>
                    TestNG supports <ulink url="http://testng.org/doc/documentation-main.html#parameters">parameterizing test methods</ulink>,
                    allowing a particular test method to be executed multiple times with different inputs. Gradle includes the parameter values
                    in its reporting of the test method execution.
                </para>
                <para>
                    Given a parameterized test method named <literal>aParameterizedTestMethod</literal> that takes two parameters, it will be reported with the name:
                    <literal>aParameterizedTestMethod(toStringValueOfParam1, toStringValueOfParam2)</literal>. This makes identifying the parameter values for a
                    particular iteration easy.
                </para>
            </section>
        </section>

        <section>
            <title>Convention values</title>
            <table>
                <title>Java plugin - test properties</title>
                <thead>
                    <tr>
                        <td>Task Property</td>
                        <td>Type</td>
                        <td>Default Value</td>
                    </tr>
                </thead>
                <tr>
                    <td><literal>testClassesDir</literal></td>
                    <td><classname>File</classname></td>
                    <td><literal>sourceSets.test.output.classesDir</literal></td>
                </tr>
                <tr>
                    <td><literal>classpath</literal></td>
                    <td><apilink class="org.gradle.api.file.FileCollection"/></td>
                    <td><literal>sourceSets.test.runtimeClasspath</literal></td>
                </tr>
                <tr>
                    <td><literal>testResultsDir</literal></td>
                    <td><classname>File</classname></td>
                    <td><literal>testResultsDir</literal></td>
                </tr>
                <tr>
                    <td><literal>testReportDir</literal></td>
                    <td><classname>File</classname></td>
                    <td><literal>testReportDir</literal></td>
                </tr>
                <tr>
                    <td><literal>testSrcDirs</literal></td>
                    <td><classname>List&lt;File></classname></td>
                    <td><literal>sourceSets.test.java.srcDirs</literal></td>
                </tr>
            </table>
        </section>

    </section>

    <section>
        <title>Jar</title>
        <para>The <literal>jar</literal> task creates a JAR file containing the class files and resources of the
            project. The JAR file is declared as an artifact in the <literal>archives</literal> dependency
            configuration. This means that the JAR is available in the classpath of a dependent project. If you upload
            your project into a repository, this JAR is declared as part of the dependency descriptor. You can learn
            more about how to work with archives in <xref linkend="sec:archives"/> and artifact configurations in
            <xref linkend="artifact_management"/>.
        </para>
        <section id='sub:manifest'>
            <title>Manifest</title>
            <para>Each jar or war object has a <literal>manifest</literal>
                property with a separate instance of <apilink class="org.gradle.api.java.archives.Manifest"/>.
                When the archive is generated, a corresponding <literal>MANIFEST.MF</literal> file is written into the
                archive.
            </para>
            <sample id="manifest" dir="userguide/tutorial/manifest" title="Customization of MANIFEST.MF">
                <sourcefile file="build.gradle" snippet="add-to-manifest"/>
            </sample>
            <para>You can create stand alone instances of a <classname>Manifest</classname>. You can use that for example,
                to share manifest information between jars.
            </para>
            <sample id="manifest" dir="userguide/tutorial/manifest" title="Creating a manifest object.">
                <sourcefile file="build.gradle" snippet="custom-manifest"/>
            </sample>
            <para>You can merge other manifests into any <classname>Manifest</classname>
                object. The other manifests might
                be either described by a file path or, like in the example above, by a reference to another <classname>Manifest</classname> object.
            </para>
            <sample id="manifest" dir="userguide/tutorial/manifest" title="Separate MANIFEST.MF for a particular archive">
                <sourcefile file="build.gradle" snippet="merge"/>
            </sample>
            <para>Manifest are merged in the order they are declared by the <literal>from</literal> statement. If
            the based manifest and the merged manifest both define values for the same key, the merged manifest wins by default.
            You can fully customize the merge behavior by adding <literal>eachEntry</literal> actions in which
                you have access to a <apilink class="org.gradle.api.java.archives.ManifestMergeDetails"/> instance for each entry
                of the resulting manifest. The merge is not immediately triggered by the from statement. It is done lazily,
                either when generating the jar, or by calling <literal>writeTo</literal> or <literal>effectiveManifest</literal></para>
            <para>You can easily write a manifest to disk.
            </para>
            <sample id="manifest" dir="userguide/tutorial/manifest" title="Separate MANIFEST.MF for a particular archive">
                <sourcefile file="build.gradle" snippet="write"/>
            </sample>
        </section>
    </section>

    <section id='sec:upload'>
        <title>Uploading</title>
        <para>How to upload your archives is described in <xref linkend="artifact_management"/>.
        </para>
    </section>

</chapter>
