<!--
  ~ Copyright 2011 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.
  -->

<book id="dsl">
    <bookinfo>
        <title>Gradle Build Language Reference</title>
        <titleabbrev>Gradle DSL</titleabbrev>
    </bookinfo>

    <section>
        <title>Introduction</title>
        <para>This reference guide describes the various types which make up the Gradle build language, or DSL.</para>
    </section>

    <section>
        <title>Some basics</title>
        <para>There are a few basic concepts that you should understand, which will help you write Gradle scripts.</para>

        <para>First, Gradle scripts are <firstterm>configuration scripts</firstterm>. As the script executes, it
            configures an object of a particular type. For example, as a build script executes, it configures an
            object of type <apilink class="org.gradle.api.Project"/>. This object is called the <firstterm>delegate object</firstterm>
            of the script. The following table shows the delegate for each type of Gradle script.
        </para>

        <table>
            <title>Script delegates</title>
            <thead>
                <tr>
                    <td>Type of script</td>
                    <td>Delegates to instance of</td>
                </tr>
            </thead>
            <tr>
                <td>Build script</td>
                <td>
                    <apilink class="org.gradle.api.Project"/>
                </td>
            </tr>
            <tr>
                <td>Init script</td>
                <td>
                    <apilink class="org.gradle.api.invocation.Gradle"/>
                </td>
            </tr>
            <tr>
                <td>Settings script</td>
                <td>
                    <apilink class="org.gradle.api.initialization.Settings"/>
                </td>
            </tr>
        </table>

        <para>The properties and methods of the delegate object are available for you to use in the script.</para>

        <para>Second, each Gradle script implements the <apilink class="org.gradle.api.Script"/> interface. This
            interface defines a number of properties and methods which you can use in the script.
        </para>
    </section>

    <!--
      -
      - 1. Adding new types:
      - There are 2 ways to include a new types to this guide:
      -     * Types referenced by a property are automatically included, if there is a corresponding ${typename}.xml in the DSL source directory.
      -     * Types listed in one of the following tables are included. There must be a corresponding ${typename}.xml in the DSL source directory.
      -
      - 2. Adding new sections:
      - The section title should end with 'types' (see AssembleDslDocTask.mergeContent)
      -->

    <section>
        <title>Build script structure</title>
        <para>A build script is made up of zero or more statements and script blocks. Statements can include method calls,
            property assignments, and local variable definitions. A script block is a method call which takes a closure
            as a parameter. The closure is treated as a <firstterm>configuration closure</firstterm> which configures
            some delegate object as it executes. The top level script blocks are listed below.</para>
        <table>
            <title>Build script blocks</title>
            <tr>
                <td>allprojects</td>
            </tr>
            <tr>
                <td>artifacts</td>
            </tr>
            <tr>
                <td>buildscript</td>
            </tr>
            <tr>
                <td>configurations</td>
            </tr>
            <tr>
                <td>dependencies</td>
            </tr>
            <tr>
                <td>repositories</td>
            </tr>
            <tr>
                <td>sourceSets</td>
            </tr>
            <tr>
                <td>subprojects</td>
            </tr>
            <tr>
                <td>publishing</td>
            </tr>
        </table>
        <para>A build script is also a Groovy script, and so can contain those elements allowed in a Groovy script,
            such as method definitions and class definitions.
        </para>
    </section>

    <section>
        <title>Core types</title>
        <para>Listed below are some of the central types which are used in Gradle scripts:</para>
        <table>
            <title>Core types</title>
            <tr>
                <td>org.gradle.api.Project</td>
            </tr>
            <tr>
                <td>org.gradle.api.Task</td>
            </tr>
            <tr>
                <td>org.gradle.api.invocation.Gradle</td>
            </tr>
            <tr>
                <td>org.gradle.api.initialization.Settings</td>
            </tr>
            <tr>
                <td>org.gradle.api.Script</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.SourceSet</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.SourceSetOutput</td>
            </tr>
            <tr>
                <td>org.gradle.api.artifacts.Configuration</td>
            </tr>
            <tr>
                <td>org.gradle.api.artifacts.ResolutionStrategy</td>
            </tr>
            <tr>
                <td>org.gradle.api.dsl.ConventionProperty</td>
            </tr>
            <tr>
                <td>org.gradle.api.plugins.ExtensionAware</td>
            </tr>
            <tr>
                <td>org.gradle.api.plugins.ExtraPropertiesExtension</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.PublishingExtension</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.ivy.IvyPublication</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.ivy.IvyArtifact</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.ivy.IvyArtifactSet</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.ivy.IvyModuleDescriptor</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.maven.MavenPublication</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.maven.MavenArtifact</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.maven.MavenArtifactSet</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.maven.MavenPom</td>
            </tr>
        </table>
    </section>

    <section>
        <title>Container types</title>
        <para>Container types that handle various declarative elements (e.g. dependencies, configurations, artifacts, etc.):</para>
        <table>
            <title>Container types</title>
            <tr>
                <td>org.gradle.api.artifacts.ConfigurationContainer</td>
            </tr>
            <tr>
                <td>org.gradle.api.artifacts.dsl.RepositoryHandler</td>
            </tr>
            <tr>
                <td>org.gradle.api.artifacts.dsl.DependencyHandler</td>
            </tr>
            <tr>
                <td>org.gradle.api.artifacts.dsl.ArtifactHandler</td>
            </tr>
        </table>
    </section>

    <section>
        <title>Help Task types</title>
        <para>Below are the task types that are available for every Gradle project.
            Those task types can also be declared and configured directly in the build script.
        </para>
        <table>
            <title>Help Task types</title>
            <tr>
                <td>org.gradle.api.tasks.diagnostics.TaskReportTask</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.diagnostics.ProjectReportTask</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.diagnostics.DependencyReportTask</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.diagnostics.DependencyInsightReportTask</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.diagnostics.PropertyReportTask</td>
            </tr>
        </table>
    </section>

    <section>
        <title>Task types</title>
        <para>Listed below are the various task types which are available for use in your build script:</para>
        <table>
            <title>Task types</title>
            <tr>
                <td>org.gradle.api.plugins.antlr.AntlrTask</td>
            </tr>
            <tr>
                <td>org.gradle.api.plugins.quality.Checkstyle</td>
            </tr>
            <tr>
                <td>org.gradle.api.plugins.quality.CodeNarc</td>
            </tr>
            <tr>
                <td>org.gradle.api.plugins.buildcomparison.gradle.CompareGradleBuilds</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.compile.Compile</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.Copy</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.application.CreateStartScripts</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.Delete</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.Directory</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ear.Ear</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.Exec</td>
            </tr>
            <tr>
                <td>org.gradle.api.plugins.quality.FindBugs</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.ivy.tasks.GenerateIvyDescriptor</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.maven.tasks.GenerateMavenPom</td>
            </tr>
            <tr>
                <td>org.gradle.api.reporting.GenerateBuildDashboard</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.GradleBuild</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.compile.GroovyCompile</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.javadoc.Groovydoc</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.bundling.Jar</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.compile.JavaCompile</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.javadoc.Javadoc</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.JavaExec</td>
            </tr>
            <tr>
                <td>org.gradle.api.plugins.quality.JDepend</td>
            </tr>
            <tr>
                <td>org.gradle.api.plugins.jetty.JettyRun</td>
            </tr>
            <tr>
                <td>org.gradle.api.plugins.jetty.JettyRunWar</td>
            </tr>
            <tr>
                <td>org.gradle.api.plugins.jetty.JettyStop</td>
            </tr>
            <tr>
                <td>org.gradle.api.plugins.quality.Pmd</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.ivy.tasks.PublishToIvyRepository</td>
            </tr>
            <tr>
                <td>org.gradle.api.publish.maven.tasks.PublishToMavenRepository</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.scala.ScalaCompile</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.scala.ScalaDoc</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.signing.Sign</td>
            </tr>
            <tr>
                <td>org.gradle.api.plugins.sonar.SonarAnalyze</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.Sync</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.bundling.Tar</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.testing.Test</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.testing.TestReport</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.Upload</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.bundling.War</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.wrapper.Wrapper</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.bundling.Zip</td>
            </tr>
        </table>
    </section>

    <section>
        <title>Eclipse/IDEA model types</title>
        <para>Used to configure Eclipse or IDEA plugins</para>
        <table>
            <title>Eclipse/IDEA model types</title>
            <tr>
                <td>org.gradle.plugins.ide.eclipse.model.EclipseModel</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.eclipse.model.EclipseProject</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.eclipse.model.EclipseClasspath</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.eclipse.model.EclipseJdt</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.eclipse.model.EclipseWtp</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.eclipse.model.EclipseWtpComponent</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.eclipse.model.EclipseWtpFacet</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.idea.model.IdeaModel</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.idea.model.IdeaProject</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.idea.model.IdeaModule</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.idea.model.IdeaWorkspace</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.api.XmlFileContentMerger</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.api.FileContentMerger</td>
            </tr>
        </table>
    </section>

    <section>
        <title>Eclipse/IDEA task types</title>
        <para>Tasks contributed by IDE plugins. To configure IDE plugins please use IDE model types.</para>
        <table>
            <title>Eclipse/IDEA task types</title>
            <tr>
                <td>org.gradle.plugins.ide.eclipse.GenerateEclipseProject</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.eclipse.GenerateEclipseClasspath</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.eclipse.GenerateEclipseJdt</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.eclipse.GenerateEclipseWtpComponent</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.eclipse.GenerateEclipseWtpFacet</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.idea.GenerateIdeaModule</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.idea.GenerateIdeaProject</td>
            </tr>
            <tr>
                <td>org.gradle.plugins.ide.idea.GenerateIdeaWorkspace</td>
            </tr>
        </table>
    </section>

</book>