Project

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 set containing this project and its subprojects.

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 a handler for assigning artifacts produced by the project to configurations.

Examples: See docs for ArtifactHandler

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

The build script for this project.

If the file exists, it will be evaluated against this project when this project is configured.

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

The direct children of this project.

The configurations of this project.

Examples: See docs for ConfigurationContainer

The Convention for this project.

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

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

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

Provides access to configuring dependency locking

The description of this project, if any.

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

The Gradle invocation which this project belongs to.

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

Provides access to various important directories for this project.

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

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

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. If the root project is unnamed and is located on a file system root it will have a randomly-generated name

Provides access to configuring input normalization.

The parent project of this project, if any.

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

The plugin manager for this plugin aware object.

The container of plugins that have been applied to this object.

While not deprecated, it is preferred to use the methods of this interface or the PluginAware.getPluginManager() than use the plugin container.

Use one of the 'apply' methods on this interface or on the PluginAware.getPluginManager() to apply plugins instead of applying via the plugin container.

Use PluginManager.hasPlugin(java.lang.String) or similar to query for the application of plugins instead of doing so via the plugin container.

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.

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.

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

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

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

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

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.

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.

The set containing the subprojects of this project.

The tasks of this project.

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

The JavaApplication added by the application plugin.

Array of string arguments to pass to the JVM when running the application

The specification of the contents of the distribution.

Use this CopySpec to include extra files/resource in the application distribution.

plugins {
    id 'application'
}

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.

The name of the application.

Directory to place executables in

The fully qualified name of the application's main class.

The CheckstyleExtension added by the checkstyle plugin.

The CodeNarcExtension added by the codenarc plugin.

The DistributionContainer added by the distribution plugin.

The name of the application directory, relative to the project directory. Default is "src/main/application".

A custom deployment descriptor configuration. Default is an "application.xml" with sensible defaults.

Specifies if the deploymentDescriptor should be generated if it does not exist. Default is true.

The name of the library directory in the EAR file. Default is "lib".

The EclipseModel added by the eclipse plugin.

The IdeaModel added by the idea plugin.

The JacocoPluginExtension added by the jacoco plugin.

The base name to use for archive files.

The BasePluginExtension added by the java plugin.

The name for the distributions directory. This in interpreted relative to the project' build directory.

The directory to generate TAR and ZIP archives into.

Returns a file pointing to the root directory supposed to be used for all docs.

The name of the docs directory. Can be a name or a path relative to the build dir.

The JavaPluginExtension added by the java plugin.

The name for the libs directory. This in interpreted relative to the project' build directory.

The directory to generate JAR and WAR archives into.

The ReportingExtension added by the java plugin.

The source compatibility used for compiling Java sources.

The source sets container.

The target compatibility used for compiling Java sources.

Returns a file pointing to the root directory to be used for reports.

The name of the test reports directory. Can be a name or a path relative to ReportingExtension.getBaseDir().

Returns a file pointing to the root directory of the test results.

The name of the test results directory. Can be a name or a path relative to the build dir.

The PmdExtension added by the pmd plugin.

The directory to generate the project reports into.

The name of the directory to generate the project reports into, relative to the project's reports dir.

The PublishingExtension added by the publishing plugin.

The SigningExtension added by the signing plugin.

The VisualStudioRootExtension added by the visual-studio plugin.

The web application directory.

The name of the web application directory, relative to the project directory.

The XcodeRootExtension added by the xcode plugin.

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

Adds a closure to call immediately after this project is evaluated.

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

Passes the project to the action as a parameter. Actions passed to this method execute in the same order they were passed. A parent project may add an action to its child projects to further configure those projects based on their state after their build files run.

If the project has already been evaluated, this method fails.

If you call this method within an afterEvaluate action, the passed action executes after all previously added afterEvaluate actions finish executing.

Configures this project and each of its sub-projects.

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

Executes the given action against the AntBuilder for this project. You can use this in your build file to execute ant tasks. See example in javadoc for Project.getAnt()

Applies zero or more plugins or scripts.

The given closure is used to configure an ObjectConfigurationAction, which “builds” the plugin application.

This method differs from PluginAware.apply(java.util.Map) in that it allows methods of the configuration action to be invoked more than once.

Applies a plugin or script, using the given options provided as a map. Does nothing if the plugin has already been applied.

The given map is applied as a series of method calls to a newly created ObjectConfigurationAction. That is, each key in the map is expected to be the name of a method ObjectConfigurationAction and the value to be compatible arguments to that method.

The following options are available:

Applies zero or more plugins or scripts.

The given closure is used to configure an ObjectConfigurationAction, which “builds” the plugin application.

This method differs from PluginAware.apply(java.util.Map) in that it allows methods of the configuration action to be invoked more than once.

Configures the published artifacts for this project.

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

Example:

configurations {
  //declaring new configuration that will be used to associate with artifacts
  schema
}

