<!--
  ~ 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>
        </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>
        </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.DependencyHandler</td>
            </tr>
            <tr>
                <td>org.gradle.api.artifacts.dsl.ArtifactHandler</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.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.api.tasks.diagnostics.DependencyReportTask</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.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.tasks.diagnostics.PropertyReportTask</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.diagnostics.ProjectReportTask</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.diagnostics.TaskReportTask</td>
            </tr>
            <tr>
                <td>org.gradle.api.tasks.testing.Test</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>
            <tr>
                <td>org.gradle.api.plugins.buildcomparison.gradle.CompareGradleBuilds</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>

    <section id="dsl-element-types">
        <title>Backwards compatibility across Gradle versions</title>
        <para>Most DSL elements documented here are considered <firstterm>public</firstterm> elements. This means that they are fully supported
            and will remain unchanged until at least the next major version of Gradle. And in most cases, a feature will be supported well
            beyond the next major version.
            By <firstterm>major version</firstterm>, we mean a change to the first part of the version number. So, if a public feature is available
            in Gradle 1.2, it will continue to be available in Gradle 1.3, Gradle 1.4, and so on until at least Gradle 2.0.
        </para>
        <para>Some elements of the DSL are marked as <firstterm>deprecated</firstterm>. This means that the element is not longer
            intended to be used, and will be removed at some point in the future. In most cases, there is a replacement for the deprecated element,
            and this will be described in the documentation.
        </para>
        <para>
            A deprecated element will not be removed before the next major version of Gradle. You can continue to use the element
            until then. However, you will receive a deprecation warning when you run a build that uses the element, to remind you that the
            element is to be removed.
            We recommend that you change your code so that it no longer uses the deprecated element and uses the appropriate replacement instead.
        </para>
        <para>Some elements of the DSL are marked as <firstterm>incubating</firstterm>. This means that the element is a work-in-progress,
            and may require some changes before it is ready to become public. These changes are based on feedback as these features are used in
            real builds. Please feel free to try an incubating element and give us your feedback, but please be aware that it may change in
            future versions of Gradle, including minor versions.
        </para>
        <para>Finally, there are also some <firstterm>internal</firstterm> undocumented features present in Gradle.
            These are intended to be used in Gradle itself, and may change at any time.
            Internal features are not documented in this DSL reference, the user guide, or in the javadoc and groovydoc API documentation.
            If a feature is not documented, then it is likely an internal feature, and we recommend that you avoid using it.
        </para>
    </section>

</book>