# Configuration

API Documentation: | `Configuration`

Known Subtypes: |
`ConsumableConfiguration`
`ResolvableConfiguration`
`DependencyScopeConfiguration`

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 `Configuration.getAllDependencies()`) but not artifacts. If you want to refer to the artifacts declared in this configuration please use `Configuration.getArtifacts()` or `Configuration.getAllArtifacts()`. Read more about declaring artifacts in the configuration in docs for `ArtifactHandler` Please see the Declaring Dependencies User Manual chapter for more information.

### Properties

Property | Description
`allArtifacts` | The artifacts of this configuration including the artifacts of extended configurations.
`allDependencies` | Gets the complete set of declared dependencies including those contributed by superconfigurations.
`artifacts` | The artifacts of this configuration excluding the artifacts of extended configurations.
`buildDependencies` | 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.
`dependencies` | Gets the set of declared dependencies directly contained in this configuration (ignoring superconfigurations).
`description` | The description for this configuration.
`excludeRules` | The exclude rules applied for resolving any dependency of this configuration.
`extendsFrom` | The names of the configurations which this configuration extends from. The artifacts of the super configurations are also available in this configuration.
`hierarchy` | Gets an ordered set including this configuration and all superconfigurations recursively.
`incoming` | Returns a `ResolvableDependencies` instance, exposing the results of dependency resolution. This method is the primary way to consume dependency resolution outputs.
`resolutionStrategy` | 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.
`resolvedConfiguration` | Returns a `ResolvedConfiguration`, a legacy view of the results of dependency resolution. Avoid this method for new code. Prefer accessing resolution outputs via `Configuration.getIncoming()`. This API will be deprecated and removed in future Gradle versions.
`state` | The state of the configuration.
`transitive` | 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.
`visible` | Deprecated This is a legacy property and the value does not affect dependency resolution in any way. There is no need to read this property and this method will be deprecated in an upcoming Gradle version.

### Methods

Method | Description
`copy()` | 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. `Configuration.getHierarchy()` for the copy will not include any superconfigurations.
`copy(dependencySpec)` | Takes a closure which gets coerced into a `Spec`. Behaves otherwise in the same way as `Configuration.copy(org.gradle.api.specs.Spec)`
`copy(dependencySpec)` | Creates a copy of this configuration ignoring superconfigurations (see `Configuration.copy()` but filtering the dependencies using the specified dependency spec.
`copyRecursive()` | 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. `Configuration.getHierarchy()` for the copy will not include any superconfigurations.
`copyRecursive(dependencySpec)` | Takes a closure which gets coerced into a `Spec`. Behaves otherwise in the same way as `Configuration.copyRecursive(org.gradle.api.specs.Spec)`
`copyRecursive(dependencySpec)` | Creates a copy of this configuration with dependencies from superconfigurations (see `Configuration.copyRecursive()`) but filtering the dependencies using the dependencySpec.
`defaultDependencies(action)` | 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:
`exclude(excludeProperties)` | 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(superConfigs)` | Adds the given configurations to the set of configuration which this configuration extends from.
`getTaskDependencyFromProjectDependency(useDependedOn, taskName)` | 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.

### Script blocks

No script blocks

### Property details

#### `PublishArtifactSet` `allArtifacts` (read-only)

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

#### `DependencySet` `allDependencies` (read-only)

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.

#### `PublishArtifactSet` `artifacts` (read-only)

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

#### `TaskDependency` `buildDependencies` (read-only)

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.

#### `DependencySet` `dependencies` (read-only)

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.

#### `String` `description`

The description for this configuration.

#### ``Set`<`ExcludeRule`>` `excludeRules` (read-only)

The exclude rules applied for resolving any dependency of this configuration.

#### ``Set`<`Configuration`>` `extendsFrom`

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

#### ``Set`<`Configuration`>` `hierarchy` (read-only)

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

#### `ResolvableDependencies` `incoming` (read-only)

Returns a `ResolvableDependencies` instance, exposing the results of dependency resolution. This method is the primary way to consume dependency resolution outputs.

#### `ResolutionStrategy` `resolutionStrategy` (read-only)

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.

#### `ResolvedConfiguration` `resolvedConfiguration` (read-only)

Returns a `ResolvedConfiguration`, a legacy view of the results of dependency resolution. Avoid this method for new code. Prefer accessing resolution outputs via `Configuration.getIncoming()`. This API will be deprecated and removed in future Gradle versions.

See `ResolvedConfiguration` for details on why this API should not be used.

#### `State` `state` (read-only)

The state of the configuration.

#### `boolean` `transitive`

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.

#### `boolean` `visible`

Note: This property is deprecated and will be removed in the next major version of Gradle.

This is a legacy property and the value does not affect dependency resolution in any way. There is no need to read this property and this method will be deprecated in an upcoming Gradle version.

The value of this property does not dictate in any way the "visibility" of a configuration, or if it is accessible between projects.

### Method details

#### `Configuration` `copy`()

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. `Configuration.getHierarchy()` for the copy will not include any superconfigurations.

This method is only intended for use for specific situations involving resolvable configuration, it is NOT intended as a general-purpose copying mechanism.

#### `Configuration` `copy`(`Closure` dependencySpec)

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

This method is only intended for use for specific situations involving resolvable configuration, it is NOT intended as a general-purpose copying mechanism.

#### `Configuration` `copy`(``Spec`<? super `Dependency`>` dependencySpec)

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

This method is only intended for use for specific situations involving resolvable configuration, it is NOT intended as a general-purpose copying mechanism.

#### `Configuration` `copyRecursive`()

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. `Configuration.getHierarchy()` for the copy will not include any superconfigurations.

This method is only intended for use for specific situations involving resolvable configuration, it is NOT intended as a general-purpose copying mechanism.

#### `Configuration` `copyRecursive`(`Closure` dependencySpec)

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

This method is only intended for use for specific situations involving resolvable configuration, it is NOT intended as a general-purpose copying mechanism.

#### `Configuration` `copyRecursive`(``Spec`<? super `Dependency`>` dependencySpec)

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

This method is only intended for use for specific situations involving resolvable configuration, it is NOT intended as a general-purpose copying mechanism.

#### `Configuration` `defaultDependencies`(``Action`<? super `DependencySet`>` action)

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.

#### `Configuration` `exclude`(``Map`<`String`, `String`>` excludeProperties)

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)`.

#### `Configuration` `extendsFrom`(``Configuration`...` superConfigs)

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

Configurations are only allowed to extend from other configurations in the same project.

#### `TaskDependency` `getTaskDependencyFromProjectDependency`(`boolean` useDependedOn, `String` taskName)

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.