api / org.gradle.api.artifacts / Configuration

Configuration

interface Configuration : FileCollection, HasConfigurableAttributes<Configuration>

A Configuration represents a group of artifacts and their dependencies. Find more information about declaring dependencies to a configuration or about managing configurations in docs for ConfigurationContainer

Configuration is an instance of a FileCollection that contains all dependencies (see also #getAllDependencies()) but not artifacts. If you want to refer to the artifacts declared in this configuration please use #getArtifacts() or #getAllArtifacts(). Read more about declaring artifacts in the configuration in docs for org.gradle.api.artifacts.dsl.ArtifactHandler Please see the Managing Dependency Configurations User Guide chapter for more information.

Types

Namer

open class Namer : Namer<Configuration>

A org.gradle.api.Namer namer for configurations that returns #getName().

State

class State

The states a configuration can be into. A configuration is only mutable as long as it is in the unresolved state.

Functions

copy

abstract fun copy(): Configuration

Creates a copy of this configuration that only contains the dependencies directly in this configuration (without contributions from superconfigurations). The new configuration will be in the UNRESOLVED state, but will retain all other attributes of this configuration except superconfigurations. #getHierarchy() for the copy will not include any superconfigurations.

abstract fun copy(dependencySpec: Spec<in Dependency>): Configuration

Creates a copy of this configuration ignoring superconfigurations (see #copy() but filtering the dependencies using the specified dependency spec.

abstract fun copy(dependencySpec: Closure<Any>): Configuration

Takes a closure which gets coerced into a Spec. Behaves otherwise in the same way as #copy(org.gradle.api.specs.Spec)

copyRecursive

abstract fun copyRecursive(): Configuration

Creates a copy of this configuration that contains the dependencies directly in this configuration and those derived from superconfigurations. The new configuration will be in the UNRESOLVED state, but will retain all other attributes of this configuration except superconfigurations. #getHierarchy() for the copy will not include any superconfigurations.

abstract fun copyRecursive(dependencySpec: Spec<in Dependency>): Configuration

Creates a copy of this configuration with dependencies from superconfigurations (see #copyRecursive()) but filtering the dependencies using the dependencySpec.

abstract fun copyRecursive(dependencySpec: Closure<Any>): Configuration

Takes a closure which gets coerced into a Spec. Behaves otherwise in the same way as #copyRecursive(org.gradle.api.specs.Spec)

defaultDependencies

abstract fun defaultDependencies(action: Action<in DependencySet>): Configuration

Execute the given action if the configuration has no defined dependencies when it first participates in dependency resolution. A Configuration will participate in dependency resolution when:

  • The Configuration itself is resolved
  • Another Configuration that extends this one is resolved
  • Another Configuration that references this one as a project dependency is resolved
This method is useful for specifying default dependencies for a configuration:
 configurations { conf } configurations['conf'].defaultDependencies { dependencies -> dependencies.add(owner.project.dependencies.create("org.gradle:my-util:1.0")) } 
A Configuration is considered empty even if it extends another, non-empty Configuration. If multiple actions are supplied, each action will be executed until the set of dependencies is no longer empty. Remaining actions will be ignored.

exclude

abstract fun exclude(excludeProperties: MutableMap<String, String>): Configuration

Adds an exclude rule to exclude transitive dependencies for all dependencies of this configuration. You can also add exclude rules per-dependency. See ModuleDependency#exclude(java.util.Map).

extendsFrom

abstract fun extendsFrom(vararg superConfigs: Configuration): Configuration

Adds the given configurations to the set of configuration which this configuration extends from.

fileCollection

abstract fun fileCollection(dependencySpec: Spec<in Dependency>): FileCollection

Resolves this configuration lazily. The resolve happens when the elements of the returned FileCollection get accessed the first time. This locates and downloads the files which make up this configuration. Only the resulting set of files belonging to the subset of dependencies specified by the dependencySpec is contained in the FileCollection.

abstract fun fileCollection(dependencySpecClosure: Closure<Any>): FileCollection

Takes a closure which gets coerced into a Spec. Behaves otherwise in the same way as #fileCollection(org.gradle.api.specs.Spec).

abstract fun fileCollection(vararg dependencies: Dependency): FileCollection

Resolves this configuration lazily. The resolve happens when the elements of the returned FileCollection get accessed the first time. This locates and downloads the files which make up this configuration. Only the resulting set of files belonging to specified dependencies is contained in the FileCollection.

files

abstract fun files(dependencySpecClosure: Closure<Any>): MutableSet<File>

Takes a closure which gets coerced into a Spec. Behaves otherwise in the same way as #files(org.gradle.api.specs.Spec).

abstract fun files(dependencySpec: Spec<in Dependency>): MutableSet<File>

Resolves this configuration. This locates and downloads the files which make up this configuration. But only the resulting set of files belonging to the subset of dependencies specified by the dependencySpec is returned.

abstract fun files(vararg dependencies: Dependency): MutableSet<File>

Resolves this configuration. This locates and downloads the files which make up this configuration. But only the resulting set of files belonging to the specified dependencies is returned.

getAll

abstract fun getAll(): MutableSet<Configuration>

Returns all the configurations belonging to the same configuration container as this configuration (including this configuration).

getAllArtifacts

abstract fun getAllArtifacts(): PublishArtifactSet

Returns the artifacts of this configuration including the artifacts of extended configurations.

getAllDependencies

abstract fun getAllDependencies(): DependencySet

Gets the complete set of declared dependencies including those contributed by superconfigurations.

This method does not resolve the configuration. Therefore, the return value does not include transitive dependencies.

getAllDependencyConstraints

abstract fun getAllDependencyConstraints(): DependencyConstraintSet

Gets the complete set of dependency constraints including those contributed by superconfigurations.

getArtifacts

abstract fun getArtifacts(): PublishArtifactSet

Returns the artifacts of this configuration excluding the artifacts of extended configurations.

getBuildDependencies

abstract fun getBuildDependencies(): TaskDependency

Returns a TaskDependency object containing all required dependencies to build the local dependencies (e.g. project dependencies) belonging to this configuration or to one of its super configurations.

getDependencies

abstract fun getDependencies(): DependencySet

Gets the set of declared dependencies directly contained in this configuration (ignoring superconfigurations).

This method does not resolve the configuration. Therefore, the return value does not include transitive dependencies.

getDependencyConstraints

abstract fun getDependencyConstraints(): DependencyConstraintSet

Gets the set of dependency constraints directly contained in this configuration (ignoring superconfigurations).

getDescription

abstract fun getDescription(): String

Returns the description for this configuration.

getExcludeRules

abstract fun getExcludeRules(): MutableSet<ExcludeRule>

Returns the exclude rules applied for resolving any dependency of this configuration.

getExtendsFrom

abstract fun getExtendsFrom(): MutableSet<Configuration>

Returns the names of the configurations which this configuration extends from. The artifacts of the super configurations are also available in this configuration.

getHierarchy

abstract fun getHierarchy(): MutableSet<Configuration>

Gets a ordered set including this configuration and all superconfigurations recursively.

getIncoming

abstract fun getIncoming(): ResolvableDependencies

Returns the incoming dependencies of this configuration.

getName

abstract fun getName(): String

Returns the name of this configuration.

getOutgoing

abstract fun getOutgoing(): ConfigurationPublications

Returns the outgoing artifacts of this configuration.

getResolutionStrategy

abstract fun getResolutionStrategy(): ResolutionStrategy

Returns the resolution strategy used by this configuration. The resolution strategy provides extra details on how to resolve this configuration. See docs for ResolutionStrategy for more info and examples.

getResolvedConfiguration

abstract fun getResolvedConfiguration(): ResolvedConfiguration

Resolves this configuration. This locates and downloads the files which make up this configuration, and returns a ResolvedConfiguration that may be used to determine information about the resolve (including errors).

getState

abstract fun getState(): State

Returns the state of the configuration.

getTaskDependencyFromProjectDependency

abstract fun getTaskDependencyFromProjectDependency(useDependedOn: Boolean, taskName: String): TaskDependency

Returns a TaskDependency object containing dependencies on all tasks with the specified name from project dependencies related to this configuration or one of its super configurations. These other projects may be projects this configuration depends on or projects with a similarly named configuration that depend on this one based on the useDependOn argument.

getUploadTaskName

abstract fun getUploadTaskName(): String

Returns the name of the task that upload the artifacts of this configuration to repositories declared by the user.

isCanBeConsumed

abstract fun isCanBeConsumed(): Boolean

Returns true if this configuration can be consumed from another project, or published. Defaults to true.

isCanBeResolved

abstract fun isCanBeResolved(): Boolean

Returns true if it is allowed to query or resolve this configuration. Defaults to true.

isTransitive

abstract fun isTransitive(): Boolean

Returns the transitivity of this configuration. A transitive configuration contains the transitive closure of its direct dependencies, and all their dependencies. An intransitive configuration contains only the direct dependencies. The default value is true.

isVisible

abstract fun isVisible(): Boolean

Returns true if this is a visible configuration. A visible configuration is usable outside the project it belongs to. The default value is true.

outgoing

abstract fun outgoing(action: Action<in ConfigurationPublications>): Unit

Configures the outgoing artifacts of this configuration.

resolutionStrategy

abstract fun resolutionStrategy(closure: Closure<Any>): Configuration
abstract fun resolutionStrategy(action: Action<in ResolutionStrategy>): Configuration

The resolution strategy provides extra details on how to resolve this configuration. See docs for ResolutionStrategy for more info and examples.

resolve

abstract fun resolve(): MutableSet<File>

Resolves this configuration. This locates and downloads the files which make up this configuration, and returns the resulting set of files.

setCanBeConsumed

abstract fun setCanBeConsumed(allowed: Boolean): Unit

Configures if a configuration can be consumed.

setCanBeResolved

abstract fun setCanBeResolved(allowed: Boolean): Unit

Configures if a configuration can be resolved.

setDescription

abstract fun setDescription(description: String): Configuration

Sets the description for this configuration.

setExtendsFrom

abstract fun setExtendsFrom(superConfigs: MutableIterable<Configuration>): Configuration

Sets the configurations which this configuration extends from.

setTransitive

abstract fun setTransitive(t: Boolean): Configuration

Sets the transitivity of this configuration. When set to true, this configuration will contain the transitive closure of its dependencies and their dependencies. The default value is true.

setVisible

abstract fun setVisible(visible: Boolean): Configuration

Sets the visibility of this configuration. When visible is set to true, this configuration is visible outside the project it belongs to. The default value is true.

withDependencies

abstract fun withDependencies(action: Action<in DependencySet>): Configuration

Execute the given action before the configuration first participates in dependency resolution. A Configuration will participate in dependency resolution when:

  • The Configuration itself is resolved
  • Another Configuration that extends this one is resolved
  • Another Configuration that references this one as a project dependency is resolved
This method is useful for mutating the dependencies for a configuration:
 configurations { conf } configurations['conf'].withDependencies { dependencies -> dependencies.each { dependency -> if (dependency.version == null) { dependency.version { prefer '1.0' } } } } 
Actions will be executed in the order provided.

Inherited Functions

add

abstract fun add(collection: FileCollection): FileCollection

Adds another collection to this collection. This is an optional operation.

addToAntBuilder

abstract fun addToAntBuilder(builder: Any, nodeName: String, type: AntType): Unit

Adds this collection to an Ant task as a nested node. The given type determines how this collection is added:

  • AntType#MatchingTask: adds this collection to an Ant MatchingTask. The collection is converted to a set of source directories and include and exclude patterns. The source directories as added as an Ant Path with the given node name. The patterns are added using 'include' and 'exclude' nodes.
  • AntType#FileSet: adds this collection as zero or more Ant FileSets with the given node name.
  • AntType#ResourceCollection: adds this collection as zero or more Ant ResourceCollections with the given node name.
You should prefer using AntType#ResourceCollection, if the target Ant task supports it, as this is generally the most efficient. Using the other types may involve copying the contents of this collection to a temporary directory.

abstract fun addToAntBuilder(builder: Any, nodeName: String): Any

Adds this collection to an Ant task as a nested node. Equivalent to calling addToAntBuilder(builder, nodeName,AntType.ResourceCollection).

asType

abstract fun asType(type: Class<*>): Any

Converts this collection into an object of the specified type. Supported types are: Collection, List, Set, Object[], File[], File, and FileTree.

You can call this method in your build script using the as operator.

attributes

abstract fun attributes(action: Action<in AttributeContainer>): SELF

Configure the attribute container that provides the attributes associated with this domain object.

contains

abstract fun contains(file: File): Boolean

Determines whether this collection contains the given file. Generally, this method is more efficient than calling getFiles().contains(file).

filter

abstract fun filter(filterClosure: Closure<Any>): FileCollection

Restricts the contents of this collection to those files which match the given criteria. The filtered collection is live, so that it reflects any changes to this collection.

The given closure is passed the File as a parameter, and should return a boolean value.

abstract fun filter(filterSpec: Spec<in File>): FileCollection

Restricts the contents of this collection to those files which match the given criteria. The filtered collection is live, so that it reflects any changes to this collection.

getAsFileTree

abstract fun getAsFileTree(): FileTree

Converts this collection to a FileTree. Generally, for each file in this collection, the resulting file tree will contain the source file at the root of the tree. For each directory in this collection, the resulting file tree will contain all the files under the source directory.

getAsPath

abstract fun getAsPath(): String

Returns the contents of this collection as a platform-specific path. This can be used, for example, in an Ant <path> element.

getFiles

abstract fun getFiles(): MutableSet<File>

Returns the contents of this collection as a Set.

getSingleFile

abstract fun getSingleFile(): File

Returns the content of this collection, asserting it contains exactly one file.

isEmpty

abstract fun isEmpty(): Boolean

Returns true if this collection is empty. Generally, calling this method is more efficient than calling getFiles().isEmpty().

minus

abstract fun minus(collection: FileCollection): FileCollection

Returns a FileCollection which contains the difference between this collection and the given collection. The returned collection is live, and tracks changes to both source collections.

You can call this method in your build script using the - operator.

plus

abstract fun plus(collection: FileCollection): FileCollection

Returns a FileCollection which contains the union of this collection and the given collection. The returned collection is live, and tracks changes to both source collections.

You can call this method in your build script using the + operator.

stopExecutionIfEmpty

abstract fun stopExecutionIfEmpty(): FileCollection

Throws a StopExecutionException if this collection is empty.

Extension Functions

exclude

fun Configuration.exclude(group: String? = null, module: String? = null): Configuration

Adds an exclude rule to exclude transitive dependencies for all dependencies of this configuration. You can also add exclude rules per-dependency. See ModuleDependency.exclude.