api / org.gradle.api.file / ProjectLayout

ProjectLayout

@Incubating interface ProjectLayout

Provides access to several important locations for a project. An instance of the factory can be injected into a task or plugin by annotating a public constructor or method with javax.inject.Inject. It is also available via org.gradle.api.Project#getLayout().

Since
4.1

Functions

configurableFiles

abstract fun configurableFiles(vararg paths: Any): ConfigurableFileCollection

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

  • A CharSequence, including String or groovy.lang.GString. Interpreted relative to the project directory, as per Project#file(Object). A string that starts with file: is treated as a file URL.
  • A File. Interpreted relative to the project directory, as per Project#file(Object).
  • A java.nio.file.Path as defined by Project#file(Object).
  • A java.net.URI or java.net.URL. The URL's path is interpreted as a file path. Only file: URLs are supported.
  • A org.gradle.api.file.Directory or org.gradle.api.file.RegularFile.
  • A java.util.Collection, Iterable, or an array that contains objects of any supported type. The elements of the collection are recursively converted to files.
  • A org.gradle.api.file.FileCollection. The contents of the collection are included in the returned collection.
  • A Provider of any supported type. The provider's value is recursively converted to files. If the provider represents an output of a task, that task is executed if the file collection is used as an input to another task.
  • A java.util.concurrent.Callable that returns any supported type. The return value of the call() method is recursively converted to files. A null return value is treated as an empty collection.
  • A Closure that returns any of the types listed here. The return value of the closure is recursively converted to files. A null return value is treated as an empty collection.
  • A Task. Converted to the task's output files. The task is executed if the file collection is used as an input to another task.
  • A org.gradle.api.tasks.TaskOutputs. Converted to the output files the related task. The task is executed if the file collection is used as an input to another task.
  • Anything else is treated as a failure.

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

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

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

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

directoryProperty

abstract fun directoryProperty(): DirectoryProperty

Creates a new DirectoryProperty that uses the project directory to resolve paths, if required. The property has no initial value.

abstract fun directoryProperty(initialProvider: Provider<out Directory>): DirectoryProperty

Creates a new DirectoryProperty that uses the project directory to resolve paths, if required. The property has the initial provider specified.

file

abstract fun file(file: Provider<File>): Provider<RegularFile>

Creates a RegularFile provider whose location is calculated from the given Provider.

fileProperty

abstract fun fileProperty(): RegularFileProperty

Creates a new RegularFileProperty that uses the project directory to resolve paths, if required. The property has no initial value.

abstract fun fileProperty(initialProvider: Provider<out RegularFile>): RegularFileProperty

Creates a new RegularFileProperty that uses the project directory to resolve paths, if required. The property has the initial provider specified.

files

abstract fun files(vararg paths: Any): FileCollection

Creates a FileCollection for the given targets. You can pass any of the following types to this method:

  • A CharSequence, including String or groovy.lang.GString. Interpreted relative to the project directory, as per Project#file(Object). A string that starts with file: is treated as a file URL.
  • A File. Interpreted relative to the project directory, as per Project#file(Object).
  • A java.nio.file.Path as defined by Project#file(Object).
  • A java.net.URI or java.net.URL. The URL's path is interpreted as a file path. Only file: URLs are supported.
  • A org.gradle.api.file.Directory or org.gradle.api.file.RegularFile.
  • A java.util.Collection, Iterable, or an array that contains objects of any supported type. The elements of the collection are recursively converted to files.
  • A org.gradle.api.file.FileCollection. The contents of the collection are included in the returned collection.
  • A Provider of any supported type. The provider's value is recursively converted to files. If the provider represents an output of a task, that task is executed if the file collection is used as an input to another task.
  • A java.util.concurrent.Callable that returns any supported type. The return value of the call() method is recursively converted to files. A null return value is treated as an empty collection.
  • A Closure that returns any of the types listed here. The return value of the closure is recursively converted to files. A null return value is treated as an empty collection.
  • A Task. Converted to the task's output files. The task is executed if the file collection is used as an input to another task.
  • A org.gradle.api.tasks.TaskOutputs. Converted to the output files the related task. The task is executed if the file collection is used as an input to another task.
  • Anything else is treated as a failure.

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

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

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

This method can also be used to create an empty collection, but the collection may not be mutated later.

getBuildDirectory

abstract fun getBuildDirectory(): DirectoryProperty

Returns the build directory for the project.

getProjectDirectory

abstract fun getProjectDirectory(): Directory

Returns the project directory.

newDirectoryVar

abstract fun newDirectoryVar(): DirectoryVar

Creates a new DirectoryVar that uses the project directory to resolve paths, if required. The var has no initial value.

newFileVar

abstract fun newFileVar(): RegularFileVar

Creates a new RegularFileVar that uses the project directory to resolve paths, if required. The var has no initial value.