Gradle Build Language Reference

Version 1.1

Introduction

This reference guide describes the various types which make up the Gradle build language, or DSL.

Some basics

There are a few basic concepts that you should understand, which will help you write Gradle scripts.

First, Gradle scripts are configuration scripts. 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 Project. This object is called the delegate object of the script. The following table shows the delegate for each type of Gradle script.

Type of script	Delegates to instance of
Build script	`Project`
Init script	`Gradle`
Settings script	`Settings`

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

Second, each Gradle script implements the Script interface. This interface defines a number of properties and methods which you can use in the script.

Build script structure

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 configuration closure which configures some delegate object as it executes. The top level script blocks are listed below.

Block	Description
`allprojects { }`	Configures this project and each of its sub-projects.
`artifacts { }`	Configures the published artifacts for this project.
`buildscript { }`	Configures the build script classpath for this project.
`configurations { }`	Configures the dependency configurations for this project.
`dependencies { }`	Configures the dependencies for this project.
`repositories { }`	Configures the repositories for this project.
`sourceSets { }`	Configures the source sets of this project.
`subprojects { }`	Configures the sub-projects of this project.

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.

Core types

Listed below are some of the central types which are used in Gradle scripts:

Type	Description
`Project`	This interface is the main API you use to interact with Gradle from your build file. From a `Project`, you have programmatic access to all of Gradle's features.
`Task`	A `Task` represents a single atomic piece of work for a build, such as compiling classes or generating javadoc.
`Gradle`	Represents an invocation of Gradle.
`Settings`	Declares the configuration required to instantiate and configure the hierarchy of `Project` instances which are to participate in a build.
`Script`	This interface is implemented by all Gradle scripts to add in some Gradle-specific methods. As your compiled script class will implement this interface, you can use the methods and properties declared by this interface directly in your script.
`SourceSet`	A `SourceSet` represents a logical group of Java source and resources.
`SourceSetOutput`	A collection of all output directories (compiled classes, processed resources, etc.) - notice that `SourceSetOutput` extends `FileCollection`.
`Configuration`	A `Configuration` represents a group of artifacts and their dependencies. Find more information about declaring dependencies to a configuration or about managing configurations in docs for `ConfigurationContainer`
`ResolutionStrategy`	Defines the strategies around dependency resolution. For example, forcing certain dependency versions, conflict resolutions or snapshot timeouts.
`ConventionProperty`	ConventionProperty can be assigned but cannot be mutated (even if the object is mutable!)
`ExtensionAware`	Objects that can be extended at runtime with other objects.
`ExtraPropertiesExtension`	Additional, ad-hoc, properties for Gradle domain objects.

Container types

Container types that handle various declarative elements (e.g. dependencies, configurations, artifacts, etc.):

Type	Description
`ConfigurationContainer`	A `ConfigurationContainer` is responsible for declaring and managing configurations. See also `Configuration`.
`DependencyHandler`	A `DependencyHandler` is used to declare dependencies. Dependencies are grouped into configurations (see `Configuration`).
`ArtifactHandler`	This class is for defining artifacts to be published and adding them to configurations. Creating publish artifacts does not mean to create an archive. What is created is a domain object which represents a file to be published and information on how it should be published (e.g. the name).
`TestLoggingContainer`	Container for all test logging related options. Different options can be set for each log level. Options that are set directly (without specifying a log level) apply to log level LIFECYCLE. Example:

Task types

Listed below are the various task types which are available for use in your build script:

