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 build.gradle
file. During build initialisation, Gradle assembles a Project object for each project which is to
participate in the build, as follows:

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.

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 Project.property(java.lang.String) method. The scopes are:

The Project object itself. This scope includes any property getters and setters declared by the
Project implementation class. For example, Project.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 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 Project.property(java.lang.String) 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.

Dynamic Methods

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 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 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 Action parameter. The method calls the Task.configure(groovy.lang.Closure) 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.

The build script handler for this project. You can use this handler to query details about the build
script for this project, and manage the classpath used to compile and execute the project's build script.

The LoggingManager which can be used to receive logging and to control the
standard output/error capture for this project's build script. By default, System.out is redirected to the Gradle
logging system at the QUIET log level, and System.err is redirected at the ERROR log level.

Returns this project. This method is useful in build files to explicitly access project properties and
methods. For example, using project.name can express your intent better than using
name. This method also allows you to access project properties from a scope where the property may
be hidden, such as, for example, from a method or closure.

Methods

Adds a closure to be called immediately after this project has been evaluated. The project is passed to the
closure as a parameter. Such a listener gets notified when the build file belonging to this project has been
executed. A parent project may for example add such a listener to its child project. Such a listener can further
configure those child projects based on the state of the child projects after their build files have been
run.

Creates a container for managing named objects of the specified type. The given closure is used to create object instances. The name of the instance to be created is passed as a parameter to
the closure.

Creates a new ConfigurableFileTree using the given base directory. The given baseDir path is evaluated
as per Project.file(java.lang.Object). The closure will be used to configure the new file tree.
The file tree is passed to the closure as its delegate. Example:

Creates a new ConfigurableFileTree using the given base directory. The given baseDir path is evaluated
as per Project.file(java.lang.Object). The action will be used to configure the new file tree. Example:

Creates a new ConfigurableFileCollection using the given paths. The paths are evaluated as per Project.files(java.lang.Object[]). The file collection is configured using the given closure. The file collection is passed to
the closure as its delegate. Example:

Locates a project by path and configures it using the given closure. If the path is relative, it is
interpreted relative to this project. The target project is passed to the closure as the closure's delegate.

Returns the relative path from the project directory to the given path. The given path object is (logically)
resolved as described for Project.file(java.lang.Object), from which a relative path is calculated.

Creates a Task with the given name and adds it to this project. Before the task is returned, the given
closure is executed to configure the task. A map of creation options can be passed to this method to control how
the task is created. See Project.task(java.util.Map, java.lang.String) for the available options.

Resolves a file path to a URI, relative to the project directory of this project. Evaluates the provided path
object as described for Project.file(java.lang.Object), with the exception that any URI scheme is supported, not just
'file:' URIs.

Script blocks

Executes the given closure against the AntBuilder for this project. You can use this in your
build file to execute ant tasks. The AntBuild is passed to the closure as the closure's
delegate. See example in javadoc for Project.getAnt()

The build script handler for this project. You can use this handler to query details about the build
script for this project, and manage the classpath used to compile and execute the project's build script.

Examples:

You can access this property in your build file
using convention. You can also access the properties and methods of the convention object
as if they were properties and methods of this project. See here for more details

The LoggingManager which can be used to receive logging and to control the
standard output/error capture for this project's build script. By default, System.out is redirected to the Gradle
logging system at the QUIET log level, and System.err is redirected at the ERROR log level.

Returns this project. This method is useful in build files to explicitly access project properties and
methods. For example, using project.name can express your intent better than using
name. This method also allows you to access project properties from a scope where the property may
be hidden, such as, for example, from a method or closure.

Note that the application plugin pre configures this spec to; include the contents of "src/dist",
copy the application start scripts into the "bin" directory, and copy the built jar and its dependencies
into the "lib" directory.

Method details

Adds a closure to be called immediately after this project has been evaluated. The project is passed to the
closure as a parameter. Such a listener gets notified when the build file belonging to this project has been
executed. A parent project may for example add such a listener to its child project. Such a listener can further
configure those child projects based on the state of the child projects after their build files have been
run.

This method executes the given action against the ArtifactHandler for this project.

Example:

configurations {
//declaring new configuration that will be used to associate with artifacts
schema
}
task schemaJar(type: Jar) {
//some imaginary task that creates a jar artifact with the schema
}
//associating the task that produces the artifact with the configuration
artifacts {
//configuration name and the task:
schema schemaJar
}

Creates a container for managing named objects of the specified type. The given closure is used to create object instances. The name of the instance to be created is passed as a parameter to
the closure.

All objects MUST expose their name as a bean property named "name". The name must be constant for the life of the object.

The returned file tree is lazy, so that it scans for files only when the contents of the file tree are
queried. The file tree is also live, so that it scans for files each time the contents of the file tree are
queried.

Creates a new ConfigurableFileTree using the given base directory. The given baseDir path is evaluated
as per Project.file(java.lang.Object). The closure will be used to configure the new file tree.
The file tree is passed to the closure as its delegate. Example:

The returned file tree is lazy, so that it scans for files only when the contents of the file tree are
queried. The file tree is also live, so that it scans for files each time the contents of the file tree are
queried.