task schemaJar(type: Jar) {
  //some imaginary task that creates a jar artifact with the schema
}

//associating the task that produces the artifact with the configuration
artifacts {
  //configuration name and the task:
  schema schemaJar
}

Adds a closure to call immediately before this project is evaluated.

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

Passes the project to the action as a parameter. Actions passed to this method execute in the same order they were passed.

If the project has already been evaluated, the action never executes.

If you call this method within a beforeEvaluate action, the passed action never executes.

Configures a collection of objects via a closure. This is equivalent to calling Project.configure(java.lang.Object, groovy.lang.Closure) 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() }

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.

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.

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.

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

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

Creates a CopySpec which can later be used to copy files or create an archive.

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.

def baseSpec = copySpec {
   from "source"
   include "**/*.java"
}

task copy(type: Copy) {
   into "target"
   with baseSpec
}

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

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

Deletes files and directories.

This will not follow symlinks. If you need to follow symlinks too use Project.delete(org.gradle.api.Action).

Deletes the specified files. The given action is used to configure a DeleteSpec, which is then used to delete the files.

Example:

project.delete {
    delete 'somefile'
    followSymlinks = true
}

Configures dependency locking

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

Executes an external command. The closure configures a ExecSpec.

Executes an external command.

The given action configures a ExecSpec, which is used to launch the process. This method blocks until the process terminates, with its result being returned.

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

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.

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

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

def myTree = fileTree("src")
myTree.include "**/*.java"
myTree.builtBy "someTask"

task copy(type: Copy) {
   from myTree
}

The order of the files in a FileTree is not stable, even on a single computer.

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

def myTree = fileTree('src') {
   exclude '**/.data/**'
   builtBy 'someTask'
}

task copy(type: Copy) {
   from myTree
}

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

The order of the files in a FileTree is not stable, even on a single computer.

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

def myTree = fileTree('src') {
   exclude '**/.data/**'
   builtBy 'someTask'
}

task copy(type: Copy) {
   from myTree
}

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

The order of the files in a FileTree is not stable, even on a single computer.

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

def myTree = fileTree(dir:'src', excludes:['**/ignore/**', '**/.data/**'])

task copy(type: Copy) {
    from myTree
}

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

The order of the files in a FileTree is not stable, even on a single computer.

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

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

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

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

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

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

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

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

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

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

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

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

Returns the value of the given property or null if not found. This method locates a property as follows:

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. NOTE: This is an expensive operation since it requires all projects to be configured.

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

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

Executes an external Java process.

The given action configures a JavaExecSpec, which is used to launch the process. This method blocks until the process terminates, with its result being returned.

Creates a directory and returns a file pointing to it.

Configures input normalization.

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.

Locates a project by path and configures it using the given action. If the path is relative, it is interpreted relative to this project.

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

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

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

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.

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.

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

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

Example:

project.sync {
   from 'my/shared/dependencyDir'
   into 'build/deps/compile'
}

Note that you can preserve output that already exists in the destination directory:

project.sync {
    from 'source'
    into 'dest'
    preserve {
        include 'extraDir/**'
        include 'dir1/**'
        exclude 'dir1/extra.txt'
    }
}

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

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(org.gradle.api.Action) 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(java.util.Map, java.lang.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 properties 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. Before the task is returned, the given action 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:

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(java.util.Map, java.lang.String) for the available options.

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

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

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

Creates a new FileTree which contains the contents of the given ZIP file. The given zipPath path is evaluated as per Project.file(java.lang.Object). You can combine this method with the Project.copy(org.gradle.api.Action) 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.

Allows changing the application directory. Default is "src/main/application".

Configures the deployment descriptor for this EAR archive.

The given action is executed to configure the deployment descriptor.

Allows changing the library directory in the EAR file. Default is "lib".

Creates a new instance of a Manifest.

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 instance of a Manifest.

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.

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

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
}

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.

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

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

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.

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.

Configures the JavaApplication added by the application plugin.

Configures the CheckstyleExtension added by the checkstyle plugin.

Configures the CodeNarcExtension added by the codenarc plugin.

Configures the DistributionContainer added by the distribution plugin.

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.

Configures the EclipseModel added by the eclipse plugin.

Configures the IdeaModel added by the idea plugin.

Configures the JacocoPluginExtension added by the jacoco plugin.

Configures the BasePluginExtension added by the java plugin.

Configures the JavaPluginExtension added by the java plugin.

Configures the ReportingExtension added by the java plugin.

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.

plugins {
    id 'java'
}

sourceSets {
  main {
    java {
      exclude 'some/unwanted/package/**'
    }
  }
}

Configures the PmdExtension added by the pmd plugin.

Configures the PublishingExtension added by the publishing plugin.

Configures the SigningExtension added by the signing plugin.

Configures the VisualStudioRootExtension added by the visual-studio plugin.

Configures the XcodeRootExtension added by the xcode plugin.