org.gradle.api.invocation.Gradle Maven / Gradle / Ivy
Show all versions of gradle-api Show documentation
/*
* Copyright 2009 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.
*/
package org.gradle.api.invocation;
import groovy.lang.Closure;
import groovy.lang.DelegatesTo;
import org.gradle.BuildListener;
import org.gradle.BuildResult;
import org.gradle.StartParameter;
import org.gradle.api.Action;
import org.gradle.api.Incubating;
import org.gradle.api.Project;
import org.gradle.api.ProjectEvaluationListener;
import org.gradle.api.UnknownDomainObjectException;
import org.gradle.api.execution.TaskExecutionGraph;
import org.gradle.api.flow.FlowProviders;
import org.gradle.api.initialization.IncludedBuild;
import org.gradle.api.initialization.Settings;
import org.gradle.api.plugins.ExtensionAware;
import org.gradle.api.plugins.PluginAware;
import org.gradle.api.services.BuildServiceRegistry;
import org.gradle.internal.HasInternalProtocol;
import javax.annotation.Nullable;
import java.io.File;
import java.util.Collection;
/**
* Represents an invocation of Gradle.
*
* You can obtain a {@code Gradle} instance by calling {@link Project#getGradle()}.
*/
@HasInternalProtocol
public interface Gradle extends PluginAware, ExtensionAware {
/**
* Returns the current Gradle version.
*
* @return The Gradle version. Never returns null.
*/
String getGradleVersion();
/**
* Returns the Gradle user home directory.
*
* This directory is used to cache downloaded resources, compiled build scripts and so on.
*
* @return The user home directory. Never returns null.
*/
File getGradleUserHomeDir();
/**
* 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.
*
* @return The home directory. May return null.
*/
@Nullable
File getGradleHomeDir();
/**
* Returns the parent build of this build, if any.
*
* @return The parent build. May return null.
*/
@Nullable
Gradle getParent();
/**
* Returns the root project of this build.
*
* @return The root project. Never returns null.
* @throws IllegalStateException When called before the root project is available.
*/
Project getRootProject() throws IllegalStateException;
/**
* 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.
*
* @param action The action to execute.
*/
void rootProject(Action 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.
*
* @param action The action to execute.
*/
void allprojects(Action action);
/**
* Returns the {@link TaskExecutionGraph} for this build.
*
* @return The task graph. Never returns null.
*/
TaskExecutionGraph getTaskGraph();
/**
* Returns the {@link StartParameter} used to start this build.
*
* @return The start parameter. Never returns null.
*/
StartParameter getStartParameter();
/**
* Adds a listener to this build, to receive notifications as projects are evaluated.
*
* @param listener The listener to add. Does nothing if this listener has already been added.
* @return The added listener.
*/
ProjectEvaluationListener addProjectEvaluationListener(ProjectEvaluationListener listener);
/**
* Removes the given listener from this build.
*
* @param listener The listener to remove. Does nothing if this listener has not been added.
*/
void removeProjectEvaluationListener(ProjectEvaluationListener listener);
/**
* Gives access to the new Gradle build lifecycle callbacks.
*
* @since 8.8
*/
@Incubating
GradleLifecycle getLifecycle();
/**
* Adds a closure to be called immediately before a project is evaluated. The project is passed to the closure as a
* parameter.
*
* @param closure The closure to execute.
*/
void beforeProject(Closure closure);
/**
* Adds an action to be called immediately before a project is evaluated.
*
* @param action The action to execute.
* @since 3.4
*/
void beforeProject(Action action);
/**
* 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.
*
* @param closure The closure to execute.
*/
void afterProject(Closure closure);
/**
* Adds an action to be called immediately after a project is evaluated.
*
* @param action The action to execute.
* @since 3.4
*/
void afterProject(Action action);
/**
* Adds an action to be called before the build settings have been loaded and evaluated.
*
* @param closure The action to execute.
* @since 6.0
*/
void beforeSettings(@DelegatesTo(Settings.class) Closure closure);
/**
* Adds an action to be called before the build settings have been loaded and evaluated.
*
* @param action The action to execute.
* @since 6.0
*/
void beforeSettings(Action action);
/**
* 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
* {@link org.gradle.api.initialization.Settings} object is passed to the closure as a parameter.
*
* @param closure The closure to execute.
*/
void settingsEvaluated(Closure closure);
/**
* 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.
*
* @param action The action to execute.
* @since 3.4
*/
void settingsEvaluated(Action action);
/**
* 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 {@code 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 {
* //...
* }
* }
* }
*
*
* @param closure The closure to execute.
*/
void projectsLoaded(Closure closure);
/**
* 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.
*
* @param action The action to execute.
* @since 3.4
*/
void projectsLoaded(Action action);
/**
* 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 {@code Gradle} instance is passed to the closure as a parameter.
*
* @param closure The closure to execute.
*/
void projectsEvaluated(Closure closure);
/**
* 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.
*
* @param action The action to execute.
* @since 3.4
*/
void projectsEvaluated(Action action);
/**
* Adds a closure to be called when the build is completed.
*
* All selected tasks have been executed.
* A {@link BuildResult} instance is passed to the closure as a parameter.
*
* @param closure The closure to execute.
* @see FlowProviders#getBuildWorkResult()
* @deprecated This method is not supported when configuration caching is enabled.
*/
@Deprecated
void buildFinished(Closure closure);
/**
* Adds an action to be called when the build is completed.
*
* All selected tasks have been executed.
*
* @param action The action to execute.
* @see FlowProviders#getBuildWorkResult()
* @since 3.4
* @deprecated This method is not supported when configuration caching is enabled.
*/
@Deprecated
void buildFinished(Action action);
/**
* Adds a {@link BuildListener} to this Build instance.
*
* The listener is notified of events which occur during the execution of the build.
*
* @param buildListener The listener to add.
*/
void addBuildListener(BuildListener buildListener);
/**
* Adds the given listener to this build. The listener may implement any of the given listener interfaces:
*
*
* - {@link org.gradle.api.execution.TaskExecutionGraphListener}
*
- {@link org.gradle.api.ProjectEvaluationListener}
*
- {@link org.gradle.api.artifacts.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:
*
*
* - {@link org.gradle.BuildListener}
*
- {@link org.gradle.api.execution.TaskExecutionListener}
*
- {@link org.gradle.api.execution.TaskActionListener}
*
- {@link org.gradle.api.tasks.testing.TestListener}
*
- {@link org.gradle.api.tasks.testing.TestOutputListener}
*
*
* @param listener The listener to add. Does nothing if this listener has already been added.
*/
void addListener(Object listener);
/**
* Removes the given listener from this build.
*
* @param listener The listener to remove. Does nothing if this listener has not been added.
*/
void removeListener(Object listener);
/**
* Uses the given object as a logger.
*
* The logger object may implement any of the listener interfaces supported by
* {@link #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.
*
* @param logger The logger to use.
* @deprecated Will be removed in Gradle 9. Logging customization through listeners is no longer supported.
*/
@Deprecated
void useLogger(Object logger);
/**
* Returns this {@code 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.
*
* @return this. Never returns null.
*/
Gradle getGradle();
/**
* Returns the build services that are shared by all projects of this build.
*
* @since 6.1
*/
BuildServiceRegistry getSharedServices();
/**
* Returns the included builds for this build.
*
* @since 3.1
*/
Collection getIncludedBuilds();
/**
* 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
*/
IncludedBuild includedBuild(String name) throws UnknownDomainObjectException;
}