Creates a new ConfigurableFileTree using the given base directory. The given baseDir path is evaluated
as per Project.file(java.lang.Object). The action will be used to configure the new file tree. Example:

The returned file tree is lazy, so that it scans for files only when the contents of the file tree are
queried. The file tree is also live, so that it scans for files each time the contents of the file tree are
queried.

The returned file tree is lazy, so that it scans for files only when the contents of the file tree are
queried. The file tree is also live, so that it scans for files each time the contents of the file tree are
queried.

Creates a new ConfigurableFileCollection using the given paths. The paths are evaluated as per Project.files(java.lang.Object[]). The file collection is configured using the given closure. The file collection is passed to
the closure as its delegate. Example:

files "$buildDir/classes" {
builtBy 'compile'
}

The returned file collection is lazy, so that the paths are evaluated only when the contents of the file
collection are queried. The file collection is also live, so that it evaluates the above each time the contents
of the collection is queried.

Creates a new ConfigurableFileCollection using the given paths. The paths are evaluated as per Project.files(java.lang.Object[]). The file collection is configured using the given action. Example:

files "$buildDir/classes" {
builtBy 'compile'
}

The returned file collection is lazy, so that the paths are evaluated only when the contents of the file
collection are queried. The file collection is also live, so that it evaluates the above each time the contents
of the collection is queried.

A Collection, Iterable, or an array that contains objects of any supported type. The elements of the collection are recursively converted to files.

A FileCollection. The contents of the collection are included in the returned collection.

A Provider of any supported type. The provider's value is recursively converted to files. If the provider represents an output of a task, that task is executed if the file collection is used as an input to another task.

A Callable that returns any supported type. The return value of the call() method is recursively converted to files. A null return value is treated as an empty collection.

A Closure that returns any of the types listed here. The return value of the closure is recursively converted to files. A null return value is treated as an empty collection.

A Task. Converted to the task's output files. The task is executed if the file collection is used as an input to another task.

A TaskOutputs. Converted to the output files the related task. The task is executed if the file collection is used as an input to another task.

Anything else is treated as a failure.

The returned file collection is lazy, so that the paths are evaluated only when the contents of the file
collection are queried. The file collection is also live, so that it evaluates the above each time the contents
of the collection is queried.

The returned file collection maintains the iteration order of the supplied paths.

The returned file collection maintains the details of the tasks that produce the files, so that these tasks are executed if this file collection is used as an input to some task.

This method can also be used to create an empty collection, which can later be mutated to add elements.

Locates a project by path and configures it using the given closure. If the path is relative, it is
interpreted relative to this project. The target project is passed to the closure as the closure's delegate.

Returns the relative path from the project directory to the given path. The given path object is (logically)
resolved as described for Project.file(java.lang.Object), from which a relative path is calculated.

Synchronizes the contents of a destination directory with some source directories and files.
The given action is used to configure a CopySpec, which is then used to synchronize the files.

This method is like the Project.copy(org.gradle.api.Action) task, except the destination directory will only contain the files copied.
All files that exist in the destination directory will be deleted before copying files, unless a preserve option is specified.

The returned file tree is lazy, so that it scans for files only when the contents of the file tree are
queried. The file tree is also live, so that it scans for files each time the contents of the file tree are
queried.

Unless custom implementation of resources is passed, the tar tree attempts to guess the compression based on the file extension.

task untar(type: Copy) {
from tarTree('someCompressedTar.gzip')
//tar tree attempts to guess the compression based on the file extension//however if you must specify the compression explicitly you can:
from tarTree(resources.gzip('someTar.ext'))
//in case you work with unconventionally compressed tars//you can provide your own implementation of a ReadableResource://from tarTree(yourOwnResource as ReadableResource)
into 'dest'
}

Creates a Task with the given name and adds it to this project. Before the task is returned, the given
closure is executed to configure the task. A map of creation options can be passed to this method to control how
the task is created. See Project.task(java.util.Map, java.lang.String) for the available options.

After the task is added to the project, it is made available as a property of the project, so that you can
reference the task by name in your build file. See here for more details

If a task with the given name already exists in this project and the override option is not set
to true, an exception is thrown.

Resolves a file path to a URI, relative to the project directory of this project. Evaluates the provided path
object as described for Project.file(java.lang.Object), with the exception that any URI scheme is supported, not just
'file:' URIs.

The returned file tree is lazy, so that it scans for files only when the contents of the file tree are
queried. The file tree is also live, so that it scans for files each time the contents of the file tree are
queried.

ant { }

Executes the given closure against the AntBuilder for this project. You can use this in your
build file to execute ant tasks. The AntBuild is passed to the closure as the closure's
delegate. See example in javadoc for Project.getAnt()

artifacts { }

This method executes the given closure against the ArtifactHandler for this project. The ArtifactHandler is passed to the closure as the closure's delegate.

Example:

configurations {
//declaring new configuration that will be used to associate with artifacts
schema
}
task schemaJar(type: Jar) {
//some imaginary task that creates a jar artifact with the schema
}
//associating the task that produces the artifact with the configuration
artifacts {
//configuration name and the task:
schema schemaJar
}