# Gradle

API Documentation: | `Gradle`

Represents an invocation of Gradle.

You can obtain a `Gradle` instance by calling `Project.getGradle()`.

### Properties

Property | Description
`buildPath` | Get the path of this build relative to the root build.
`extensions` | The container of extensions.
`gradle` | Returns this `Gradle` instance. This method is useful in init scripts to explicitly access Gradle properties and methods. For example, using `gradle.parent` can express your intent better than using `parent`. This property also allows you to access Gradle properties from a scope where the property may be hidden, such as, for example, from a method or closure.
`gradleHomeDir` | The Gradle home directory, if any. This directory is the directory containing the Gradle distribution executing this build.
`gradleUserHomeDir` | The Gradle user home directory. This directory is used to cache downloaded resources, compiled build scripts and so on.
`gradleVersion` | The current Gradle version.
`includedBuilds` | The included builds for this build.
`parent` | The parent build of this build, if any.
`pluginManager` | The plugin manager for this plugin aware object.
`plugins` | The container of plugins that have been applied to this object.
`rootProject` | The root project of this build.
`startParameter` | The `StartParameter` used to start this build.
`taskGraph` | The `TaskExecutionGraph` for this build.

### Methods

Method | Description
`addBuildListener(buildListener)` | Adds a `BuildListener` to this Build instance. The listener is notified of events which occur during the execution of the build.
`addListener(listener)` | Adds the given listener to this build. The listener may implement any of the given listener interfaces:
`addProjectEvaluationListener(listener)` | Adds a listener to this build, to receive notifications as projects are evaluated.
`afterProject(closure)` | Adds a closure to be called immediately after a project is evaluated. The project is passed to the closure as the first parameter. The project evaluation failure, if any, is passed as the second parameter. Both parameters are optional.
`afterProject(action)` | Adds an action to be called immediately after a project is evaluated.
`allprojects(action)` | Adds an action to execute against all projects of this build. The action is executed immediately against all projects which are already available. It is also executed as subsequent projects are added to this build.
`apply(closure)` | Applies zero or more plugins or scripts.
`apply(options)` | Applies a plugin or script, using the given options provided as a map. Does nothing if the plugin has already been applied.
`apply(action)` | Applies zero or more plugins or scripts.
`beforeProject(closure)` | Adds a closure to be called immediately before a project is evaluated. The project is passed to the closure as a parameter.
`beforeProject(action)` | Adds an action to be called immediately before a project is evaluated.
`beforeSettings(closure)` | Adds an action to be called before the build settings have been loaded and evaluated.
`beforeSettings(action)` | Adds an action to be called before the build settings have been loaded and evaluated.
`buildFinished(closure)` | Deprecated Adds a closure to be called when the build is completed. All selected tasks have been executed. A `BuildResult` instance is passed to the closure as a parameter.
`buildFinished(action)` | Deprecated Adds an action to be called when the build is completed. All selected tasks have been executed.
`includedBuild(name)` | Returns the included build with the specified name for this build.
`projectsEvaluated(closure)` | Adds a closure to be called when all projects for the build have been evaluated. The project objects are fully configured and are ready to use to populate the task graph. This `Gradle` instance is passed to the closure as a parameter.
`projectsEvaluated(action)` | Adds an action to be called when all projects for the build have been evaluated. The project objects are fully configured and are ready to use to populate the task graph.
`projectsLoaded(closure)` | Adds a closure to be called when the projects for the build have been created from the settings. None of the projects have been evaluated. This `Gradle` instance is passed to the closure as a parameter.
`projectsLoaded(action)` | Adds an action to be called when the projects for the build have been created from the settings. None of the projects have been evaluated.
`removeListener(listener)` | Removes the given listener from this build.
`removeProjectEvaluationListener(listener)` | Removes the given listener from this build.
`rootProject(action)` | Adds an action to execute against the root project of this build. If the root project is already available, the action is executed immediately. Otherwise, the action is executed when the root project becomes available.
`settingsEvaluated(closure)` | Adds a closure to be called when the build settings have been loaded and evaluated. The settings object is fully configured and is ready to use to load the build projects. The `Settings` object is passed to the closure as a parameter.
`settingsEvaluated(action)` | Adds an action to be called when the build settings have been loaded and evaluated. The settings object is fully configured and is ready to use to load the build projects.
`useLogger(logger)` | Deprecated Uses the given object as a logger. The logger object may implement any of the listener interfaces supported by `Gradle.addListener(java.lang.Object)`.

