# Interface Gradle

All Superinterfaces:
  `ExtensionAware, PluginAware`

@ServiceScope({org.gradle.internal.service.scopes.Scope.Build.class,org.gradle.internal.service.scopes.Scope.Project.class}) public interface Gradle extends PluginAware, ExtensionAware
Represents an invocation of Gradle.

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

Since:
  0.8

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addBuildListener(BuildListener buildListener)`
  Adds a `BuildListener` to this Build instance.
  `void`
  `addListener(Object listener)`
  Adds the given listener to this build.
  `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.
  `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.
  `void`
  `beforeProject(Closure closure)`
  Adds a closure to be called immediately before a project is evaluated.
  `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)`
  Deprecated.
  This method is not supported when configuration caching is enabled.
  `void`
  `buildFinished(Action<? super BuildResult> action)`
  Deprecated.
  This method is not supported when configuration caching is enabled.
  `String`
  `getBuildPath()`
  Get the path of this build relative to the root build.
  `Gradle`
  `getGradle()`
  Returns this `Gradle` instance.
  `@Nullable File`
  `getGradleHomeDir()`
  Returns the Gradle home directory, if any.
  `File`
  `getGradleUserHomeDir()`
  Returns the Gradle user home directory.
  `String`
  `getGradleVersion()`
  Returns the current Gradle version.
  `Collection<IncludedBuild>`
  `getIncludedBuilds()`
  Returns the included builds for this build.
  `GradleLifecycle`
  `getLifecycle()`
  Gives access to the new Gradle build lifecycle callbacks.
  `@Nullable Gradle`
  `getParent()`
  Returns the parent build of this build, if any.
  `ProviderFactory`
  `getProviders()`
  Provides access to methods to create various kinds of `Provider` instances.
  `Project`
  `getRootProject()`
  Returns the root project of this build.
  `BuildServiceRegistry`
  `getSharedServices()`
  Returns the build services that are shared by all projects of this build.
  `StartParameter`
  `getStartParameter()`
  Returns the `StartParameter` used to start this build.
  `TaskExecutionGraph`
  `getTaskGraph()`
  Returns the `TaskExecutionGraph` for this build.
  `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.
  `void`
  `projectsEvaluated(Action<? super Gradle> action)`
  Adds an action to be called when all projects for the build have been evaluated.
  `void`
  `projectsLoaded(Closure closure)`
  Adds a closure to be called when the projects for the build have been created from the settings.
  `void`
  `projectsLoaded(Action<? super Gradle> action)`
  Adds an action to be called when the projects for the build have been created from the settings.
  `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.
  `<T extends GradleService>
  T`
  `service(Class<T> serviceType)`
  Looks up a service provided by Gradle for use in init scripts and `Gradle` plugins.
  `void`
  `settingsEvaluated(Closure closure)`
  Adds a closure to be called when the build settings have been loaded and evaluated.
  `void`
  `settingsEvaluated(Action<? super Settings> action)`
  Adds an action to be called when the build settings have been loaded and evaluated.
  `void`
  `useLogger(Object logger)`
  Deprecated.
  Will be removed in Gradle 10.

  ### Methods inherited from interface ExtensionAware

  `getExtensions`

  ### Methods inherited from interface PluginAware

  `apply, apply, apply, getPluginManager, getPlugins`

- ## Method Details

  - ### getBuildPath

    String getBuildPath()
    Get the path of this build relative to the root build.
    Since:
      9.1.0

  - ### getGradleVersion

    String getGradleVersion()
    Returns the current Gradle version.
    Returns:
      The Gradle version. Never returns null.
    Since:
      0.8

  - ### getGradleUserHomeDir

    File getGradleUserHomeDir()
    Returns the Gradle user home directory. This directory is used to cache downloaded resources, compiled build scripts and so on.
    Returns:
      The user home directory. Never returns null.
    Since:
      0.8

  - ### getGradleHomeDir

    @Nullable File getGradleHomeDir()
    Returns 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.

    Returns:
      The home directory. May return null.
    Since:
      0.8

  - ### getParent

    @Nullable Gradle getParent()
    Returns the parent build of this build, if any.
    Returns:
      The parent build. May return null.
    Since:
      0.9

  - ### getRootProject

    Project getRootProject() throws IllegalStateException
    Returns the root project of this build.
    Returns:
      The root project. Never returns null.
    Throws:
      `IllegalStateException` - When called before the root project is available.
    Since:
      0.8

  - ### rootProject

    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.
    Parameters:
      `action` - The action to execute.
    Since:
      1.0

  - ### allprojects

    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.
    Parameters:
      `action` - The action to execute.
    Since:
      1.0

  - ### getTaskGraph

    TaskExecutionGraph getTaskGraph()
    Returns the `TaskExecutionGraph` for this build.
    Returns:
      The task graph. Never returns null.
    Since:
      0.8

  - ### getStartParameter

    StartParameter getStartParameter()
    Returns the `StartParameter` used to start this build.
    Returns:
      The start parameter. Never returns null.
    Since:
      0.8

  - ### addProjectEvaluationListener

    ProjectEvaluationListener addProjectEvaluationListener(ProjectEvaluationListener listener)
    Adds a listener to this build, to receive notifications as projects are evaluated.
    Parameters:
      `listener` - The listener to add. Does nothing if this listener has already been added.
    Returns:
      The added listener.
    Since:
      0.8

  - ### removeProjectEvaluationListener

    void removeProjectEvaluationListener(ProjectEvaluationListener listener)
    Removes the given listener from this build.
    Parameters:
      `listener` - The listener to remove. Does nothing if this listener has not been added.
    Since:
      0.8

  - ### getLifecycle

    @Incubating GradleLifecycle getLifecycle()
    Gives access to the new Gradle build lifecycle callbacks.
    Since:
      8.8

  - ### beforeProject

    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.
    Parameters:
      `closure` - The closure to execute.
    Since:
      0.8

  - ### beforeProject

    void beforeProject(Action<? super Project> action)
    Adds an action to be called immediately before a project is evaluated.
    Parameters:
      `action` - The action to execute.
    Since:
      3.4

  - ### afterProject

    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.
    Parameters:
      `closure` - The closure to execute.
    Since:
      0.8

  - ### afterProject

    void afterProject(Action<? super Project> action)
    Adds an action to be called immediately after a project is evaluated.
    Parameters:
      `action` - The action to execute.
    Since:
      3.4

  - ### beforeSettings

    void beforeSettings(@DelegatesTo(Settings.class) Closure<?> closure)
    Adds an action to be called before the build settings have been loaded and evaluated.
    Parameters:
      `closure` - The action to execute.
    Since:
      6.0

  - ### beforeSettings

    void beforeSettings(Action<? super Settings> action)
    Adds an action to be called before the build settings have been loaded and evaluated.
    Parameters:
      `action` - The action to execute.
    Since:
      6.0

  - ### settingsEvaluated

    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.
    Parameters:
      `closure` - The closure to execute.
    Since:
      0.9

  - ### settingsEvaluated

    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.
    Parameters:
      `action` - The action to execute.
    Since:
      3.4

  - ### projectsLoaded

    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 {
              //...
            }
          }
        }

    Parameters:
      `closure` - The closure to execute.
    Since:
      0.9

  - ### projectsLoaded

    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.
    Parameters:
      `action` - The action to execute.
    Since:
      3.4

  - ### projectsEvaluated

    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.
    Parameters:
      `closure` - The closure to execute.
    Since:
      0.9

  - ### projectsEvaluated

    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.
    Parameters:
      `action` - The action to execute.
    Since:
      3.4

  - ### buildFinished

    @Deprecated void buildFinished(Closure closure)
    Deprecated.
    This method is not supported when configuration caching is enabled.
    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.
    Parameters:
      `closure` - The closure to execute.
    Since:
      0.9
    See Also:
      - `FlowProviders.getBuildWorkResult()`

  - ### buildFinished

    @Deprecated void buildFinished(Action<? super BuildResult> action)
    Deprecated.
    This method is not supported when configuration caching is enabled.
    Adds an action to be called when the build is completed. All selected tasks have been executed.
    Parameters:
      `action` - The action to execute.
    Since:
      3.4
    See Also:
      - `FlowProviders.getBuildWorkResult()`

  - ### addBuildListener

    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.

    Parameters:
      `buildListener` - The listener to add.
    Since:
      0.8

  - ### addListener

    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`
    Parameters:
      `listener` - The listener to add. Does nothing if this listener has already been added.
    Since:
      0.8

  - ### removeListener

    void removeListener(Object listener)
    Removes the given listener from this build.
    Parameters:
      `listener` - The listener to remove. Does nothing if this listener has not been added.
    Since:
      0.8

  - ### useLogger

    @Deprecated void useLogger(Object logger)
    Deprecated.
    Will be removed in Gradle 10. Logging customization through listeners is no longer supported.
    Uses the given object as a logger. The logger object may implement any of the listener interfaces supported by `addListener(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.

    Parameters:
      `logger` - The logger to use.
    Since:
      0.9

  - ### getGradle

    Gradle getGradle()
    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.
    Returns:
      this. Never returns null.
    Since:
      0.8

  - ### getSharedServices

    BuildServiceRegistry getSharedServices()
    Returns the build services that are shared by all projects of this build.
    Since:
      6.1

  - ### getIncludedBuilds

    Collection<IncludedBuild> getIncludedBuilds()
    Returns the included builds for this build.
    Since:
      3.1

  - ### includedBuild

    IncludedBuild includedBuild(String name) throws UnknownDomainObjectException
    Returns the included build with the specified name for this build.
    Throws:
      `UnknownDomainObjectException` - when there is no build with the given name
    Since:
      3.1

  - ### getProviders

    @Incubating ProviderFactory getProviders()
    Provides access to methods to create various kinds of `Provider` instances.
    Returns:
      the provider factory. Never returns null.
    Since:
      9.4.0

  - ### service

    @Incubating <T extends GradleService> T service(Class<T> serviceType)
    Looks up a service provided by Gradle for use in init scripts and `Gradle` plugins.

    The services available for lookup are the Gradle types that implement `GradleService`.

    This method does not provide access to `shared build services`; use `getSharedServices()` to access those.

    Type Parameters:
      `T` - the service type
    Parameters:
      `serviceType` - the type of the service to look up
    Returns:
      the service instance. Never returns null.
    Throws:
      `InvalidUserDataException` - when the given type is not one of the services available in this scope
    Since:
      9.8.0