# Project

interface Project : Comparable<Project> , ExtensionAware, PluginAware(source)

This interface is the main API you use to interact with Gradle from your build file. From a `Project`, you have programmatic access to all of Gradle's features.

## Lifecycle

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

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

## Tasks

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

## Dependencies

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

## Multi-project Builds

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

## Plugins

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

## Dynamic Project Properties

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

For example:

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

Content copied to clipboard

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

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

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

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

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

### Extra Properties

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

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

Content copied to clipboard
Reading extra properties is done through the "ext" or through the owning object.

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

Content copied to clipboard

### Dynamic Methods

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

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

## Properties

DEFAULT_BUILD_DIR_NAME
Link copied to clipboard
val DEFAULT_BUILD_DIR_NAME: String = "build"
The default build directory name.
DEFAULT_BUILD_FILE
Link copied to clipboard
val DEFAULT_BUILD_FILE: String = "build.gradle"
The default project build file name.
DEFAULT_STATUS
Link copied to clipboard
val DEFAULT_STATUS: String = "release"
DEFAULT_VERSION
Link copied to clipboard
val DEFAULT_VERSION: String = "unspecified"
GRADLE_PROPERTIES
Link copied to clipboard
val GRADLE_PROPERTIES: String = "gradle.properties"
PATH_SEPARATOR
Link copied to clipboard
val PATH_SEPARATOR: String = ":"
The hierarchy separator for project and task path names.
SYSTEM_PROP_PREFIX
Link copied to clipboard
val SYSTEM_PROP_PREFIX: String = "systemProp"

## Functions