### Script blocks

No script blocks

### Property details

#### `String` `buildPath` (read-only)

Get the path of this build relative to the root build.

#### `ExtensionContainer` `extensions` (read-only)

The container of extensions.

#### `Gradle` `gradle` (read-only)

Returns this `Gradle` instance. This method is useful in init scripts to explicitly access Gradle properties and methods. For example, using `gradle.parent` can express your intent better than using `parent`. This property also allows you to access Gradle properties from a scope where the property may be hidden, such as, for example, from a method or closure.

#### `File` `gradleHomeDir` (read-only)

The Gradle home directory, if any. This directory is the directory containing the Gradle distribution executing this build.

When using the "Gradle Daemon", this may not be the same Gradle distribution that the build was started with. If an existing daemon process is running that is deemed compatible (e.g. has the desired JVM characteristics) then this daemon may be used instead of starting a new process and it may have been started from a different "gradle home". However, it is guaranteed to be the same version of Gradle. For more information on the Gradle Daemon, please consult the User Manual.

#### `File` `gradleUserHomeDir` (read-only)

The Gradle user home directory. This directory is used to cache downloaded resources, compiled build scripts and so on.

#### `String` `gradleVersion` (read-only)

The current Gradle version.

#### ``Collection`<`IncludedBuild`>` `includedBuilds` (read-only)

The included builds for this build.

#### `Gradle` `parent` (read-only)

The parent build of this build, if any.

#### `PluginManager` `pluginManager` (read-only)

The plugin manager for this plugin aware object.

#### `PluginContainer` `plugins` (read-only)

The container of plugins that have been applied to this object.

While not deprecated, it is preferred to use the methods of this interface or the `PluginAware.getPluginManager()` than use the plugin container.

Use one of the 'apply' methods on this interface or on the `PluginAware.getPluginManager()` to apply plugins instead of applying via the plugin container.

Use `PluginManager.hasPlugin(java.lang.String)` or similar to query for the application of plugins instead of doing so via the plugin container.

#### `Project` `rootProject` (read-only)

The root project of this build.

#### `StartParameter` `startParameter` (read-only)

The `StartParameter` used to start this build.

#### `TaskExecutionGraph` `taskGraph` (read-only)

The `TaskExecutionGraph` for this build.

### Method details

#### `void` `addBuildListener`(`BuildListener` buildListener)

Adds a `BuildListener` to this Build instance. The listener is notified of events which occur during the execution of the build.

`BuildListener` is not supported when the configuration cache is enabled. Check the individual methods of `BuildListener` for compatible replacements.

#### `void` `addListener`(`Object` listener)

Adds the given listener to this build. The listener may implement any of the given listener interfaces:

- `TaskExecutionGraphListener`
- `ProjectEvaluationListener`
- `DependencyResolutionListener`

The following listener types can be used, but are not supported when configuration caching is enabled. Their usage is deprecated and adding a listener of these types become an error in a future Gradle version:

- `BuildListener`
- `TaskExecutionListener`
- `TaskActionListener`
- `TestListener`
- `TestOutputListener`

#### `ProjectEvaluationListener` `addProjectEvaluationListener`(`ProjectEvaluationListener` listener)

Adds a listener to this build, to receive notifications as projects are evaluated.

#### `void` `afterProject`(`Closure` closure)

Adds a closure to be called immediately after a project is evaluated. The project is passed to the closure as the first parameter. The project evaluation failure, if any, is passed as the second parameter. Both parameters are optional.

#### `void` `afterProject`(``Action`<? super `Project`>` action)

Adds an action to be called immediately after a project is evaluated.

#### `void` `allprojects`(``Action`<? super `Project`>` action)

Adds an action to execute against all projects of this build. The action is executed immediately against all projects which are already available. It is also executed as subsequent projects are added to this build.

#### `void` `apply`(`Closure` closure)

Applies zero or more plugins or scripts.

The given closure is used to configure an `ObjectConfigurationAction`, which "builds" the plugin application.

This method differs from `PluginAware.apply(java.util.Map)` in that it allows methods of the configuration action to be invoked more than once.

#### `void` `apply`(``Map`<`String`, ?>` options)

Applies a plugin or script, using the given options provided as a map. Does nothing if the plugin has already been applied.

