Project (Gradle API 1.8)

Overview

Package

Class

Deprecated

Index

Help

Groovy Documentation

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | METHOD

DETAIL: FIELD | METHOD

org.gradle.api
[Java] Interface Project

org.gradle.api.plugins.ExtensionAware
  org.gradle.api.plugins.PluginAware
      org.gradle.api.Project

All Superinterfaces:: ExtensionAware, PluginAware

@HasInternalProtocol
public interface Project
extends Comparable, ExtensionAware, PluginAware

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 Settings instance for the build.
Evaluate the {@value org.gradle.api.initialization.Settings#DEFAULT_SETTINGS_FILE} script, if present, against the Settings object to configure it.
Use the configured 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 project 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(String).

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 add() methods on TaskContainer, such as TaskContainer#add(String)#add(String). You can locate existing tasks using one of the lookup methods on TaskContainer, such as TaskCollection.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 ConfigurationContainer returned by getConfigurations() method to manage the configurations. The DependencyHandler returned by getDependencies() method to manage the dependencies. The ArtifactHandler returned by getArtifacts() method to manage the artifacts. The 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.

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(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, 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 additional properties of the project. Each project maintains a map of additional properties, which can contain any arbitrary name -> value pair. The properties of this scope are readable and writable.
The convention properties added to the project by each Plugin applied to the project. 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 additional properties and convention properties of the project's parent project, 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. See property(String) 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, the project adds the property to its map of additional properties. For the next few releases a deprecation warning will be issued when trying to set a property that does not exist. Dynamic properties will eventually be removed entirely, meaning that this will be a fatal error in future versions of Gradle. See Extra Properties to learn how to add properties dynamically.

Extra Properties

All extra properties must be created through the "ext" namespace. Once extra properties have been created, they are available on the owning object (in the below case the Project, Task, and sub-projects respectively) and can be read and changed. It's 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 }

Reading extra properties is done through the "ext" or through the owning object.

 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 convention methods added to the project by each Plugin applied to the project. 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 parameter. The method calls the Task.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 parent project, recursively up to the root project.

Field Summary
`static String`	`DEFAULT_BUILD_DIR_NAME` The default build directory name.
`static String`	`DEFAULT_BUILD_FILE` The default project build file name.
`static String`	`DEFAULT_STATUS`
`static String`	`DEFAULT_VERSION`
`static String`	`GRADLE_PROPERTIES`
`static String`	`PATH_SEPARATOR` The hierarchy separator for project and task path names.
`static String`	`SYSTEM_PROP_PREFIX`

Method Summary
`String`	`absoluteProjectPath(String path)`
`void`	`afterEvaluate(Action action)` Adds an action to execute immediately after this project is evaluated.
`void`	`afterEvaluate(Closure closure)`
`void`	`allprojects(Action action)`
`void`	`allprojects(Closure configureClosure)`
`AntBuilder`	`ant(Closure configureClosure)`
`void`	`apply(Closure closure)`
`void`	`apply(Map options)`
`void`	`artifacts(Closure configureClosure)`
`void`	`beforeEvaluate(Action action)` Adds an action to execute immediately before this project is evaluated.
`void`	`beforeEvaluate(Closure closure)`
`void`	`buildscript(Closure configureClosure)`
`Project`	`childrenDependOnMe()`
`void`	`configurations(Closure configureClosure)`
`Object`	`configure(Object object, Closure configureClosure)`
`Iterable`	`configure(Iterable objects, Closure configureClosure)` Configures a collection of objects via a closure.
`Iterable`	`configure(Iterable objects, Action configureAction)` Configures a collection of objects via an action.
`NamedDomainObjectContainer`	`container(Class type)`
`NamedDomainObjectContainer`	`container(Class type, NamedDomainObjectFactory factory)`
`NamedDomainObjectContainer`	`container(Class type, Closure factoryClosure)`
`WorkResult`	`copy(Closure closure)` Copies the specified files.
`CopySpec`	`copySpec(Closure closure)` Creates a CopySpec which can later be used to copy files or create an archive.
`AntBuilder`	`createAntBuilder()`
`void`	`defaultTasks(String... defaultTasks)`
`boolean`	`delete(Object... paths)` Deletes files and directories.
`void`	`dependencies(Closure configureClosure)`
`void`	`dependsOn(String path)`
`void`	`dependsOn(String path, boolean evaluateDependsOnProject)`
`Project`	`dependsOnChildren()`
`Project`	`dependsOnChildren(boolean evaluateDependsOnProject)`
`int`	`depthCompare(Project otherProject)`
`Project`	`evaluationDependsOn(String path)`
`void`	`evaluationDependsOnChildren()`
`ExecResult`	`exec(Closure closure)` Executes an external command.
`File`	`file(Object path)`
`File`	`file(Object path, PathValidation validation)`
`ConfigurableFileTree`	`fileTree(Object baseDir)`
`ConfigurableFileTree`	`fileTree(Object baseDir, Closure configureClosure)`
`ConfigurableFileTree`	`fileTree(Map args)`
`ConfigurableFileTree`	`fileTree(Closure closure)`
`ConfigurableFileCollection`	`files(Object... paths)`
`ConfigurableFileCollection`	`files(Object paths, Closure configureClosure)`
`Project`	`findProject(String path)`
`Map`	`getAllTasks(boolean recursive)`
`Set`	`getAllprojects()`
`AntBuilder`	`getAnt()`
`ArtifactHandler`	`getArtifacts()` Returns a handler for assigning artifacts produced by the project to configurations.
`File`	`getBuildDir()`
`File`	`getBuildFile()`
`ScriptHandler`	`getBuildscript()` Returns the build script handler for this project.
`Map`	`getChildProjects()`
`SoftwareComponentContainer`	`getComponents()` Returns the software components produced by this project.
`ConfigurationContainer`	`getConfigurations()` Returns the configurations of this project.
`Convention`	`getConvention()`
`List`	`getDefaultTasks()`
`DependencyHandler`	`getDependencies()` Returns the dependency handler of this project.
`Set`	`getDependsOnProjects()`
`int`	`getDepth()`
`String`	`getDescription()` Returns the description of this project.
`ExtensionContainer`	`getExtensions()` Allows adding DSL extensions to the project.
`Gradle`	`getGradle()`
`Object`	`getGroup()`
`Logger`	`getLogger()`
`LoggingManager`	`getLogging()` Returns the LoggingManager which can be used to control the logging level and standard output/error capture for this project's build script.
`String`	`getName()`
`Project`	`getParent()`
`String`	`getPath()`
`PluginContainer`	`getPlugins()` Returns the plugins container for this project.
`Project`	`getProject()`
`File`	`getProjectDir()`
`Map`	`getProperties()`
`RepositoryHandler`	`getRepositories()` Returns a handler to create repositories which are used for retrieving dependencies and uploading artifacts produced by the project.
`ResourceHandler`	`getResources()` Provides access to resource-specific utility methods, for example factory methods that create various resources.
`File`	`getRootDir()`
`Project`	`getRootProject()`
`ProjectState`	`getState()` Returns the evaluation state of this project.
`Object`	`getStatus()`
`Set`	`getSubprojects()`
`TaskContainer`	`getTasks()`
`Set`	`getTasksByName(String name, boolean recursive)`
`Object`	`getVersion()`
`boolean`	`hasProperty(String propertyName)`
`ExecResult`	`javaexec(Closure closure)` Executes a Java main class.
`File`	`mkdir(Object path)` Creates a directory and returns a file pointing to it.
`Project`	`project(String path)`
`Project`	`project(String path, Closure configureClosure)`
`Object`	`property(String propertyName)`
`String`	`relativePath(Object path)`
`String`	`relativeProjectPath(String path)`
`void`	`repositories(Closure configureClosure)`
`void`	`setBuildDir(Object path)`
`void`	`setDefaultTasks(List defaultTasks)`
`void`	`setDescription(String description)` Sets a description for this project.
`void`	`setGroup(Object group)`
`void`	`setProperty(String name, Object value)`
`void`	`setStatus(Object status)` Sets the status of this project.
`void`	`setVersion(Object version)`
`void`	`subprojects(Action action)`
`void`	`subprojects(Closure configureClosure)`
`FileTree`	`tarTree(Object tarPath)` Creates a new `FileTree` which contains the contents of the given TAR file.
`Task`	`task(String name)`
`Task`	`task(Map args, String name)`
`Task`	`task(Map args, String name, Closure configureClosure)`
`Task`	`task(String name, Closure configureClosure)`
`URI`	`uri(Object path)`
`FileTree`	`zipTree(Object zipPath)`

Methods inherited from interface ExtensionAware
getExtensions

Methods inherited from interface PluginAware
apply, apply, getPlugins

Methods inherited from interface Comparable
compareTo

Methods inherited from class Object
wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll

Field Detail

DEFAULT_BUILD_DIR_NAME

public static final String DEFAULT_BUILD_DIR_NAME

The default build directory name.

DEFAULT_BUILD_FILE

public static final String DEFAULT_BUILD_FILE

The default project build file name.

DEFAULT_STATUS

public static final String DEFAULT_STATUS

DEFAULT_VERSION

public static final String DEFAULT_VERSION

GRADLE_PROPERTIES

public static final String GRADLE_PROPERTIES

PATH_SEPARATOR

public static final String PATH_SEPARATOR

The hierarchy separator for project and task path names.

SYSTEM_PROP_PREFIX

public static final String SYSTEM_PROP_PREFIX

Method Detail

absoluteProjectPath

public String absoluteProjectPath(String path)

Converts a name to an absolute project path, resolving names relative to this project.

Parameters:: path - The path to convert.

Returns:: The absolute path.

afterEvaluate

public void afterEvaluate(Action action)

Adds an action to execute immediately after this project is evaluated.

Parameters:: action - the action to execute.

afterEvaluate

public void afterEvaluate(Closure closure)

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.

Parameters:: closure - The closure to call.

allprojects

public void allprojects(Action action)

Configures this project and each of its sub-projects.

This method executes the given Action against this project and each of its sub-projects.

Parameters:: action - The action to execute.

allprojects

public void allprojects(Closure configureClosure)

Configures this project and each of its sub-projects.

This method executes the given closure against this project and its sub-projects. The target Project is passed to the closure as the closure's delegate.

Parameters:: configureClosure - The closure to execute.

ant

public AntBuilder ant(Closure configureClosure)

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 getAnt()

Parameters:: configureClosure - The closure to execute against the AntBuilder.

Returns:: The AntBuilder. Never returns null.

apply

public void apply(Closure closure)

Configures this project using plugins or scripts. The given closure is used to configure an ObjectConfigurationAction which is then used to configure this project.

Parameters:: closure - The closure to configure the ObjectConfigurationAction.

apply

public void apply(Map options)

Configures this project using plugins or scripts. The following options are available:

from: A script to apply to the project. Accepts any path supported by uri(Object).
plugin: The id or implementation class of the plugin to apply to the project.
to: The target delegate object or objects. Use this to configure objects other than the project.

For more detail, see ObjectConfigurationAction.

Parameters:: options - The options to use to configure the ObjectConfigurationAction.

artifacts

public void artifacts(Closure configureClosure)

Configures the published artifacts for this project.

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
 }

Parameters:: configureClosure - the closure to use to configure the published artifacts.

beforeEvaluate

public void beforeEvaluate(Action action)

Adds an action to execute immediately before this project is evaluated.

Parameters:: action - the action to execute.

beforeEvaluate

public void beforeEvaluate(Closure closure)

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

Parameters:: closure - The closure to call.

buildscript

public void buildscript(Closure configureClosure)

Configures the build script classpath for this project.

The given closure is executed against this project's ScriptHandler. The ScriptHandler is passed to the closure as the closure's delegate.

Parameters:: configureClosure - the closure to use to configure the build script classpath.

childrenDependOnMe

@Deprecated
public Project childrenDependOnMe()

Declares that all child projects of this project have an execution dependency on this project.

deprecated:: Use Task.dependsOn instead.

Returns:: this project.

configurations

public void configurations(Closure configureClosure)

Configures the dependency configurations for this project.

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

Examples:

See docs for ConfigurationContainer

Parameters:: configureClosure - the closure to use to configure the dependency configurations.

configure

public Object configure(Object object, Closure configureClosure)

Configures an object via a closure, with the closure's delegate set to the supplied object. This way you don't have to specify the context of a configuration statement multiple times.

Instead of:

 MyType myType = new MyType()
 myType.doThis()
 myType.doThat()

you can do:

 MyType myType = configure(new MyType()) {
     doThis()
     doThat()
 }

The object being configured is also passed to the closure as a parameter, so you can access it explicitly if required:

 configure(someObj) { obj -> obj.doThis() }

Parameters:: object - The object to configure; configureClosure - The closure with configure statements

Returns:: The configured object

configure

public Iterable configure(Iterable objects, Closure configureClosure)

Configures a collection of objects via a closure. This is equivalent to calling configure for each of the given objects.

Parameters:: objects - The objects to configure; configureClosure - The closure with configure statements

Returns:: The configured objects.

configure

public Iterable configure(Iterable objects, Action configureAction)

Configures a collection of objects via an action.

Parameters:: objects - The objects to configure; configureAction - The action to apply to each object

Returns:: The configured objects.

container

public NamedDomainObjectContainer container(Class type)

Creates a container for managing named objects of the specified type. The specified type must have a public constructor which takes the name as a String parameter.

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

Parameters:: type - The type of objects for the container to contain.; - The type of objects for the container to contain.

Returns:: The container.

container

public NamedDomainObjectContainer container(Class type, NamedDomainObjectFactory factory)

Creates a container for managing named objects of the specified type. The given factory is used to create object instances.

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

Parameters:: type - The type of objects for the container to contain.; factory - The factory to use to create object instances.; - The type of objects for the container to contain.

Returns:: The container.

container

public NamedDomainObjectContainer container(Class type, Closure factoryClosure)

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.

Parameters:: type - The type of objects for the container to contain.; factoryClosure - The closure to use to create object instances.; - The type of objects for the container to contain.

Returns:: The container.

copy

public WorkResult copy(Closure closure)

Copies the specified files. The given closure is used to configure a CopySpec, which is then used to copy the files. Example:

 copy {
    from configurations.runtime
    into 'build/deploy/lib'
 }

Note that CopySpecs can be nested:

 copy {
    into 'build/webroot'
    exclude '**/.svn/**'
    from('src/main/webapp') {
       include '**/*.jsp'
       filter(ReplaceTokens, tokens:[copyright:'2009', version:'2.3.1'])
    }
    from('src/main/js') {
       include '**/*.js'
    }
 }

Parameters:: closure - Closure to configure the CopySpec

Returns:: WorkResult that can be used to check if the copy did any work.

copySpec

public CopySpec copySpec(Closure closure)

Creates a CopySpec which can later be used to copy files or create an archive. The given closure is used to configure the CopySpec before it is returned by this method.

Parameters:: closure - Closure to configure the CopySpec

Returns:: The CopySpec

createAntBuilder

public AntBuilder createAntBuilder()

Creates an additional AntBuilder for this project. You can use this in your build file to execute ant tasks.

Returns:: Creates an AntBuilder for this project. Never returns null.

See Also:: getAnt()

defaultTasks

public void defaultTasks(String... defaultTasks)

Sets the names of the default tasks of this project. These are used when no tasks names are provided when starting the build.

Parameters:: defaultTasks - The default task names.

delete

public boolean delete(Object... paths)

Deletes files and directories.

Parameters:: paths - Any type of object accepted by Project.files

Returns:: true if anything got deleted, false otherwise

dependencies

public void dependencies(Closure configureClosure)

Configures the dependencies for this project.

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

Examples:

See docs for DependencyHandler

Parameters:: configureClosure - the closure to use to configure the dependencies.

dependsOn

@Deprecated
public void dependsOn(String path)

Declares that this project has an execution dependency on the project with the given path.

deprecated:: Use Task.dependsOn instead.

throws:: UnknownProjectException If no project with the given path exists.

Parameters:: path - The path of the project which this project depends on.

dependsOn

@Deprecated
public void dependsOn(String path, boolean evaluateDependsOnProject)

Declares that this project has an execution dependency on the project with the given path.

deprecated:: Use Task.dependsOn instead.

throws:: UnknownProjectException If no project with the given path exists.

Parameters:: path - The path of the project which this project depends on.; evaluateDependsOnProject - If true, adds an evaluation dependency.

dependsOnChildren

@Deprecated
public Project dependsOnChildren()

Declares that this project has an execution dependency on each of its child projects.

deprecated:: Use Task.dependsOn instead.

Returns:: this project.

dependsOnChildren

@Deprecated
public Project dependsOnChildren(boolean evaluateDependsOnProject)

Declares that this project has an execution dependency on each of its child projects.

deprecated:: To definde task dependencies use Task.dependsOn instead. For declaring evaluation dependencies to child projects, use evaluation dependencies use evaluationDependsOnChildren().

Parameters:: evaluateDependsOnProject - If true, adds an evaluation dependency.

Returns:: this project.

depthCompare

public int depthCompare(Project otherProject)

Compares the nesting level of this project with another project of the multi-project hierarchy.

Parameters:: otherProject - The project to compare the nesting level with.

Returns:: a negative integer, zero, or a positive integer as this project has a nesting level less than, equal to, or greater than the specified object.

See Also:: getDepth()

evaluationDependsOn

public Project evaluationDependsOn(String path)

Declares that this project has an evaluation dependency on the project with the given path.

throws:: UnknownProjectException If no project with the given path exists.

Parameters:: path - The path of the project which this project depends on.

Returns:: The project which this project depends on.

evaluationDependsOnChildren

public void evaluationDependsOnChildren()

Declares that this project has an evaluation dependency on each of its child projects.

exec

public ExecResult exec(Closure closure)

Executes an external command. The closure configures a ExecSpec.

Parameters:: closure - The closure for configuring the execution.

Returns:: the result of the execution

file

public File file(Object path)

Resolves a file path relative to the project directory of this project. This method converts the supplied path based on its type:

A CharSequence, including String or GString. Interpreted relative to the project directory. A string that starts with file: is treated as a file URL.
A File. If the file is an absolute file, it is returned as is. Otherwise, the file's path is interpreted relative to the project directory.
A URI or URL. The URL's path is interpreted as the file path. Currently, only file: URLs are supported.
A Closure. The closure's return value is resolved recursively.
A Callable. The callable's return value is resolved recursively.
An Object. Its toString() value is treated the same way as a String. This is deprecated and will be removed in the next version of Gradle.

Parameters:: path - The object to resolve as a File.

Returns:: The resolved file. Never returns null.

file

public File file(Object path, PathValidation validation)

Resolves a file path relative to the project directory of this project and validates it using the given scheme. See PathValidation for the list of possible validations.

throws:: InvalidUserDataException When the file does not meet the given validation constraint.

Parameters:: path - An object which toString method value is interpreted as a relative path to the project directory.; validation - The validation to perform on the file.

Returns:: The resolved file. Never returns null.

fileTree

public ConfigurableFileTree fileTree(Object baseDir)

Creates a new ConfigurableFileTree using the given base directory. The given baseDir path is evaluated as per file(Object).

Note: to use a closure as the baseDir, you must explicitly cast the closure to Object to force the use of this method instead of fileTree(Closure). Example:

 fileTree((Object){ someDir })

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.

Parameters:: baseDir - The base directory of the file tree. Evaluated as per file(Object).

Returns:: the file tree. Never returns null.

fileTree

public ConfigurableFileTree fileTree(Object baseDir, Closure configureClosure)

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

 fileTree('src') {
    exclude '**/.svn/**'
 }.copy { into 'dest'}

Parameters:: baseDir - The base directory of the file tree. Evaluated as per file(Object).; configureClosure - Closure to configure the ConfigurableFileTree object.

Returns:: the configured file tree. Never returns null.

fileTree

public ConfigurableFileTree fileTree(Map args)

Creates a new ConfigurableFileTree using the provided map of arguments. The map will be applied as properties on the new file tree. Example:

 fileTree(dir:'src', excludes:['**/ignore/**','**/.svn/**'])

Parameters:: args - map of property assignments to ConfigurableFileTree object

Returns:: the configured file tree. Never returns null.

fileTree

@Deprecated
public ConfigurableFileTree fileTree(Closure closure)

Creates a new ConfigurableFileTree using the provided closure. The closure will be used to configure the new file tree. The file tree is passed to the closure as its delegate. Example:

 fileTree {
    from 'src'
    exclude '**/.svn/**'
 }.copy { into 'dest'}

deprecated:: Use fileTree(Object,Closure) instead.

Parameters:: closure - Closure to configure the ConfigurableFileTree object

Returns:: the configured file tree. Never returns null.

files

public ConfigurableFileCollection files(Object... paths)

Returns a ConfigurableFileCollection containing the given files. You can pass any of the following types to this method:

A CharSequence, including String or GString. Interpreted relative to the project directory, as per file(Object). A string that starts with file: is treated as a file URL.
A File. Interpreted relative to the project directory, as per file(Object).
A URI or URL. The URL's path is interpreted as a file path. Currently, only file: URLs are supported.
A Collection, Iterable, or an array. May contain any of the types listed here. The elements of the collection are recursively converted to files.
A FileCollection. The contents of the collection are included in the returned collection.
A Callable. The call() method may return any of the types listed here. The return value of the call() method is recursively converted to files. A null return value is treated as an empty collection.
A Closure. May return 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.
A TaskOutputs. Converted to the output files the related task.
An Object. Its toString() value is treated the same way as a String, as per file(Object). This has been deprecated and will be removed in the next version of Gradle.

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.

Parameters:: paths - The paths to the files. May be empty.

Returns:: The file collection. Never returns null.

files

public ConfigurableFileCollection files(Object paths, Closure configureClosure)

Creates a new ConfigurableFileCollection using the given paths. The paths are evaluated as per files(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'
 }

Parameters:: paths - The contents of the file collection. Evaluated as per files(Object...).; configureClosure - The closure to use to configure the file collection.

Returns:: the configured file tree. Never returns null.

findProject

public Project findProject(String path)

Locates a project by path. If the path is relative, it is interpreted relative to this project.

Parameters:: path - The path.

Returns:: The project with the given path. Returns null if no such project exists.

getAllTasks

public Map getAllTasks(boolean recursive)

Returns a map of the tasks contained in this project, and optionally its subprojects.

Parameters:: recursive - If true, returns the tasks of this project and its subprojects. If false, returns the tasks of just this project.

Returns:: A map from project to a set of tasks.

getAllprojects

public Set getAllprojects()

Returns the set containing this project and its subprojects.

Returns:: The set of projects.

getAnt

public AntBuilder getAnt()

Returns the AntBuilder for this project. You can use this in your build file to execute ant tasks. See example below.

 task printChecksum {
   doLast {
     ant {
       //using ant checksum task to store the file checksum in the checksumOut ant property
       checksum(property: 'checksumOut', file: 'someFile.txt')

       //we can refer to the ant property created by checksum task:
       println "The checksum is: " + checksumOut
     }

     //we can refer to the ant property later as well:
     println "I just love to print checksums: " + ant.checksumOut
   }
 }

Consider following example of ant target:

 <target name='printChecksum'>
   <checksum property='checksumOut'>
     <fileset dir='.'>
       <include name='agile.txt'/>
     </fileset>
   </checksum>
   <echo>The checksum is: ${checksumOut}</echo>
 </target>

Here's how it would look like in gradle. Observe how the ant XML is represented in groovy by the ant builder

 task printChecksum {
   doLast {
     ant {
       checksum(property: 'checksumOut') {
         fileset(dir: '.') {
           include name: 'agile1.txt'
         }
       }
     }
     logger.lifecycle("The checksum is $ant.checksumOut")
   }
 }

Returns:: The AntBuilder for this project. Never returns null.

getArtifacts

public ArtifactHandler getArtifacts()

Returns a handler for assigning artifacts produced by the project to configurations.

Examples:

See docs for ArtifactHandler

getBuildDir

public File getBuildDir()

Returns the build directory of this project. The build directory is the directory which all artifacts are generated into. The default value for the build directory is projectDir/build

Returns:: The build directory. Never returns null.

getBuildFile

public File getBuildFile()

Returns the build file Gradle will evaluate against this project object. The default is {

value:: #DEFAULT_BUILD_FILE}. If an embedded script is provided the build file will be null.

Returns:: Current build file. May return null.

getBuildscript

public ScriptHandler getBuildscript()

Returns 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.

Returns:: the classpath handler. Never returns null.

getChildProjects

public Map getChildProjects()

Returns the direct children of this project.

Returns:: A map from child project name to child project. Returns an empty map if this this project does not have any children.

getComponents

@Incubating
public SoftwareComponentContainer getComponents()

Returns the software components produced by this project.

Returns:: The components for this project.

getConfigurations

public ConfigurationContainer getConfigurations()

Returns the configurations of this project.

Examples:

See docs for ConfigurationContainer

Returns:: The configuration of this project.

getConvention

public Convention getConvention()

Returns the Convention for this project.

You can access this property in your build file using convention. You can also 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

Returns:: The Convention. Never returns null.

getDefaultTasks

public List getDefaultTasks()

Returns the names of the default tasks of this project. These are used when no tasks names are provided when starting the build.

Returns:: The default task names. Returns an empty list if this project has no default tasks.

getDependencies

public DependencyHandler getDependencies()

Returns the dependency handler of this project. The returned dependency handler instance can be used for adding new dependencies. For accessing already declared dependencies, the configurations can be used.

Examples:

See docs for DependencyHandler

Returns:: the dependency handler. Never returns null.

See Also:: getConfigurations()

getDependsOnProjects

public Set getDependsOnProjects()

Returns the set of projects which this project depends on.

Returns:: The set of projects. Returns an empty set if this project depends on no projects.

getDepth

public int getDepth()

Returns the nesting level of a project in a multi-project hierarchy. For single project builds this is always 0. In a multi-project hierarchy 0 is returned for the root project.

getDescription

public String getDescription()

Returns the description of this project.

Returns:: the description. May return null.

getExtensions

public ExtensionContainer getExtensions()

Allows adding DSL extensions to the project. Useful for plugin authors.

Returns:: Returned instance allows adding DSL extensions to the project

getGradle

public Gradle getGradle()

Returns the Gradle invocation which this project belongs to.

Returns:: The Gradle object. Never returns null.

getGroup

public Object getGroup()

Returns the group of this project. Gradle always uses the toString() value of the group. The group defaults to the path with dots a separators.

Returns:: The group of this project. Never returns null.

getLogger

public Logger getLogger()

Returns the logger for this project. You can use this in your build file to write log messages.

Returns:: The logger. Never returns null.

getLogging

public LoggingManager getLogging()

Returns the LoggingManager which can be used to control the logging level and 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:: the LoggingManager. Never returns null.

getName

public String getName()

Returns the name of this project. The project's name is not necessarily unique within a project hierarchy. You should use the getPath() method for a unique identifier for the project.

Returns:: The name of this project. Never return null.

getParent

public Project getParent()

Returns the parent project of this project, if any.

Returns:: The parent project, or null if this is the root project.

getPath

public String getPath()

Returns the path of this project. The path is the fully qualified name of the project.

Returns:: The path. Never returns null.

getPlugins

public PluginContainer getPlugins()

Returns the plugins container for this project. The returned container can be used to manage the plugins which are used by this project.

Returns:: the plugin container. Never returns null.

getProject

public Project getProject()

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.

Returns:: This project. Never returns null.

getProjectDir

public File getProjectDir()

The directory containing the project build file.

Returns:: The project directory. Never returns null.

getProperties

public Map getProperties()

Returns the properties of this project. See here for details of the properties which are available for a project.

Returns:: A map from property name to value.

getRepositories

public RepositoryHandler getRepositories()

Returns a handler to create repositories which are used for retrieving dependencies and uploading artifacts produced by the project.

Returns:: the repository handler. Never returns null.

getResources

public ResourceHandler getResources()

Provides access to resource-specific utility methods, for example factory methods that create various resources.

Returns:: Returned instance contains various resource-specific utility methods.

getRootDir

public File getRootDir()

Returns the root directory of this project. The root directory is the project directory of the root project.

Returns:: The root directory. Never returns null.

getRootProject

public Project getRootProject()

Returns the root project for the hierarchy that this project belongs to. In the case of a single-project build, this method returns this project.

Returns:: The root project. Never returns null.

getState

public ProjectState getState()

Returns the evaluation state of this project. You can use this to access information about the evaluation of this project, such as whether it has failed.

Returns:: the project state. Never returns null.

getStatus

public Object getStatus()

Returns the status of this project. Gradle always uses the toString() value of the status. The status defaults to {

value:

#DEFAULT_STATUS}.

The status of the project is only relevant, if you upload libraries together with a module descriptor. The status specified here, will be part of this module descriptor.

Returns:: The status of this project. Never returns null.

getSubprojects

public Set getSubprojects()

Returns the set containing the subprojects of this project.

Returns:: The set of projects. Returns an empty set if this project has no subprojects.

getTasks

public TaskContainer getTasks()

Returns the tasks of this project.

Returns:: the tasks of this project.

getTasksByName

public Set getTasksByName(String name, boolean recursive)

Returns the set of tasks with the given name contained in this project, and optionally its subprojects.

Parameters:: name - The name of the task to locate.; recursive - If true, returns the tasks of this project and its subprojects. If false, returns the tasks of just this project.

Returns:: The set of tasks. Returns an empty set if no such tasks exist in this project.

getVersion

public Object getVersion()

Returns the version of this project. Gradle always uses the toString() value of the version. The version defaults to {

value:: #DEFAULT_VERSION}.

Returns:: The version of this project. Never returns null.

hasProperty

public boolean hasProperty(String propertyName)

Determines if this project has the given property. See here for details of the properties which are available for a project.

Parameters:: propertyName - The name of the property to locate.

Returns:: True if this project has the given property, false otherwise.

javaexec

public ExecResult javaexec(Closure closure)

Executes a Java main class. The closure configures a JavaExecSpec.

Parameters:: closure - The closure for configuring the execution.

Returns:: the result of the execution

mkdir

public File mkdir(Object path)

Creates a directory and returns a file pointing to it.

throws:: org.gradle.api.InvalidUserDataException If the path points to an existing file.

Parameters:: path - The path for the directory to be created. Evaluated as per file(Object).

Returns:: the created directory

project

public Project project(String path)

Locates a project by path. If the path is relative, it is interpreted relative to this project.

throws:: UnknownProjectException If no project with the given path exists.

Parameters:: path - The path.

Returns:: The project with the given path. Never returns null.

project

public Project project(String path, Closure configureClosure)

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.

throws:: UnknownProjectException If no project with the given path exists.

Parameters:: path - The path.; configureClosure - The closure to use to configure the project.

Returns:: The project with the given path. Never returns null.

property

public Object property(String propertyName)

Returns the value of the given property. This method locates a property as follows:

If this project object has a property with the given name, return the value of the property.
If this project's convention object has a property with the given name, return the value of the property.
If this project has an additional property with the given name, return the value of the property.
If this project has a task with the given name, return the task.
Search up through this project's ancestor projects for a convention property or additional property with the given name.
If not found, throw MissingPropertyException

throws:: MissingPropertyException When the given property is unknown.

Parameters:: propertyName - The name of the property.

Returns:: The value of the property, possibly null.

relativePath

public String relativePath(Object path)

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

Parameters:: path - The path to convert to a relative path.

Returns:: The relative path. Never returns null.

relativeProjectPath

public String relativeProjectPath(String path)

Converts a name to a project path relative to this project.

Parameters:: path - The path to convert.

Returns:: The relative path.

repositories

public void repositories(Closure configureClosure)

Configures the repositories for this project.

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

Parameters:: configureClosure - the closure to use to configure the repositories.

setBuildDir

public void setBuildDir(Object path)

Sets the build directory of this project. The build directory is the directory which all artifacts are generated into. The path parameter is evaluated as described for file(Object). This mean you can use, amongst other things, a relative or absolute path or File object to specify the build directory.

Parameters:: path - The build directory. This is evaluated as per file(Object)

setDefaultTasks

public void setDefaultTasks(List defaultTasks)

Sets the names of the default tasks of this project. These are used when no tasks names are provided when starting the build.

Parameters:: defaultTasks - The default task names.

setDescription

public void setDescription(String description)

Sets a description for this project.

Parameters:: description - The description of the project. Might be null.

setGroup

public void setGroup(Object group)

Sets the group of this project.

Parameters:: group - The group of this project. Must not be null.

setProperty

public void setProperty(String name, Object value)

Sets a property of this project. This method searches for a property with the given name in the following locations, and sets the property on the first location where it finds the property.

The project object itself. For example, the rootDir project property.
The project's Convention object. For example, the srcRootName java plugin property.
The project's additional properties.

If the property is not found in any of these locations, it is added to the project's additional properties.

Parameters:: name - The name of the property; value - The value of the property

setStatus

public void setStatus(Object status)

Sets the status of this project.

Parameters:: status - The status. Must not be null.

setVersion

public void setVersion(Object version)

Sets the version of this project.

Parameters:: version - The version of this project. Must not be null.

subprojects

public void subprojects(Action action)

Configures the sub-projects of this project

This method executes the given Action against the sub-projects of this project.

Parameters:: action - The action to execute.

subprojects

public void subprojects(Closure configureClosure)

Configures the sub-projects of this project.

This method executes the given closure against each of the sub-projects of this project. The target Project is passed to the closure as the closure's delegate.

Parameters:: configureClosure - The closure to execute.

tarTree

public FileTree tarTree(Object tarPath)

Creates a new FileTree which contains the contents of the given TAR file. The given tarPath path can be:

an instance of Resource
any other object is evaluated as per file(Object)

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

You can combine this method with the copy(groovy.lang.Closure) method to untar a TAR file:

 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'
 }

Parameters:: tarPath - The TAR file or an instance of Resource.

Returns:: the file tree. Never returns null.

task

public Task task(String name)

Creates a Task with the given name and adds it to this project. Calling this method is equivalent to calling task(java.util.Map, String) with an empty options map.

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, an exception is thrown.

throws:: InvalidUserDataException If a task with the given name already exists in this project.

Parameters:: name - The name of the task to be created

Returns:: The newly created task object

task

public Task task(Map args, String name)

Creates a Task with the given name and adds it to this project. A map of creation options can be passed to this method to control how the task is created. The following options are available:

Option	Description	Default Value
`{` `value:` `org.gradle.api.Task#TASK_TYPE}`	The class of the task to create.	DefaultTask
`{@value org.gradle.api.Task#TASK_OVERWRITE}`	Replace an existing task?	`false`
`{@value org.gradle.api.Task#TASK_DEPENDS_ON}`	A task name or set of task names which this task depends on	`[]`
`{@value org.gradle.api.Task#TASK_ACTION}`	A closure or Action to add to the task.	`null`
`{@value org.gradle.api.Task#TASK_DESCRIPTION}`	A description of the task.	`null`
`{@value org.gradle.api.Task#TASK_GROUP}`	A task group which this task belongs to.	`null`

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.

throws:: InvalidUserDataException If a task with the given name already exists in this project.

Parameters:: args - The task creation options.; name - The name of the task to be created

Returns:: The newly created task object

task

public Task task(Map args, String name, Closure configureClosure)

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 task(java.util.Map, 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.

throws:: InvalidUserDataException If a task with the given name already exists in this project.

Parameters:: args - The task creation options.; name - The name of the task to be created; configureClosure - The closure to use to configure the created task.

Returns:: The newly created task object

task

public Task task(String name, Closure configureClosure)

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.

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

throws:: InvalidUserDataException If a task with the given name already exists in this project.

Parameters:: name - The name of the task to be created; configureClosure - The closure to use to configure the created task.

Returns:: The newly created task object

uri

public URI uri(Object path)

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

Parameters:: path - The object to resolve as a URI.

Returns:: The resolved URI. Never returns null.

zipTree

public FileTree zipTree(Object zipPath)

Creates a new FileTree which contains the contents of the given ZIP file. The given zipPath path is evaluated as per file(Object). You can combine this method with the copy(groovy.lang.Closure) method to unzip a ZIP file.

Parameters:: zipPath - The ZIP file. Evaluated as per file(Object).

Returns:: the file tree. Never returns null.

Gradle API 1.8

org.gradle.api [Java] Interface Project

Lifecycle

Tasks

Dependencies

Multi-project Builds

Properties

Extra Properties

Dynamic Methods

DEFAULT_BUILD_DIR_NAME

DEFAULT_BUILD_FILE

DEFAULT_STATUS

DEFAULT_VERSION

GRADLE_PROPERTIES

PATH_SEPARATOR

SYSTEM_PROP_PREFIX

absoluteProjectPath

afterEvaluate

afterEvaluate

allprojects

allprojects

ant

apply

apply

artifacts

beforeEvaluate

beforeEvaluate

buildscript

childrenDependOnMe

configurations

Examples:

configure

configure

configure

container

container

container

copy

copySpec

createAntBuilder

defaultTasks

delete

dependencies

Examples:

dependsOn

dependsOn

dependsOnChildren

dependsOnChildren

depthCompare

evaluationDependsOn

evaluationDependsOnChildren

exec

file

file

fileTree

fileTree

fileTree

fileTree

files

files

findProject

getAllTasks

getAllprojects

getAnt

getArtifacts

Examples:

getBuildDir

getBuildFile

getBuildscript

getChildProjects

getComponents

getConfigurations

Examples:

getConvention

getDefaultTasks

getDependencies

Examples:

getDependsOnProjects

getDepth

getDescription

getExtensions

org.gradle.api
[Java] Interface Project