absoluteProjectPath
Link copied to clipboard
abstract fun absoluteProjectPath(path: String): String
Converts a name to an absolute project path, resolving names relative to this project.
afterEvaluate
Link copied to clipboard
abstract fun afterEvaluate(@DelegatesTo(value = Project::class) closure: Closure)
Adds a closure to call immediately after this project is evaluated.
abstract fun afterEvaluate(action: Action<in Project>)
Adds an action to call immediately after this project is evaluated.
allprojects
Link copied to clipboard
abstract fun allprojects(@DelegatesTo(value = Project::class) configureClosure: Closure)
abstract fun allprojects(action: Action<in Project>)
Configures this project and each of its sub-projects.
ant
Link copied to clipboard
abstract fun ant(@DelegatesTo(value = AntBuilder::class) configureClosure: Closure): AntBuilder
Executes the given closure against the `AntBuilder` for this project.
abstract fun ant(configureAction: Action<in AntBuilder>): AntBuilder
Executes the given action against the `AntBuilder` for this project.
apply
Link copied to clipboard
abstract fun apply(@DelegatesTo(value = ObjectConfigurationAction::class) closure: Closure)
abstract fun apply(action: Action<in ObjectConfigurationAction>)
Applies zero or more plugins or scripts.
abstract fun apply(options: Map<String, out Any>)
Applies a plugin or script, using the given options provided as a map.
artifacts
Link copied to clipboard
abstract fun artifacts(@DelegatesTo(value = ArtifactHandler::class) configureClosure: Closure)
abstract fun artifacts(configureAction: Action<in ArtifactHandler>)
Configures the published artifacts for this project.
beforeEvaluate
Link copied to clipboard
abstract fun beforeEvaluate(@DelegatesTo(value = Project::class) closure: Closure)
Adds a closure to call immediately before this project is evaluated.
abstract fun beforeEvaluate(action: Action<in Project>)
Adds an action to call immediately before this project is evaluated.
buildscript
Link copied to clipboard
abstract fun buildscript(configureClosure: Closure)
Configures the build script classpath for this project.
compareTo
Link copied to clipboard
abstract fun compareTo(p: T): Int
components
Link copied to clipboard
@Incubating
abstract fun components(configuration: Action<in SoftwareComponentContainer>)
Configures software components.
configurations
Link copied to clipboard
abstract fun configurations(configureClosure: Closure)
Configures the dependency configurations for this project.
configure
Link copied to clipboard
abstract fun configure(objects: Iterable<out Any>, configureClosure: Closure): Iterable<out Any>
Configures a collection of objects via a closure.
abstract fun <T> configure(objects: Iterable<T>, configureAction: Action<in T>): Iterable<T>
Configures a collection of objects via an action.
abstract fun configure(object: Any, configureClosure: Closure): Any
Configures an object via a closure, with the closure's delegate set to the supplied object.
container
Link copied to clipboard
abstract fun <T> container(type: Class<T>): NamedDomainObjectContainer<T>
abstract fun <T> container(type: Class<T>, factoryClosure: Closure): NamedDomainObjectContainer<T>
abstract fun <T> container(type: Class<T>, factory: NamedDomainObjectFactory<T>): NamedDomainObjectContainer<T>
Creates a container for managing named objects of the specified type.
copy
Link copied to clipboard
abstract fun copy(@DelegatesTo(value = CopySpec::class) closure: Closure): WorkResult
abstract fun copy(action: Action<in CopySpec>): WorkResult
Copies the specified files.
copySpec
Link copied to clipboard
abstract fun copySpec(): CopySpec
abstract fun copySpec(@DelegatesTo(value = CopySpec::class) closure: Closure): CopySpec
abstract fun copySpec(action: Action<in CopySpec>): CopySpec
Creates a CopySpec which can later be used to copy files or create an archive.
createAntBuilder
Link copied to clipboard
abstract fun createAntBuilder(): AntBuilder
Creates an additional `AntBuilder` for this project.
defaultTasks
Link copied to clipboard
abstract fun defaultTasks(defaultTasks: Array<String>)
Sets the names of the default tasks of this project.
delete
Link copied to clipboard
abstract fun delete(@Nullable paths: Array<@Nullable Any>): Boolean
Deletes files and directories.
abstract fun delete(action: Action<in DeleteSpec>): WorkResult
Deletes the specified files.
dependencies
Link copied to clipboard
abstract fun dependencies(configureClosure: Closure)
Configures the dependencies for this project.
dependencyLocking
Link copied to clipboard
abstract fun dependencyLocking(configuration: Action<in DependencyLockingHandler>)
Configures dependency locking
depthCompare
Link copied to clipboard
abstract fun depthCompare(otherProject: Project): Int
Compares the nesting level of this project with another project of the multi-project hierarchy.
evaluationDependsOn
Link copied to clipboard
abstract fun evaluationDependsOn(path: String): Project
Declares that this project has an evaluation dependency on the project with the given path.
evaluationDependsOnChildren
Link copied to clipboard
abstract fun evaluationDependsOnChildren()
Declares that this project has an evaluation dependency on each of its child projects.
file
Link copied to clipboard
abstract fun file(path: Any): File
Resolves a file path relative to the project directory of this project.
abstract fun file(path: Any, validation: PathValidation): File
Resolves a file path relative to the project directory of this project and validates it using the given scheme.
files
Link copied to clipboard
abstract fun files(@Nullable paths: Array<@Nullable Any>): ConfigurableFileCollection
Returns a ConfigurableFileCollection containing the given files.
abstract fun files(paths: Any, @DelegatesTo(value = ConfigurableFileCollection::class) configureClosure: Closure): ConfigurableFileCollection
abstract fun files(paths: Any, configureAction: Action<in ConfigurableFileCollection>): ConfigurableFileCollection
Creates a new `ConfigurableFileCollection` using the given paths.
fileTree
Link copied to clipboard
abstract fun fileTree(baseDir: Any): ConfigurableFileTree
abstract fun fileTree(baseDir: Any, @DelegatesTo(value = ConfigurableFileTree::class) configureClosure: Closure): ConfigurableFileTree
abstract fun fileTree(baseDir: Any, configureAction: Action<in ConfigurableFileTree>): ConfigurableFileTree
Creates a new `ConfigurableFileTree` using the given base directory.
abstract fun fileTree(args: Map<String, out Any>): ConfigurableFileTree
Creates a new `ConfigurableFileTree` using the provided map of arguments.
findProject
Link copied to clipboard
@Nullable
abstract fun findProject(path: String): @Nullable Project
Locates a project by path.
findProperty
Link copied to clipboard
@Nullable
abstract fun findProperty(propertyName: String): @Nullable Any
Returns the value of the given property or null if not found.
getAllprojects
Link copied to clipboard
abstract fun getAllprojects(): Set<Project>
Returns the set containing this project and its subprojects.
getAllTasks
Link copied to clipboard
abstract fun getAllTasks(recursive: Boolean): Map<Project, Set<Task>>
Returns a map of the tasks contained in this project, and optionally its subprojects.
getAnt
Link copied to clipboard
abstract fun getAnt(): AntBuilder
Returns the `AntBuilder` for this project.
getArtifacts
Link copied to clipboard
abstract fun getArtifacts(): ArtifactHandler
Returns a handler for assigning artifacts produced by the project to configurations.
getBuildDir
Link copied to clipboard
abstract fun getBuildDir(): File
Returns the build directory of this project.
getBuildFile
Link copied to clipboard
abstract fun getBuildFile(): File
The build script for this project.
getBuildscript
Link copied to clipboard
abstract fun getBuildscript(): ScriptHandler
Returns the build script handler for this project.
getBuildTreePath
Link copied to clipboard
@Incubating
abstract fun getBuildTreePath(): String
Returns a path to the project for the full build tree.
getChildProjects
Link copied to clipboard
abstract fun getChildProjects(): Map<String, Project>
Returns the direct children of this project.
getComponents
Link copied to clipboard
abstract fun getComponents(): SoftwareComponentContainer
Returns the software components produced by this project.
getConfigurations
Link copied to clipboard
abstract fun getConfigurations(): ConfigurationContainer
Returns the configurations of this project.
getDefaultTasks
Link copied to clipboard
abstract fun getDefaultTasks(): List<String>
Returns the names of the default tasks of this project.
getDependencies
Link copied to clipboard
abstract fun getDependencies(): DependencyHandler
Returns the dependency handler of this project.
getDependencyFactory
Link copied to clipboard
abstract fun getDependencyFactory(): DependencyFactory
Provides access to methods to create various kinds of Dependency instances.
getDependencyLocking
Link copied to clipboard
abstract fun getDependencyLocking(): DependencyLockingHandler
Provides access to configuring dependency locking
getDepth
Link copied to clipboard
abstract fun getDepth(): Int
Returns the nesting level of a project in a multi-project hierarchy.
getDescription
Link copied to clipboard
@Nullable
abstract fun getDescription(): @Nullable String
Returns the description of this project, if any.
getDisplayName
Link copied to clipboard
abstract fun getDisplayName(): String
Returns a human-consumable display name for this project.
getExtensions
Link copied to clipboard
abstract fun getExtensions(): ExtensionContainer
Allows adding DSL extensions to the project.
getGradle
Link copied to clipboard
abstract fun getGradle(): Gradle
Returns the org.gradle.api.invocation.Gradle invocation which this project belongs to.
getGroup
Link copied to clipboard
abstract fun getGroup(): Any
Returns the group of this project.
getIsolated
Link copied to clipboard
@Incubating
abstract fun getIsolated(): IsolatedProject
Returns an immutable view of this project, safe for use with isolated projects.
getLayout
Link copied to clipboard
abstract fun getLayout(): ProjectLayout
Provides access to various important directories for this project.
getLogger
Link copied to clipboard
abstract fun getLogger(): Logger
Returns the logger for this project.
getLogging
Link copied to clipboard
abstract fun getLogging(): LoggingManager
Returns the org.gradle.api.logging.LoggingManager which can be used to receive logging and to control the standard output/error capture for this project's build script.
getName
Link copied to clipboard
abstract fun getName(): String
Returns the name of this project.
getNormalization
Link copied to clipboard
abstract fun getNormalization(): InputNormalizationHandler
Provides access to configuring input normalization.
getObjects
Link copied to clipboard
abstract fun getObjects(): ObjectFactory
Provides access to methods to create various kinds of model objects.
getParent
Link copied to clipboard
@Nullable
abstract fun getParent(): @Nullable Project
Returns the parent project of this project, if any.
getPath
Link copied to clipboard
abstract fun getPath(): String
Returns the path of this project, starting with ':'.
getPluginManager
Link copied to clipboard
abstract fun getPluginManager(): PluginManager
The plugin manager for this plugin aware object.
getPlugins
Link copied to clipboard
abstract fun getPlugins(): PluginContainer
The container of plugins that have been applied to this object.
getProject
Link copied to clipboard
abstract fun getProject(): Project
Returns this project.
getProjectDir
Link copied to clipboard
abstract fun getProjectDir(): File
The directory containing the project build file.
getProperties
Link copied to clipboard
abstract fun getProperties(): Map<String, out @Nullable Any>
Returns the properties of this project.
getProviders
Link copied to clipboard
abstract fun getProviders(): ProviderFactory
Provides access to methods to create various kinds of Provider instances.
getRepositories
Link copied to clipboard
abstract fun getRepositories(): RepositoryHandler
Returns a handler to create repositories which are used for retrieving dependencies and uploading artifacts produced by the project.
getResources
Link copied to clipboard
abstract fun getResources(): ResourceHandler
Provides access to resource-specific utility methods, for example factory methods that create various resources.
getRootDir
Link copied to clipboard
abstract fun getRootDir(): File
Returns the root directory of this project.
getRootProject
Link copied to clipboard
abstract fun getRootProject(): Project
Returns the root project for the hierarchy that this project belongs to.
getState
Link copied to clipboard
abstract fun getState(): ProjectState
Returns the evaluation state of this project.
getStatus
Link copied to clipboard
abstract fun getStatus(): Any
Returns the status of this project.
getSubprojects
Link copied to clipboard
abstract fun getSubprojects(): Set<Project>
Returns the set containing the subprojects of this project.
getTasks
Link copied to clipboard
abstract fun getTasks(): TaskContainer
Returns the tasks of this project.
getTasksByName
Link copied to clipboard
abstract fun getTasksByName(name: String, recursive: Boolean): Set<Task>
Returns the set of tasks with the given name contained in this project, and optionally its subprojects.
getVersion
Link copied to clipboard
abstract fun getVersion(): Any
Returns the version of this project.
hasProperty
Link copied to clipboard
abstract fun hasProperty(propertyName: String): Boolean
Determines if this project has the given property.
mkdir
Link copied to clipboard
abstract fun mkdir(path: Any): File
Creates a directory and returns a file pointing to it.
normalization
Link copied to clipboard
abstract fun normalization(configuration: Action<in InputNormalizationHandler>)
Configures input normalization.
project
Link copied to clipboard
abstract fun project(path: String): Project
Locates a project by path.
abstract fun project(path: String, @DelegatesTo(value = Project::class) configureClosure: Closure): Project
Locates a project by path and configures it using the given closure.
abstract fun project(path: String, configureAction: Action<in Project>): Project
Locates a project by path and configures it using the given action.
property
Link copied to clipboard
@Nullable
abstract fun property(propertyName: String): @Nullable Any
Returns the value of the given property.
provider
Link copied to clipboard
abstract fun <T> provider(value: Callable<out @Nullable T>): Provider<T>
Creates a Provider implementation based on the provided value.
relativePath
Link copied to clipboard
abstract fun relativePath(path: Any): String
Returns the relative path from the project directory to the given path.
relativeProjectPath
Link copied to clipboard
abstract fun relativeProjectPath(path: String): String
Converts a name to a project path relative to this project.
repositories
Link copied to clipboard
abstract fun repositories(configureClosure: Closure)
Configures the repositories for this project.
setBuildDir
Link copied to clipboard
abstract fun setBuildDir(path: File)
abstract fun setBuildDir(path: Any)
Sets the build directory of this project.
setDefaultTasks
Link copied to clipboard
abstract fun setDefaultTasks(defaultTasks: List<String>)
Sets the names of the default tasks of this project.
setDescription
Link copied to clipboard
abstract fun setDescription(@Nullable description: @Nullable String)
Sets a description for this project.
setGroup
Link copied to clipboard
abstract fun setGroup(group: Any)
Sets the group of this project.
setProperty
Link copied to clipboard
abstract fun setProperty(name: String, @Nullable value: @Nullable Any)
Sets a property of this project.
setStatus
Link copied to clipboard
abstract fun setStatus(status: Any)
Sets the status of this project.
setVersion
Link copied to clipboard
abstract fun setVersion(version: Any)
Sets the version of this project.
subprojects
Link copied to clipboard
abstract fun subprojects(@DelegatesTo(value = Project::class) configureClosure: Closure)
Configures the sub-projects of this project.
abstract fun subprojects(action: Action<in Project>)
Configures the sub-projects of this projectThis method executes the given Action against the sub-projects of this project.
sync
Link copied to clipboard
abstract fun sync(action: Action<in SyncSpec>): WorkResult
Synchronizes the contents of a destination directory with some source directories and files.
tarTree
Link copied to clipboard
abstract fun tarTree(tarPath: Any): FileTree
Creates a new `FileTree` which contains the contents of the given TAR file.
task
Link copied to clipboard
abstract fun task(name: String): Task
abstract fun task(name: String, @DelegatesTo(value = Task::class) configureClosure: Closure): Task
abstract fun task(name: String, configureAction: Action<in Task>): Task
abstract fun task(args: Map<String, out Any>, name: String): Task
abstract fun task(args: Map<String, out Any>, name: String, configureClosure: Closure): Task
Creates a Task with the given name and adds it to this project.
uri
Link copied to clipboard
abstract fun uri(path: Any): URI
Resolves a file path to a URI, relative to the project directory of this project.
zipTree
Link copied to clipboard
abstract fun zipTree(zipPath: Any): FileTree
Creates a new `FileTree` which contains the contents of the given ZIP file.