<!--
  ~ Copyright 2009 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>Source sets</title>
        <para>The Java plugin introduces the concept of a <firstterm>source set</firstterm>. A source set is 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>
            You might use a source set to define an integration test suite, or for the API classes of your project, or
            to separate source which needs to be compiled against different Java versions.
        </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>clean</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.Clean"/></td>
                <td>Deletes the project build directory.</td>
            </tr>
            <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.Compile"/></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.Compile"/></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" lang="groovy"/></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>
        </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.Compile"/></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.</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.</td>
            </tr>
        </table>

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

        <figure>
            <title>Java plugin - tasks</title>
            <imageobject>
                <imagedata fileref="images/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>.
            To learn more about configurations see <xref linkend="sub:configurations"/> and
            <xref linkend="artifacts_and_configurations"/>. Note also that transitive dependencies
            are disabled by default for the compile configuration. This can be overridden using:
        </para>
        <programlisting>configurations.compile.transitive = true</programlisting>
        <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, archives</td>
                <td>-</td>
                <td>Artifacts produced <literal>and</literal> dependencies required by this project.
                </td>
            </tr>
        </table>
        <figure>
            <title>Java plugin - dependency configurations</title>
            <imageobject>
                <imagedata fileref="images/javaPluginConfigurations.png"/>
            </imageobject>
        </figure>
    </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>dists</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, eg
                    <literal>'1.5'</literal> or <literal>1.5</literal>.
                </td>
                <td>
                    <literal>1.5</literal>
                </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, eg
                    <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.tasks.bundling.GradleManifest" lang="groovy"/></td>
                <td>an empty manifest</td>
                <td>The manifest to include in all JAR files.</td>
            </tr>
            <tr>
                <td>
                    <literal>metaInf</literal>
                </td>
                <td>
                    <classname>List</classname>
                </td>
                <td><literal>[]</literal></td>
                <td>A set of <link linkend="sec:file_collections">file collections</link> which specify the files to
                    include in the <filename>META-INF</filename> directory or all JAR files.</td>
            </tr>
        </table>

        <para>
            These properties are provided by convention objects of type <apilink class="org.gradle.api.plugins.JavaPluginConvention" lang="groovy"/>,
            <apilink class="org.gradle.api.plugins.BasePluginConvention" lang="groovy"/> and
            <apilink class="org.gradle.api.plugins.ReportingBasePluginConvention" lang="groovy"/>.
        </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> method, which you can pass a closure to which configures 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>
        <para>To define a new source set, you simply reference it in the <literal>sourceSets { }</literal> block.
            When you define a source set, the Java plugin adds a number of tasks which assemble the classes for the
            source set, as shown in <xref linkend="java_source_set_tasks"/>. For example, if you add a source set called
            <literal>intTest</literal>, the Java plugin adds <literal>compileIntTestJava</literal>, <literal>processIntTestResources</literal>
            and <literal>intTestClasses</literal> tasks.
        </para>
        <sample id="defineSourceSet" dir="userguide/java/sourceSets" title="Defining a source set">
            <sourcefile file="build.gradle" snippet="define-source-set"/>
        </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>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>compileClasspath</literal>
                    </td>
                    <td>
                        <apilink class="org.gradle.api.file.FileCollection"/>
                    </td>
                    <td>
                        <literal>compile</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>classesDir</literal> + <literal>runtime</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.FileTree"/> (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.FileTree"/> (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>Some common source set examples</title>
            <para>Using dependency configurations to define the source set classpath:</para>
            <sample id="configureSourceSet" dir="userguide/java/sourceSets" title="Defining the classpath of a source set">
                <sourcefile file="build.gradle" snippet="classpath-using-configurations"/>
            </sample>
            <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://java.sun.com/j2se/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.classes + 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.Clean"/>. 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>.classesDir</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.Compile"/> instance for each
            source set in the project. The compile task delegates to Ant's javac task to do the compile. You can set most
            of the properties of the Ant javac task.
        </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>.classesDir</literal></td>
            </tr>
        </table>
    </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
            executes all unit tests found in the <literal>test</literal> source set.
        </para>
        <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.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>
        <para>Have a look at <apilink class="org.gradle.api.tasks.testing.Test"/>
            for its complete API. Right now the test results are always in XML-format. The task has a
            <literal>stopAtFailuresOrErrors</literal>
            property to control the behavior when tests are failing. Test
            <emphasis>always</emphasis>
            executes all tests. It stops the build afterwards if
            <literal>stopAtFailuresOrErrors</literal>
            is true and there are failing tests or tests that have thrown an uncaught exception.
        </para>
        <para>Per default the tests are run in a forked JVM and the fork is done per test. You can modify this behavior
            by setting forking to false or set the forkmode to once.
        </para>
        <para>The Test task detects which classes are test classes by inspecting the compiled test classes.
            By default it scans all <emphasis>.class</emphasis> 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. Extend TestCase or GroovyTestCase, Class annotated with RunWith or
            contain a method annotated with Test (inherited test methods are detected).
        </para>
        <para>
            When using TestNG, we scan for methods annotated with Test (inherited test methods are detected).
        </para>
        <para>
            Since 0.6.1 we 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 scanForTestClasses to false.
            This will make the test task only use the includes / excludes to find test classes.

            If <code>scanForTestClasses</code> 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>
        <para>Both JUnit and TestNG are supported through their Ant tasks.</para>
        <para>
            Regarding TestNG reporting, when the test report is disabled the default TestNG listeners are disabled
            (options.useDefaultListeners is set to false). 
        </para>
    </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. To learn
            more about how to work with archives and artifact configurations see <xref linkend="artifact_management"/>.
        </para>
    </section>

    <section>
        <title>Adding archives</title>
        <para>If you come from Maven you can have only one library JAR per project. With Gradle you can have as many as
            you want. You can also add WAR, ZIP and TAR archives to your project. They are all added the same way, so
            let's look at how you add a ZIP file.
        </para>
        <sample id="zip" dir="userguide/tutorial/zipProject" title="Creation of ZIP archive">
            <sourcefile file="build.gradle"/>
            <output args="-q myZip"/>
        </sample>
        <para>This adds a Zip archive task with the name <literal>myZip</literal> which produces ZIP file
            <filename>zipProject-1.0.zip</filename>. It is important to distinguish between the name of the archive task
            and the name of the archive generated by the archive task. The name of the generated archive file is by
            default the name of the project with the project version appended. The default name for archives can be
            changed with the <literal>archivesBaseName</literal> project property. The name of the archive can also be
            changed at any time later on.</para>
        <para>There are a number of properties which you can set on an archive task. You can, for example, change the
            name of the archive:
        </para>
        <sample id="zipWithCustomName" dir="userguide/tutorial/zipWithCustomName" title="Configuration of archive task - custom archive name">
            <sourcefile file="build.gradle"/>
            <output args="-q myZip"/>
        </sample>
        <para>You can further customize the archive names:</para>
        <sample id="zipWithArguments" dir="userguide/tutorial/zipWithArguments" title="Configuration of archive task - appendix &amp; classifier">
            <sourcefile file="build.gradle"/>
            <output args="-q myZip"/>
        </sample>
        <para>Often you will want to publish an archive, so that it is usable from another project. This process is
            described in <xref linkend="artifact_management"/>
        </para>

    <section id='sec:archive_tasks'>
        <title>Archive tasks</title>
        <para>An archive task is a task which produces an archive at execution time. The following archive tasks are
            available:
        </para>
        <table>
            <title>Archive tasks</title>
            <thead>
                <tr>
                    <td>Type</td>
                    <td>Accepted file container</td>
                    <td>Extends</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.bundling.Zip" lang="groovy"/>
                </td>
                <td>fileSet, fileCollection, zipFileSet</td>
                <td>AbstractArchiveTask</td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.bundling.Tar" lang="groovy"/>
                </td>
                <td>fileSet, fileCollection, zipFileSet, tarFileSet</td>
                <td>Zip</td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.bundling.Jar" lang="groovy"/>
                </td>
                <td>fileSet, fileCollection, zipFileSet</td>
                <td>Zip</td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.bundling.War" lang="groovy"/>
                </td>
                <td>fileSet, fileCollection, zipFileSet</td>
                <td>Jar</td>
            </tr>

        </table>
        <para>The following file containers are available:
        </para>
        <table id='filecontainer'>
            <title>File container for archives</title>
            <thead>
                <tr>
                    <td>Type</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <apilink class="org.gradle.api.file.FileTree"/>
                </td>
                <td>A set of files defined by a common base directory and include/exclude patterns. See <xref linkend="sec:file_trees"/>.</td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.util.ZipFileSet" lang="groovy"/>
                </td>
                <td>Extends FileSet with additional properties known from Ant's zipfileset task.</td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.util.TarFileSet" lang="groovy"/>
                </td>
                <td>Extends ZipFileSet with additional properties known from Ant's tarfileset task.</td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.file.FileCollection"/>
                </td>
                <td>An arbitrary collection of files to include in the archive. In contrast to a
                    <literal>FileTree</literal> they don't need to have a common base directory. See <xref linkend="sec:file_collections"/>
                    for more details.
                </td>
            </tr>
            <tr>
                <td>
                    <apilink class="org.gradle.api.tasks.util.AntDirective" lang="groovy"/>
                </td>
                <td>An arbitrary Ant resource declaration.</td>
            </tr>

        </table>
        <para>To learn about all the details have a look at the javadoc of the archive task class or the file container
            class itself.
        </para>
        <section id='sub:common_properties'>
            <title>Common properties</title>
            <para>The name of the generated archive is assembled from the task properties <literal>baseName</literal>,
                <literal>appendix</literal>, <literal>version</literal>, <literal>classifier</literal> and
                <literal>extension</literal> into
                <literal><replaceable>baseName</replaceable>-<replaceable>appendix</replaceable>-<replaceable>version</replaceable>-<replaceable>classifier</replaceable>.<replaceable>extension</replaceable></literal>.
                <footnote>
                    <para>If any of these properties is empty the trailing <literal>-</literal> is not added to the name.
                    </para>
                </footnote>
                The assembled name is accessible via the <literal>archiveName</literal> property. The
                <literal>name</literal> property denotes the name of the task, not the generated archive. An archive
                task has also a <literal>customName</literal> property. If this property is set, the
                <literal>archiveName</literal> property returns its value instead of assembling a name out of the
                properties mentioned above.
            </para>
            <para>Archives have a <literal>destinationDir</literal> property to specify where the generated archive
                should be placed. It has also an <literal>archivePath</literal> property, which returns a File object
                with the absolute path of the generated archive.
            </para>
        </section>
        <section id='sub:adding_content'>
            <title>Adding content</title>
            <para>To add content to an archive you must add file container to an archive (see
                <xref linkend='filecontainer'/>). You can add as many file containers as you like. They behave pretty much
                the same as the Ant resources with similar names.
            </para>
            <sample id="archiveContent" dir="userguide/tutorial/archiveContent" title="Adding content to archive - include &amp; exclude">
                <sourcefile file="build.gradle" snippet="file-set"/>
            </sample>
            <para>You can add arbitrary files to an archive:
            </para>
            <sample id="archiveContent" dir="userguide/tutorial/archiveContent" title="Adding content to archive - arbitrary files">
                <sourcefile file="build.gradle" snippet="files"/>
            </sample>
            <para>Other examples:
            </para>
            <sample id="archiveContent" dir="userguide/tutorial/archiveContent" title="Adding content to archive - zipFileSet">
                <sourcefile file="build.gradle" snippet="zip-file-set"/>
            </sample>
            <sample id="archiveContent" dir="userguide/tutorial/archiveContent" title="Creation of TAR archive">
                <sourcefile file="build.gradle" snippet="tar-file-set"/>
            </sample>
            <para>There is also the option to add an arbitrary Ant expression describing an Ant resource.
            </para>
            <programlisting><![CDATA[
myZipTask.antDirective {        
   zipgroupfileset(dir: new File(rootDir, 'lib'))    
}
]]></programlisting>
            <para>This is for rather exotic use cases. Usually you should be fine with the file container provided by
                Gradle.
            </para>
        </section>
        <section id='sub:merging'>
            <title>Merging</title>
            <para>If you want to merge the content of other archives into the archive to be generated Gradle offers you
                two methods. One is <literal>merge</literal>:
            </para>
            <programlisting><![CDATA[
myZipTask.merge('path1/otherArchive1.zip', 'path2/otherArchive.tar.gz')
]]></programlisting>
            <para>This merges the whole content of the archive passed to the merge method into the generated archive. If
                you need more control which content of the archive should be merged and to what path, you can pass a
                closure to the merge method:
            </para>
            <programlisting><![CDATA[
myZipTask.merge('path1/otherArchive1.zip', 'path2/otherArchive.tar.gz') {
	include('**/*.txt')
	exclude('**/*.gif')
	prefix = 'myprefix'
}
]]></programlisting>
            <para>Under the hood Gradle scans the extension of the archives to be merged. According to the extension, it
                creates a
                <literal>ZipFileSet</literal>
                or <literal>TarFileSet</literal>. The closure is applied to this newly created file container. There
                is another method for merging called <literal>mergeGroup</literal>.
            </para>
            <programlisting><![CDATA[
myZipTask.mergeGroup('path_to_dir_with_archives') {
	include('**/*.zip')
	exclude('**/*.tar.gz')
}
]]></programlisting>
            <para>With this method you can assign a set of archives to be merged. Those archives have to be located
                under the directory you pass as an argument. You can define filters what archives should be included.
                They are always included fully and you can't specify a path. If you need this features, you must use the
                <literal>merge</literal> method.
            </para>
        </section>
        <section id='sub:manifest'>
            <title>Manifest</title>
            <para>The convention object of the Java Plugin has a <literal>manifest</literal>
                property pointing to an instance of <apilink class="org.gradle.api.tasks.bundling.GradleManifest" lang="groovy"/>.
                With this <classname>GradleManifest</classname> object you can define the content of the
                <filename>MANIFEST.MF</filename> file for all the jar or a war archives in your project.
            </para>
            <sample id="manifest" dir="userguide/tutorial/manifest" title="Customization of MANIFEST.MF">
                <sourcefile file="build.gradle" snippet="main-attributes"/>
            </sample>
            <para>You can also define sections of a manifest file.
            </para>
            <para>If a particular archive needs unique entries in its manifest you have to create your own
                <classname>GradleManifest</classname> instance for it.
            </para>
            <sample id="manifest" dir="userguide/tutorial/manifest" title="Customization of MANIFEST.MF for a particular archive">
                <sourcefile file="build.gradle" snippet="custom-manifest"/>
            </sample>
            <para>Passing the common manifest object to the constructor of <classname>GradleManifest</classname>
                add the common manifest values to the task specific manifest instance.
            </para>
        </section>
        <section id='sub:metainf'>
            <title>MetaInf</title>
            <para>The convention object of the Java Plugin has a <literal>metaInf</literal> property pointing to a list of
                <classname>FileSet</classname> objects. With these file sets you can define which files should be in the
                <filename>META-INF</filename> directory of a JAR or a WAR archive.
            </para>
            <programlisting><![CDATA[
metaInf << new FileSet(someDir)
]]></programlisting>
        </section>
    </section>
    </section>

    <section id='sec:upload'>
        <title>Uploading</title>
        <para>How to upload your archives is described in <xref linkend="artifact_management"/>.
        </para>
    </section>
    
    <section id='sec:eclipse'>
        <title>Eclipse</title>
        <para>Gradle comes with a number of tasks for generating eclipse files for your projects.
        </para>
        <section id='sub:eclipse_classpath'>
            <title>Eclipse classpath</title>
            <para>
                <apilink class="org.gradle.api.tasks.ide.eclipse.EclipseClasspath"/>
                has a default instance with the name <literal>eclipseCp</literal>. It generates a
                <literal>.classpath</literal> file.
            </para>
            <table>
                <title>Java plugin - Eclipse properties</title>
                <thead>
                    <tr>
                        <td>Task Property</td>
                        <td>Convention Property</td>
                    </tr>
                </thead>
                <tr>
                    <td>srcDirs</td>
                    <td>srcDirs + resourcesDirs</td>
                </tr>
                <tr>
                    <td>testSrcDirs</td>
                    <td>testSrcDirs + testResourcesDirs</td>
                </tr>
                <tr>
                    <td>outputDirectory</td>
                    <td>classesDir</td>
                </tr>
                <tr>
                    <td>testOutputDirectory</td>
                    <td>testClassesDir</td>
                </tr>
                <tr>
                    <td>classpathLibs</td>
                    <td>the resolve result for
                        <literal>testRuntime</literal>
                    </td>
                </tr>

            </table>
        </section>
        <section id='sub:eclipse_project'>
            <title>Eclipse project</title>
            <para>
                <apilink class="org.gradle.api.tasks.ide.eclipse.EclipseProject"/>
                has a default instance with the name <literal>eclipseProject</literal>. It generates a
                <literal>.project</literal> file.
            </para>
            <table>
                <title>Java plugin - Eclipse project properties</title>
                <thead>
                    <tr>
                        <td>Task Property</td>
                        <td>Convention Property</td>
                    </tr>
                </thead>
                <tr>
                    <td>name</td>
                    <td>project.name</td>
                </tr>
                <tr>
                    <td>projectType</td>
                    <td>ProjectType.JAVA</td>
                </tr>

            </table>
            <para>The java plugin also provides a task called
                <literal>eclipse</literal>
                which generates both of the eclipse tasks mentioned above. If you are using the war plugin,
                <literal>eclipse</literal>
                also leads to the execution of the
                <literal>eclipseWtp</literal>
                task.
            </para>
        </section>
    </section>
</chapter>
