API Documentation: | 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.
There is a one-to-one relationship between a Project
and a
file. During build initialisation, Gradle assembles a build.gradle
Project
object for each project which is to
participate in the build, as follows:
- Create a
Settings
instance for the build. - Evaluate the
script, if present, against thesettings.gradle
Settings
object to configure it. - Use the configured
Settings
object to create the hierarchy ofProject
instances. - Finally, evaluate each
Project
by executing its
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 callingbuild.gradle
or by adding an explicit evaluation dependency usingProject.evaluationDependsOnChildren()
.Project.evaluationDependsOn()
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 TaskContainer.create()
. You can locate existing
tasks using one of the lookup methods on TaskContainer
, such as TaskCollection.getByName()
.
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 Project.getConfigurations()
method to manage the configurations. The DependencyHandler
returned by Project.getDependencies()
method to manage the
dependencies. The ArtifactHandler
returned by Project.getArtifacts()
method to
manage the artifacts. The RepositoryHandler
returned by Project.getRepositories()
method to manage the repositories.
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.
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 Project.property()
method. The scopes are:
- The
Project
object itself. This scope includes any property getters and setters declared by theProject
implementation class. For example,Project.getRootProject()
is accessible as therootProject
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 thecompile
property. - The extra properties and convention properties 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()
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 Project.setProperty()
for more details.
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 }
Reading extra properties is done through the "ext" or through the owning object.
ext.isSnapshot = version.endsWith("-SNAPSHOT") if (isSnapshot) { // do snapshot stuff }
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
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 theTask.configure()
method for the associated task with the provided closure. For example, if the project has a task calledcompile
, 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.
Property | Description |
allprojects | The set containing this project and its subprojects. |
ant | The |
artifacts | Returns a handler for assigning artifacts produced by the project to configurations. |
buildDir | 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 |
buildFile | The build file Gradle will evaluate against this project object. The default is |
buildscript | 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. |
childProjects | The direct children of this project. |
configurations | The configurations of this project. |
convention | The |
defaultTasks | The names of the default tasks of this project. These are used when no tasks names are provided when starting the build. |
dependencies | 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. |
description | The description of this project. |
extensions | Allows adding DSL extensions to the project. Useful for plugin authors. |
gradle | The |
group | The group of this project. Gradle always uses the |
logger | The logger for this project. You can use this in your build file to write log messages. |
logging | The |
name | The name of this project. The project's name is not necessarily unique within a project hierarchy. You
should use the |
parent | The parent project of this project, if any. |
path | The path of this project. The path is the fully qualified name of the project. |
plugins | The plugins container for this project. The returned container can be used to manage the plugins which are used by this project. |
project | Returns this project. This method is useful in build files to explicitly access project properties and
methods. For example, using |
projectDir | The directory containing the project build file. |
properties | The properties of this project. See here for details of the properties which are available for a project. |
repositories | Returns a handler to create repositories which are used for retrieving dependencies and uploading artifacts produced by the project. |
resources | Provides access to resource-specific utility methods, for example factory methods that create various resources. |
rootDir | The root directory of this project. The root directory is the project directory of the root project. |
rootProject | The root project for the hierarchy that this project belongs to. In the case of a single-project build, this method returns this project. |
state | 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. |
status | The status of this project. Gradle always uses the |
subprojects | The set containing the subprojects of this project. |
tasks | The tasks of this project. |
version | The version of this project. Gradle always uses the |
Property | Description |
binaries | The |
softwareComponents | The |
sources | The |
Property | Description |
announce | The |
Property | Description |
applicationDefaultJvmArgs | Array of string arguments to pass to the JVM when running the application |
applicationDistribution | The specification of the contents of the distribution. |
applicationName | The name of the application. |
mainClassName | The fully qualified name of the application's main class. |
Property | Description |
checkstyle | The |
Property | Description |
codenarc | The |
Property | Description |
testSuites | The |
Property | Description |
distributions | The |
Property | Description |
appDirName | The name of the application directory, relative to the project directory. Default is "src/main/application". |
deploymentDescriptor | A custom deployment descriptor configuration. Default is an "application.xml" with sensible defaults. |
libDirName | The name of the library directory in the EAR file. Default is "lib". |
Property | Description |
eclipse | The |
Property | Description |
findbugs | The |
Property | Description |
jacoco | The |
Property | Description |
archivesBaseName | The base name to use for archive files. |
distsDir | The directory to generate TAR and ZIP archives into. |
distsDirName | The name for the distributions directory. This in interpreted relative to the project' build directory. |
docsDir | Returns a file pointing to the root directory supposed to be used for all docs. |
docsDirName | The name of the docs directory. Can be a name or a path relative to the build dir. |
libsDir | The directory to generate JAR and WAR archives into. |
libsDirName | The name for the libs directory. This in interpreted relative to the project' build directory. |
reporting | The |
sourceCompatibility | The source compatibility used for compiling Java sources. |
sourceSets | The source sets container. |
targetCompatibility | The target compatibility used for compiling Java sources. |
testReportDir | Returns a file pointing to the root directory to be used for reports. |
testReportDirName | The name of the test reports directory. Can be a name or a path relative to the build dir. |
testResultsDir | Returns a file pointing to the root directory of the test results. |
testResultsDirName | The name of the test results directory. Can be a name or a path relative to the build dir. |
Property | Description |
jdepend | The |
Property | Description |
jvm | The |
Property | Description |
conf2ScopeMappings | The set of rules for how to map Gradle dependencies to Maven scopes. |
mavenPomDir | The directory to generate Maven POMs into. |
Property | Description |
buildTypes | The |
flavors | The |
nativeCode | The |
platforms | The |
toolChains | The |
Property | Description |
pmd | The |
Property | Description |
projectReportDir | The directory to generate the project reports into. |
projectReportDirName | The name of the directory to generate the project reports into, relative to the project's reports dir. |
Property | Description |
publishing | The |
Property | Description |
signing | The |
Property | Description |
visualStudio | The |
Property | Description |
webAppDir | The web application directory. |
webAppDirName | The name of the web application directory, relative to the project directory. |
Method | Description |
absoluteProjectPath(path) | Converts a name to an absolute project path, resolving names relative to this project. |
afterEvaluate(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. |
afterEvaluate(action) | Adds an action to execute immediately after this project is evaluated. |
allprojects(action) | Configures this project and each of its sub-projects. |
apply(closure) | Configures this project using plugins or scripts. The given closure is used to configure an |
apply(options) | Configures this project using plugins or scripts. The following options are available: |
beforeEvaluate(closure) | Adds a closure to be called immediately before this project is evaluated. The project is passed to the closure as a parameter. |
beforeEvaluate(action) | Adds an action to execute immediately before this project is evaluated. |
configure(objects, configureClosure) | Configures a collection of objects via a closure. This is equivalent to calling |
configure(objects, configureAction) | Configures a collection of objects via an action. |
configure(object, 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. |
container(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. |
container(type, 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. |
container(type, factory) | Creates a container for managing named objects of the specified type. The given factory is used to create object instances. |
copy(closure) | Copies the specified files. The given closure is used to configure a |
copySpec(closure) | Creates a |
delete(paths) | Deletes files and directories. |
evaluationDependsOn(path) | Declares that this project has an evaluation dependency on the project with the given path. |
exec(closure) | Executes an external command. The closure configures a |
file(path) | Resolves a file path relative to the project directory of this project. This method converts the supplied path based on its type: |
file(path, validation) | Resolves a file path relative to the project directory of this project and validates it using the given
scheme. See |
fileTree(baseDir) | Creates a new |
fileTree(baseDir, configureClosure) | Creates a new |
fileTree(args) | Creates a new |
files(paths, configureClosure) | Creates a new |
files(paths) | Returns a |
findProject(path) | Locates a project by path. If the path is relative, it is interpreted relative to this project. |
getAllTasks(recursive) | Returns a map of the tasks contained in this project, and optionally its subprojects. |
getTasksByName(name, recursive) | Returns the set of tasks with the given name contained in this project, and optionally its subprojects. |
hasProperty(propertyName) | Determines if this project has the given property. See here for details of the properties which are available for a project. |
javaexec(closure) | Executes a Java main class. The closure configures a |
mkdir(path) | Creates a directory and returns a file pointing to it. |
project(path) | Locates a project by path. If the path is relative, it is interpreted relative to this project. |
project(path, 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. |
property(propertyName) | Returns the value of the given property. This method locates a property as follows: |
relativePath(path) | Returns the relative path from the project directory to the given path. The given path object is (logically)
resolved as described for |
relativeProjectPath(path) | Converts a name to a project path relative to this project. |
setProperty(name, 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. |
subprojects(action) | Configures the sub-projects of this project |
tarTree(tarPath) | Creates a new |
task(name) | Creates a |
task(name, configureClosure) | Creates a |
task(args, name) | Creates a |
task(args, name, configureClosure) | Creates a |
uri(path) | Resolves a file path to a URI, relative to the project directory of this project. Evaluates the provided path
object as described for |
zipTree(zipPath) | Creates a new |
Method | Description |
appDirName(appDirName) | Allows changing the application directory. Default is "src/main/application". |
libDirName(libDirName) | Allows changing the library directory in the EAR file. Default is "lib". |
Method | Description |
osgiManifest() | Creates a new instance of |
osgiManifest(closure) | Creates and configures a new instance of an |
Block | Description |
allprojects | Configures this project and each of its sub-projects. |
ant | Executes the given closure against the |
artifacts | Configures the published artifacts for this project. |
buildscript | Configures the build script classpath for this project. |
configurations | Configures the dependency configurations for this project. |
dependencies | Configures the dependencies for this project. |
repositories | Configures the repositories for this project. |
subprojects | Configures the sub-projects of this project. |
Block | Description |
binaries | Configures the |
softwareComponents | Configures the |
sources | Configures the |
Block | Description |
announce | Configures the |
Block | Description |
checkstyle | Configures the |
Block | Description |
codenarc | Configures the |
Block | Description |
testSuites | Configures the |
Block | Description |
distributions | Configures the |
Block | Description |
deploymentDescriptor | Configures the deployment descriptor for this EAR archive. |
Block | Description |
eclipse | Configures the |
Block | Description |
findbugs | Configures the |
Block | Description |
jacoco | Configures the |
Block | Description |
reporting | Configures the |
sourceSets | Configures the source sets of this project. |
Block | Description |
jdepend | Configures the |
Block | Description |
jvm | Configures the |
Block | Description |
buildTypes | Configures the |
flavors | Configures the |
nativeCode | Configures the |
platforms | Configures the |
toolChains | Configures the |
Block | Description |
pmd | Configures the |
Block | Description |
publishing | Configures the |
Block | Description |
signing | Configures the |
Block | Description |
visualStudio | Configures the |
AntBuilder
ant
(read-only)
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") } }
ArtifactHandler
artifacts
(read-only)
Returns a handler for assigning artifacts produced by the project to configurations.
See docs for ArtifactHandler
File
buildDir
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
File
buildFile
(read-only)
The build file Gradle will evaluate against this project object. The default is
. If an embedded script is provided the build file will be null. build.gradle
ScriptHandler
buildscript
(read-only)
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.
ConfigurationContainer
configurations
(read-only)
The configurations of this project.
See docs for ConfigurationContainer
Convention
convention
(read-only)
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
The names of the default tasks of this project. These are used when no tasks names are provided when starting the build.
DependencyHandler
dependencies
(read-only)
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.
See docs for DependencyHandler
String
description
The description of this project.
ExtensionContainer
extensions
(read-only)
Allows adding DSL extensions to the project. Useful for plugin authors.
Object
group
The group of this project. Gradle always uses the toString()
value of the group. The group
defaults to the path with dots a separators.
Logger
logger
(read-only)
The logger for this project. You can use this in your build file to write log messages.
LoggingManager
logging
(read-only)
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.
String
name
(read-only)
The name of this project. The project's name is not necessarily unique within a project hierarchy. You
should use the Project.getPath()
method for a unique identifier for the project.
Project
parent
(read-only)
The parent project of this project, if any.
String
path
(read-only)
The path of this project. The path is the fully qualified name of the project.
PluginContainer
plugins
(read-only)
The plugins container for this project. The returned container can be used to manage the plugins which are used by this project.
Project
project
(read-only)
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.
File
projectDir
(read-only)
The directory containing the project build file.
The properties of this project. See here for details of the properties which are available for a project.
RepositoryHandler
repositories
(read-only)
Returns a handler to create repositories which are used for retrieving dependencies and uploading artifacts produced by the project.
ResourceHandler
resources
(read-only)
Provides access to resource-specific utility methods, for example factory methods that create various resources.
File
rootDir
(read-only)
The root directory of this project. The root directory is the project directory of the root project.
Project
rootProject
(read-only)
The root project for the hierarchy that this project belongs to. In the case of a single-project build, this method returns this project.
ProjectState
state
(read-only)
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.
Object
status
The status of this project. Gradle always uses the toString()
value of the status. The status
defaults to release
.
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.
TaskContainer
tasks
(read-only)
The tasks of this project.
Object
version
The version of this project. Gradle always uses the toString()
value of the version. The
version defaults to unspecified
.
BinaryContainer
binaries
(read-only)
The BinaryContainer
added by the LanguageBasePlugin plugin.
ProjectComponentContainer
softwareComponents
(read-only)
The ProjectComponentContainer
added by the LanguageBasePlugin plugin.
ProjectSourceSet
sources
(read-only)
The ProjectSourceSet
added by the LanguageBasePlugin plugin.
AnnouncePluginExtension
announce
(read-only)
The AnnouncePluginExtension
added by the announce plugin.
Array of string arguments to pass to the JVM when running the application
CopySpec
applicationDistribution
The specification of the contents of the distribution.
Use this CopySpec
to include extra files/resource in the application distribution.
apply plugin: 'application' applicationDistribution.from("some/dir") { include "*.txt" }
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.
String
applicationName
The name of the application.
String
mainClassName
The fully qualified name of the application's main class.
CheckstyleExtension
checkstyle
(read-only)
The CheckstyleExtension
added by the checkstyle plugin.
CodeNarcExtension
codenarc
(read-only)
The CodeNarcExtension
added by the codenarc plugin.
TestSuiteContainer
testSuites
(read-only)
The TestSuiteContainer
added by the cunit plugin.
DistributionContainer
distributions
(read-only)
The DistributionContainer
added by the distribution plugin.
String
appDirName
The name of the application directory, relative to the project directory. Default is "src/main/application".
DeploymentDescriptor
deploymentDescriptor
A custom deployment descriptor configuration. Default is an "application.xml" with sensible defaults.
String
libDirName
The name of the library directory in the EAR file. Default is "lib".
EclipseModel
eclipse
(read-only)
The EclipseModel
added by the eclipse plugin.
FindBugsExtension
findbugs
(read-only)
The FindBugsExtension
added by the findbugs plugin.
JacocoPluginExtension
jacoco
(read-only)
The JacocoPluginExtension
added by the jacoco plugin.
String
archivesBaseName
The base name to use for archive files.
File
distsDir
(read-only)
The directory to generate TAR and ZIP archives into.
String
distsDirName
The name for the distributions directory. This in interpreted relative to the project' build directory.
File
docsDir
(read-only)
Returns a file pointing to the root directory supposed to be used for all docs.
String
docsDirName
The name of the docs directory. Can be a name or a path relative to the build dir.
File
libsDir
(read-only)
The directory to generate JAR and WAR archives into.
String
libsDirName
The name for the libs directory. This in interpreted relative to the project' build directory.
ReportingExtension
reporting
(read-only)
The ReportingExtension
added by the java plugin.
JavaVersion
sourceCompatibility
The source compatibility used for compiling Java sources.
SourceSetContainer
sourceSets
(read-only)
The source sets container.
JavaVersion
targetCompatibility
The target compatibility used for compiling Java sources.
File
testReportDir
(read-only)
Returns a file pointing to the root directory to be used for reports.
String
testReportDirName
The name of the test reports directory. Can be a name or a path relative to the build dir.
File
testResultsDir
(read-only)
Returns a file pointing to the root directory of the test results.
String
testResultsDirName
The name of the test results directory. Can be a name or a path relative to the build dir.
JDependExtension
jdepend
(read-only)
The JDependExtension
added by the jdepend plugin.
Integer
httpPort
The TCP port for Jetty to listen on for incoming HTTP requests.
String
stopKey
The key to use to stop Jetty.
Integer
stopPort
The TCP port for Jetty to listen on for stop requests.
JvmComponentExtension
jvm
(read-only)
The JvmComponentExtension
added by the jvm-component plugin.
Conf2ScopeMappingContainer
conf2ScopeMappings
The set of rules for how to map Gradle dependencies to Maven scopes.
File
mavenPomDir
The directory to generate Maven POMs into.
BuildTypeContainer
buildTypes
(read-only)
The BuildTypeContainer
added by the native-component plugin.
FlavorContainer
flavors
(read-only)
The FlavorContainer
added by the native-component plugin.
NativeComponentExtension
nativeCode
(read-only)
The NativeComponentExtension
added by the native-component plugin.
PlatformContainer
platforms
(read-only)
The PlatformContainer
added by the native-component plugin.
ToolChainRegistry
toolChains
(read-only)
The ToolChainRegistry
added by the native-component plugin.
PmdExtension
pmd
(read-only)
The PmdExtension
added by the pmd plugin.
File
projectReportDir
(read-only)
The directory to generate the project reports into.
String
projectReportDirName
The name of the directory to generate the project reports into, relative to the project's reports dir.
PublishingExtension
publishing
(read-only)
The PublishingExtension
added by the publishing plugin.
SigningExtension
signing
(read-only)
The SigningExtension
added by the signing plugin.
VisualStudioExtension
visualStudio
(read-only)
The VisualStudioExtension
added by the visual-studio plugin.
File
webAppDir
(read-only)
The web application directory.
String
webAppDirName
The name of the web application directory, relative to the project directory.
Converts a name to an absolute project path, resolving names relative to this project.
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.
Adds an action to execute immediately after this project is evaluated.
Configures this project and each of its sub-projects.
This method executes the given Action
against this project and each of its sub-projects.
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.
Configures this project using plugins or scripts. The following options are available:
from
: A script to apply to the project. Accepts any path supported byProject.uri()
.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
.
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.
Adds an action to execute immediately before this project is evaluated.
Configures a collection of objects via a closure. This is equivalent to calling Project.configure()
for each of the given objects.
Configures a collection of objects via an action.
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() }
NamedDomainObjectContainer
<T
>
container
(Class
<T
>
type)
NamedDomainObjectContainer
<T
>Class
<T
>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.
NamedDomainObjectContainer
<T
>
container
(Class
<T
>
type, Closure
factoryClosure)
NamedDomainObjectContainer
<T
>Class
<T
>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.
NamedDomainObjectContainer
<T
>
container
(Class
<T
>
type, NamedDomainObjectFactory
<T
>
factory)
NamedDomainObjectContainer
<T
>Class
<T
>NamedDomainObjectFactory
<T
>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.
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' } }
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.
boolean
delete
(Object
...
paths)
Object
...Deletes files and directories.
Declares that this project has an evaluation dependency on the project with the given path.
ExecResult
exec
(Closure
closure)
Executes an external command. The closure configures a ExecSpec
.
Resolves a file path relative to the project directory of this project. This method converts the supplied path based on its type:
- A
CharSequence
, includingString
orGString
. Interpreted relative to the project directory. A string that starts withfile:
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
orURL
. The URL's path is interpreted as the file path. Currently, onlyfile:
URLs are supported. - A
Closure
. The closure's return value is resolved recursively. - A
Callable
. The callable's return value is resolved recursively.
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.
ConfigurableFileTree
fileTree
(Object
baseDir)
Creates a new ConfigurableFileTree
using the given base directory. The given baseDir path is evaluated
as per Project.file()
.
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.
ConfigurableFileTree
fileTree
(Object
baseDir, Closure
configureClosure)
Creates a new ConfigurableFileTree
using the given base directory. The given baseDir path is evaluated
as per Project.file()
. 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'}
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.
ConfigurableFileTree
fileTree
(Map
<String
, ?>
args)
Map
<String
, ?>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/**'])
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.
ConfigurableFileCollection
files
(Object
paths, Closure
configureClosure)
Creates a new ConfigurableFileCollection
using the given paths. The paths are evaluated as per Project.files()
. 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.
ConfigurableFileCollection
files
(Object
...
paths)
Object
...Returns a ConfigurableFileCollection
containing the given files. You can pass any of the following
types to this method:
- A
CharSequence
, includingString
orGString
. Interpreted relative to the project directory, as perProject.file()
. A string that starts withfile:
is treated as a file URL. - A
File
. Interpreted relative to the project directory, as perProject.file()
. - A
URI
orURL
. The URL's path is interpreted as a file path. Currently, onlyfile:
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
. Thecall()
method may return any of the types listed here. The return value of thecall()
method is recursively converted to files. Anull
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 perProject.file()
. 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.
Locates a project by path. If the path is relative, it is interpreted relative to this project.
Returns a map of the tasks contained in this project, and optionally its subprojects.
Returns the set of tasks with the given name contained in this project, and optionally its subprojects.
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.
ExecResult
javaexec
(Closure
closure)
Executes a Java main class. The closure configures a JavaExecSpec
.
Locates a project by path. If the path is relative, it is interpreted relative to this project.
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 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 has an extension with the given name, return the extension.
- If this project's convention object has a property with the given name, return the value of the property.
- If this project has an extra 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 extra property with the given name.
- If not found, a
MissingPropertyException
is thrown.
Returns the relative path from the project directory to the given path. The given path object is (logically)
resolved as described for Project.file()
, from which a relative path is calculated.
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, thesrcRootName
java plugin property. - The project's extra properties.
If the property is not found, a MissingPropertyException
is thrown.
Configures the sub-projects of this project
This method executes the given Action
against the sub-projects of this project.
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
Project.file()
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.
You can combine this method with the Project.copy()
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' }
Creates a Task
with the given name and adds it to this project. Calling this method is equivalent to
calling Project.task()
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.
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
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 |
| The class of the task to create. | DefaultTask |
| Replace an existing task? | false |
| A task name or set of task names which this task depends on | [] |
| A closure or Action to add to the
task. | null |
| A description of the task. | null |
| 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.
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()
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()
, with the exception that any URI scheme is supported, not just
'file:' URIs.
Creates a new FileTree
which contains the contents of the given ZIP file. The given zipPath path is
evaluated as per Project.file()
. You can combine this method with the Project.copy()
method to unzip a ZIP file.
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.
void
appDirName
(String
appDirName)
Allows changing the application directory. Default is "src/main/application".
void
libDirName
(String
libDirName)
Allows changing the library directory in the EAR file. Default is "lib".
Creates and configures a new instance of a Manifest
. The given closure configures
the new manifest instance before it is returned.
Creates and configures a new MavenPom
. The given closure is executed to configure the new POM instance.
OsgiManifest
osgiManifest
()
Creates a new instance of OsgiManifest
. The returned object is preconfigured with:
version: project.version name: project.archivesBaseName symbolicName: project.group + "." + project.archivesBaseName (see below for exceptions to this rule)
The symbolic name is usually the group + "." + archivesBaseName, with the following exceptions
- if group has only one section (no dots) and archivesBaseName is not null then the first package name with classes is returned. eg. commons-logging:commons-logging -> org.apache.commons.logging
- if archivesBaseName is equal to last section of group then group is returned. eg. org.gradle:gradle -> org.gradle
- if archivesBaseName starts with last section of group that portion is removed. eg. org.gradle:gradle-core -> org.gradle.core
OsgiManifest
osgiManifest
(Closure
closure)
Creates and configures a new instance of an OsgiManifest
. The closure configures
the new manifest instance before it is returned.
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.
- Delegates to:
- Each
Project
inallprojects
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()
- Delegates to:
AntBuilder
fromant
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 }
- Delegates to:
ArtifactHandler
fromartifacts
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.
- Delegates to:
ScriptHandler
frombuildscript
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.
See docs for ConfigurationContainer
- Delegates to:
ConfigurationContainer
fromconfigurations
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.
See docs for DependencyHandler
- Delegates to:
DependencyHandler
fromdependencies
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.
- Delegates to:
RepositoryHandler
fromrepositories
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.
- Delegates to:
- Each
Project
insubprojects
Configures the BinaryContainer
added by the LanguageBasePlugin plugin.
- Delegates to:
BinaryContainer
frombinaries
Configures the ProjectComponentContainer
added by the LanguageBasePlugin plugin.
- Delegates to:
ProjectComponentContainer
fromsoftwareComponents
Configures the ProjectSourceSet
added by the LanguageBasePlugin plugin.
- Delegates to:
ProjectSourceSet
fromsources
Configures the AnnouncePluginExtension
added by the announce plugin.
- Delegates to:
AnnouncePluginExtension
fromannounce
Configures the CheckstyleExtension
added by the checkstyle plugin.
- Delegates to:
CheckstyleExtension
fromcheckstyle
Configures the CodeNarcExtension
added by the codenarc plugin.
- Delegates to:
CodeNarcExtension
fromcodenarc
Configures the TestSuiteContainer
added by the cunit plugin.
- Delegates to:
TestSuiteContainer
fromtestSuites
Configures the DistributionContainer
added by the distribution plugin.
- Delegates to:
DistributionContainer
fromdistributions
Configures the deployment descriptor for this EAR archive.
The given closure is executed to configure the deployment descriptor. The DeploymentDescriptor
is passed to the closure as its delegate.
- Delegates to:
DeploymentDescriptor
fromdeploymentDescriptor
Configures the EclipseModel
added by the eclipse plugin.
- Delegates to:
EclipseModel
fromeclipse
Configures the FindBugsExtension
added by the findbugs plugin.
- Delegates to:
FindBugsExtension
fromfindbugs
Configures the JacocoPluginExtension
added by the jacoco plugin.
- Delegates to:
JacocoPluginExtension
fromjacoco
Configures the ReportingExtension
added by the java plugin.
- Delegates to:
ReportingExtension
fromreporting
Configures the source sets of this project.
The given closure is executed to configure the SourceSetContainer
. The SourceSetContainer
is passed to the closure as its delegate.
See the example below how SourceSet
'main' is accessed and how the SourceDirectorySet
'java'
is configured to exclude some package from compilation.
apply plugin: 'java' sourceSets { main { java { exclude 'some/unwanted/package/**' } } }
- Delegates to:
SourceSetContainer
fromsourceSets
Configures the JDependExtension
added by the jdepend plugin.
- Delegates to:
JDependExtension
fromjdepend
Configures the JvmComponentExtension
added by the jvm-component plugin.
- Delegates to:
JvmComponentExtension
fromjvm
Configures the BuildTypeContainer
added by the native-component plugin.
- Delegates to:
BuildTypeContainer
frombuildTypes
Configures the FlavorContainer
added by the native-component plugin.
- Delegates to:
FlavorContainer
fromflavors
Configures the NativeComponentExtension
added by the native-component plugin.
- Delegates to:
NativeComponentExtension
fromnativeCode
Configures the PlatformContainer
added by the native-component plugin.
- Delegates to:
PlatformContainer
fromplatforms
Configures the ToolChainRegistry
added by the native-component plugin.
- Delegates to:
ToolChainRegistry
fromtoolChains
Configures the PublishingExtension
added by the publishing plugin.
- Delegates to:
PublishingExtension
frompublishing
Configures the SigningExtension
added by the signing plugin.
- Delegates to:
SigningExtension
fromsigning
Configures the VisualStudioExtension
added by the visual-studio plugin.
- Delegates to:
VisualStudioExtension
fromvisualStudio