Type	Description
`AntlrTask`	Generates parsers from Antlr grammars.
`Checkstyle`	Runs Checkstyle against some source files.
`CodeNarc`	Runs CodeNarc against some source files.
`Compile`	Compiles Java source files.
`Copy`	Copies files into a destination directory. This task can also rename and filter files as it copies. The task implements `CopySpec` for specifying what to copy.
`CreateStartScripts`	A `Task` for creating OS dependent start scripts.
`Delete`	Deletes files or directories. Example:
`Directory`	Creates a directory.
`DependencyReportTask`	Displays the dependency tree for a project. Can be configured to output to a file, and to optionally output a graphviz compatible "dot" graph. An instance of this type is used when you execute the `dependencies` task from the command-line.
`Ear`	Assembles an EAR archive.
`Exec`	Executes a command line process. Example:
`FindBugs`	Analyzes code with FindBugs.
`GradleBuild`	Executes a Gradle build.
`GroovyCompile`	Compiles Groovy source files, and optionally, Java source files.
`Groovydoc`	Generates HTML API documentation for Groovy source, and optionally, Java source.
`Jar`	Assembles a JAR archive.
`Javadoc`	Generates HTML API documentation for Java classes.
`JavaExec`	Executes a Java application in a child process.
`JDepend`	Analyzes code with JDepend.
`JettyRun`	Deploys an exploded web application to an embedded Jetty web container. Does not require that the web application be assembled into a war, saving time during the development cycle.
`JettyRunWar`	Deploys a WAR to an embedded Jetty web container.
`JettyStop`	Stops the embedded Jetty web container, if it is running.
`Pmd`	Runs a set of static code analysis rules on Java source code files and generates a report of problems found.
`PropertyReportTask`	Displays the properties of a project. An instance of this type is used when you execute the `properties` task from the command-line.
`ProjectReportTask`	Displays a list of projects in the build. An instance of this type is used when you execute the `projects` task from the command-line.
`ScalaCompile`	Compiles Scala source files, and optionally, Java source files.
`ScalaDoc`	Generates HTML API documentation for Scala source files.
`Sign`	A task for creating digital signature files for one or more; tasks, files, publishable artifacts or configurations.
`SonarAnalyze`	Analyzes a project hierachy and writes the results to the Sonar database.
`Sync`	Synchronises the contents of a destination directory with some source directories and files.
`Tar`	Assembles a TAR archive.
`TaskReportTask`	Displays a list of tasks in the project. An instance of this type is used when you execute the `tasks` task from the command-line.
`Test`	Executes tests. Supports JUnit (3.8.x or 4.x) or TestNG tests.
`Upload`	Uploads the artifacts of a `Configuration` to a set of repositories.
`War`	Assembles a WAR archive.
`Wrapper`	Generates scripts (for *nix and windows) which allow you to build your project with Gradle, without having to install Gradle.
`Zip`	Assembles a ZIP archive.

Eclipse/IDEA model types

Used to configure Eclipse or IDEA plugins

Type	Description
`EclipseModel`	DSL-friendly model of the Eclipse project information. First point of entry when it comes to customizing the eclipse generation
`EclipseProject`	Enables fine-tuning project details (.project file) of the Eclipse plugin
`EclipseClasspath`	Enables fine-tuning classpath details (.classpath file) of the Eclipse plugin
`EclipseJdt`	Enables fine-tuning jdt details of the Eclipse plugin
`EclipseWtp`	Enables fine-tuning wtp/wst details of the Eclipse plugin
`EclipseWtpComponent`	Enables fine-tuning wtp component details of the Eclipse plugin
`EclipseWtpFacet`	Enables fine-tuning wtp facet details of the Eclipse plugin
`IdeaModel`	DSL-friendly model of the IDEA project information. First point of entry when it comes to customizing the IDEA generation.
`IdeaProject`	Enables fine-tuning project details (*.ipr file) of the IDEA plugin.
`IdeaModule`	Enables fine-tuning module details (*.iml file) of the IDEA plugin .
`IdeaWorkspace`	Enables fine-tuning workspace details (*.iws file) of the IDEA plugin.
`XmlFileContentMerger`	Models the generation/parsing/merging capabilities. Adds xml-related hooks.
`FileContentMerger`	Models the generation/parsing/merging capabilities.

Eclipse/IDEA task types

Tasks contributed by IDE plugins. To configure IDE plugins please use IDE model types.

Type	Description
`GenerateEclipseProject`	Generates an Eclipse `.project` file. If you want to fine tune the eclipse configuration
`GenerateEclipseClasspath`	Generates an Eclipse `.classpath` file. If you want to fine tune the eclipse configuration
`GenerateEclipseJdt`	Generates the Eclipse JDT configuration file. If you want to fine tune the eclipse configuration
`GenerateEclipseWtpComponent`	Generates the org.eclipse.wst.common.component settings file for Eclipse WTP. If you want to fine tune the eclipse configuration
`GenerateEclipseWtpFacet`	Generates the org.eclipse.wst.common.project.facet.core settings file for Eclipse WTP. If you want to fine tune the eclipse configuration
`GenerateIdeaModule`	Generates an IDEA module file. If you want to fine tune the idea configuration
`GenerateIdeaProject`	Generates an IDEA project file for root project only. If you want to fine tune the idea configuration
`GenerateIdeaWorkspace`	Generates an IDEA workspace file only for root project. There's little you can configure about workspace generation at the moment.

Backwards compatibility across Gradle versions

Most DSL elements documented here are considered public 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 major version, 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.

Some elements of the DSL are marked as deprecated. 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.

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.

Some elements of the DSL are marked as experimental. 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 experimental element and give us your feedback, but please be aware that it may change in future versions of Gradle. Note that this includes minor versions.

Finally, there are also some internal 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.