The given map is applied as a series of method calls to a newly created `ObjectConfigurationAction`. That is, each key in the map is expected to be the name of a method `ObjectConfigurationAction` and the value to be compatible arguments to that method.

The following options are available:

- `from`: A script to apply. Accepts any path supported by `Project.uri(java.lang.Object)`.
- `plugin`: The id or implementation class of the plugin to apply.
- `to`: The target delegate object or objects. The default is this plugin aware object. Use this to configure objects other than this object.

#### `void` `apply`(``Action`<? super `ObjectConfigurationAction`>` action)

Applies zero or more plugins or scripts.

The given closure is used to configure an `ObjectConfigurationAction`, which "builds" the plugin application.

This method differs from `PluginAware.apply(java.util.Map)` in that it allows methods of the configuration action to be invoked more than once.

#### `void` `beforeProject`(`Closure` closure)

Adds a closure to be called immediately before a project is evaluated. The project is passed to the closure as a parameter.

#### `void` `beforeProject`(``Action`<? super `Project`>` action)

Adds an action to be called immediately before a project is evaluated.

#### `void` `beforeSettings`(``Closure`<?>` closure)

Adds an action to be called before the build settings have been loaded and evaluated.

#### `void` `beforeSettings`(``Action`<? super `Settings`>` action)

Adds an action to be called before the build settings have been loaded and evaluated.

#### `void` `buildFinished`(`Closure` closure)

Note: This method is deprecated and will be removed in the next major version of Gradle.

Adds a closure to be called when the build is completed. All selected tasks have been executed. A `BuildResult` instance is passed to the closure as a parameter.

#### `void` `buildFinished`(``Action`<? super `BuildResult`>` action)

Note: This method is deprecated and will be removed in the next major version of Gradle.

Adds an action to be called when the build is completed. All selected tasks have been executed.

#### `IncludedBuild` `includedBuild`(`String` name)

Returns the included build with the specified name for this build.

#### `void` `projectsEvaluated`(`Closure` closure)

Adds a closure to be called when all projects for the build have been evaluated. The project objects are fully configured and are ready to use to populate the task graph. This `Gradle` instance is passed to the closure as a parameter.

#### `void` `projectsEvaluated`(``Action`<? super `Gradle`>` action)

Adds an action to be called when all projects for the build have been evaluated. The project objects are fully configured and are ready to use to populate the task graph.

#### `void` `projectsLoaded`(`Closure` closure)

Adds a closure to be called when the projects for the build have been created from the settings. None of the projects have been evaluated. This `Gradle` instance is passed to the closure as a parameter.

An example of hooking into the projectsLoaded to configure buildscript classpath from the init script.

    //init.gradle
    gradle.projectsLoaded {
      rootProject.buildscript {
        repositories {
          //...
        }
        dependencies {
          //...
        }
      }
    }

#### `void` `projectsLoaded`(``Action`<? super `Gradle`>` action)

Adds an action to be called when the projects for the build have been created from the settings. None of the projects have been evaluated.

#### `void` `removeListener`(`Object` listener)

Removes the given listener from this build.

#### `void` `removeProjectEvaluationListener`(`ProjectEvaluationListener` listener)

Removes the given listener from this build.

#### `void` `rootProject`(``Action`<? super `Project`>` action)

Adds an action to execute against the root project of this build. If the root project is already available, the action is executed immediately. Otherwise, the action is executed when the root project becomes available.

#### `void` `settingsEvaluated`(`Closure` closure)

Adds a closure to be called when the build settings have been loaded and evaluated. The settings object is fully configured and is ready to use to load the build projects. The `Settings` object is passed to the closure as a parameter.

#### `void` `settingsEvaluated`(``Action`<? super `Settings`>` action)

Adds an action to be called when the build settings have been loaded and evaluated. The settings object is fully configured and is ready to use to load the build projects.

#### `void` `useLogger`(`Object` logger)

Note: This method is deprecated and will be removed in the next major version of Gradle.

Uses the given object as a logger. The logger object may implement any of the listener interfaces supported by `Gradle.addListener(java.lang.Object)`.

Each listener interface has exactly one associated logger. When you call this method with a logger of a given listener type, the new logger will replace whichever logger is currently associated with the listener type. This allows you to selectively replace the standard logging which Gradle provides with your own implementation, for certain types of events.