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.

Lifecycle

There is a one-to-one relationship between a Project and a {@value #DEFAULT_BUILD_FILE} file. During build initialisation, Gradle assembles a Project object for each project which is to participate in the build, as follows:

• Create a org.gradle.api.initialization.Settings instance for the build.
• Evaluate the {@value org.gradle.api.initialization.Settings#DEFAULT_SETTINGS_FILE} script, if present, against the org.gradle.api.initialization.Settings object to configure it.
• Use the configured org.gradle.api.initialization.Settings object to create the hierarchy of Project instances.
• Finally, evaluate each Project by executing its {@value #DEFAULT_BUILD_FILE} file, if present, against the project. The projects are evaluated in breadth-wise order, such that a project is evaluated before its child projects. This order can be overridden by calling evaluationDependsOnChildren or by adding an explicit evaluation dependency using evaluationDependsOn.

Tasks

A project is essentially a collection of Task objects. Each task performs some basic piece of work, such as compiling classes, or running unit tests, or zipping up a WAR file. You add tasks to a project using one of the create() methods on TaskContainer, such as create. You can locate existing tasks using one of the lookup methods on TaskContainer, such as getByName.

Dependencies

A project generally has a number of dependencies it needs in order to do its work. Also, a project generally produces a number of artifacts, which other projects can use. Those dependencies are grouped in configurations, and can be retrieved and uploaded from repositories. You use the org.gradle.api.artifacts.ConfigurationContainer returned by getConfigurations method to manage the configurations. The returned by getDependencies method to manage the dependencies. The org.gradle.api.artifacts.dsl.ArtifactHandler returned by getArtifacts method to manage the artifacts. The org.gradle.api.artifacts.dsl.RepositoryHandler returned by getRepositories method to manage the repositories.

Multi-project Builds

Projects are arranged into a hierarchy of projects. A project has a name, and a fully qualified path which uniquely identifies it in the hierarchy.

Plugins

Plugins can be used to modularise and reuse project configuration. Plugins can be applied using the apply method, or by using the org.gradle.plugin.use.PluginDependenciesSpec plugins script block.

Dynamic Project Properties

Gradle executes the project's build file against the Project instance to configure the project. Any property or method which your script uses is delegated through to the associated Project object. This means, that you can use any of the methods and properties on the Project interface directly in your script.

For example:

defaultTasks('some-task')  // Delegates to Project.defaultTasks()
reportsDir = file('reports') // Delegates to Project.file() and the Java Plugin

You can also access the Project instance using the project property. This can make the script clearer in some cases. For example, you could use project.name rather than name to access the project's name.

A project has 5 property 'scopes', which it searches for properties. You can access these properties by name in your build file, or by calling the project's property method. The scopes are:

• The Project object itself. This scope includes any property getters and setters declared by the Project implementation class. For example, getRootProject is accessible as the rootProject property. The properties of this scope are readable or writable depending on the presence of the corresponding getter or setter method.
• The extra properties of the project. Each project maintains a map of extra properties, which can contain any arbitrary name -> value pair. Once defined, the properties of this scope are readable and writable. See extra properties for more details.
• The extensions added to the project by the plugins. Each extension is available as a read-only property with the same name as the extension.
• The convention properties added to the project by the plugins. A plugin can add properties and methods to a project through the project's org.gradle.api.plugins.Convention object. The properties of this scope may be readable or writable, depending on the convention objects.
• The tasks of the project. A task is accessible by using its name as a property name. The properties of this scope are read-only. For example, a task called compile is accessible as the compile property.
• The extra properties and convention properties are inherited from the project's parent, recursively up to the root project. The properties of this scope are read-only.

When reading a property, the project searches the above scopes in order, and returns the value from the first scope it finds the property in. If not found, an exception is thrown. See property for more details.

When writing a property, the project searches the above scopes in order, and sets the property in the first scope it finds the property in. If not found, an exception is thrown. See setProperty for more details.

Extra Properties

All extra properties must be defined through the "ext" namespace. Once an extra property has been defined, it is available directly on the owning object (in the below case the Project, Task, and sub-projects respectively) and can be read and updated. Only the initial declaration that needs to be done via the namespace.

project.ext.prop1 = "foo"
task doStuff {
    ext.prop2 = "bar"
}
subprojects { ext.${prop3} = false }

ext.isSnapshot = version.endsWith("-SNAPSHOT")
if (isSnapshot) {
    // do snapshot stuff
}

Dynamic Methods

A project has 5 method 'scopes', which it searches for methods:

• The Project object itself.
• The build file. The project searches for a matching method declared in the build file.
• The extensions added to the project by the plugins. Each extension is available as a method which takes a closure or org.gradle.api.Action as a parameter.
• The convention methods added to the project by the plugins. A plugin can add properties and method to a project through the project's org.gradle.api.plugins.Convention object.
• The tasks of the project. A method is added for each task, using the name of the task as the method name and taking a single closure or org.gradle.api.Action parameter. The method calls the configure method for the associated task with the provided closure. For example, if the project has a task called compile, then a method is added with the following signature: void compile(Closure configureClosure).
• The methods of the parent project, recursively up to the root project.
• A property of the project whose value is a closure. The closure is treated as a method and called with the provided parameters. The property is located as described above.