# ResolutionStrategy

API Documentation: | `ResolutionStrategy`

Defines the strategies around dependency resolution. For example, forcing certain dependency versions, substitutions, conflict resolutions or snapshot timeouts.

Examples:

    plugins {
        id 'java' // so that there are some configurations
    }

    configurations.all {
      resolutionStrategy {
        // fail eagerly on version conflict (includes transitive dependencies)
        // e.g. multiple different versions of the same dependency (group and name are equal)
        failOnVersionConflict()

        // prefer modules that are part of this build (multi-project or composite build) over external modules
        preferProjectModules()

        // force certain versions of dependencies (including transitive)
        //  *append new forced modules:
        force 'asm:asm-all:3.3.1', 'commons-io:commons-io:1.4'
        //  *replace existing forced modules with new ones:
        forcedModules = ['asm:asm-all:3.3.1']

        // add dependency substitution rules
        dependencySubstitution {
          substitute module('org.gradle:api') using project(':api')
          substitute project(':util') using module('org.gradle:util:3.0')
        }

        // cache dynamic versions for 10 minutes
        cacheDynamicVersionsFor 10*60, 'seconds'
        // don't cache changing modules at all
        cacheChangingModulesFor 0, 'seconds'
      }
    }

### Properties

Property | Description
`componentSelection` | The currently configured version selection rules object.
`dependencySubstitution` | The set of dependency substitution rules that are set for this configuration.
`forcedModules` | Returns currently configured forced modules. For more information on forcing versions see `ResolutionStrategy.force(java.lang.Object[])`

### Methods

Method | Description
`activateDependencyLocking()` | Activates dependency locking support in Gradle. Once turned on on a configuration, resolution result can be saved and then reused for subsequent builds. This enables reproducible builds when using dynamic versions.
`cacheChangingModulesFor(value, units)` | Sets the length of time that changing modules will be cached, with units expressed as a String.
`cacheChangingModulesFor(value, units)` | Sets the length of time that changing modules will be cached.
`cacheDynamicVersionsFor(value, units)` | Sets the length of time that dynamic versions will be cached, with units expressed as a String.
`cacheDynamicVersionsFor(value, units)` | Sets the length of time that dynamic versions will be cached.
`componentSelection(action)` | The componentSelection block provides rules to filter or prevent certain components from appearing in the resolution result.
`dependencySubstitution(action)` | Configures the set of dependency substitution rules for this configuration. The action receives an instance of `DependencySubstitutions` which can then be configured with substitution rules.
`eachDependency(rule)` | Adds a dependency substitution rule that is triggered for every dependency (including transitive) when the configuration is being resolved. The action receives an instance of `DependencyResolveDetails` that can be used to find out what dependency is being resolved and to influence the resolution process. Example:
`failOnVersionConflict()` | In case of conflict, Gradle by default uses the newest of conflicting versions. However, you can change this behavior. Use this method to configure the resolution to fail eagerly on any version conflict, e.g. multiple different versions of the same dependency (group and name are equal) in the same `Configuration`. The check includes both first level and transitive dependencies. See example below:
`force(moduleVersionSelectorNotations)` | Allows forcing certain versions of dependencies, including transitive dependencies. Appends new forced modules to be considered when resolving dependencies.
`getUseGlobalDependencySubstitutionRules()` | Incubating Gradle implicitly registers dependency substitution rules for all configurations in the whole build tree to find projects in other included builds. These rules are always active by default. There are however cases, where a certain configuration should not apply these rules when resolving. For example, if a binary version of a module should be discovered that is also represented by a project in another build. This property may be used to deactivate these global substitution rules.
`preferProjectModules()` | Gradle can resolve conflicts purely by version number or prioritize project dependencies over binary. The default is by version number.

### Script blocks

No script blocks

### Property details

#### `ComponentSelectionRules` `componentSelection` (read-only)

The currently configured version selection rules object.

#### `DependencySubstitutions` `dependencySubstitution` (read-only)

The set of dependency substitution rules that are set for this configuration.

#### ``Set`<`ModuleVersionSelector`>` `forcedModules`

Returns currently configured forced modules. For more information on forcing versions see `ResolutionStrategy.force(java.lang.Object[])`

### Method details

#### `ResolutionStrategy` `activateDependencyLocking`()

Activates dependency locking support in Gradle. Once turned on on a configuration, resolution result can be saved and then reused for subsequent builds. This enables reproducible builds when using dynamic versions.

#### `void` `cacheChangingModulesFor`(`int` value, `String` units)

Sets the length of time that changing modules will be cached, with units expressed as a String.

A convenience method for `ResolutionStrategy.cacheChangingModulesFor(int, java.util.concurrent.TimeUnit)` with units expressed as a String. Units are resolved by calling the `valueOf(String)` method of `TimeUnit` with the upper-cased string value.

#### `void` `cacheChangingModulesFor`(`int` value, `TimeUnit` units)

Sets the length of time that changing modules will be cached.

Gradle caches the contents and artifacts of changing modules. By default, these cached values are kept for 24 hours, after which the cached entry is expired and the module is resolved again.

Use this method to provide a custom expiry time after which the cached entries for any changing module will be expired.

#### `void` `cacheDynamicVersionsFor`(`int` value, `String` units)

Sets the length of time that dynamic versions will be cached, with units expressed as a String.

A convenience method for `ResolutionStrategy.cacheDynamicVersionsFor(int, java.util.concurrent.TimeUnit)` with units expressed as a String. Units are resolved by calling the `valueOf(String)` method of `TimeUnit` with the upper-cased string value.

#### `void` `cacheDynamicVersionsFor`(`int` value, `TimeUnit` units)

Sets the length of time that dynamic versions will be cached.

Gradle keeps a cache of dynamic version => resolved version (ie 2.+ => 2.3). By default, these cached values are kept for 24 hours, after which the cached entry is expired and the dynamic version is resolved again.

Use this method to provide a custom expiry time after which the cached value for any dynamic version will be expired.

#### `ResolutionStrategy` `componentSelection`(``Action`<? super `ComponentSelectionRules`>` action)

The componentSelection block provides rules to filter or prevent certain components from appearing in the resolution result.

#### `ResolutionStrategy` `dependencySubstitution`(``Action`<? super `DependencySubstitutions`>` action)

Configures the set of dependency substitution rules for this configuration. The action receives an instance of `DependencySubstitutions` which can then be configured with substitution rules.

Examples:

    // add dependency substitution rules
    configurations.all {
      resolutionStrategy.dependencySubstitution {
        // Substitute project and module dependencies
        substitute module('org.gradle:api') using project(':api')
        substitute project(':util') using module('org.gradle:util:3.0')

        // Substitute one module dependency for another
        substitute module('org.gradle:api:2.0') using module('org.gradle:api:2.1')
      }
    }

#### `ResolutionStrategy` `eachDependency`(``Action`<? super `DependencyResolveDetails`>` rule)

Adds a dependency substitution rule that is triggered for every dependency (including transitive) when the configuration is being resolved. The action receives an instance of `DependencyResolveDetails` that can be used to find out what dependency is being resolved and to influence the resolution process. Example:

    configurations {
      compileClasspath.resolutionStrategy {
        eachDependency { DependencyResolveDetails details ->
          //specifying a fixed version for all libraries with 'org.gradle' group
          if (details.requested.group == 'org.gradle') {
            details.useVersion '1.4'
          }
        }
        eachDependency { details ->
          //multiple actions can be specified
          if (details.requested.name == 'groovy-all') {
             //changing the name:
             details.useTarget group: details.requested.group, name: 'groovy', version: details.requested.version
          }
        }
      }
    }

The rules are evaluated in order they are declared. Rules are evaluated after forced modules are applied (see `ResolutionStrategy.force(java.lang.Object[])`

#### `ResolutionStrategy` `failOnVersionConflict`()

In case of conflict, Gradle by default uses the newest of conflicting versions. However, you can change this behavior. Use this method to configure the resolution to fail eagerly on any version conflict, e.g. multiple different versions of the same dependency (group and name are equal) in the same `Configuration`. The check includes both first level and transitive dependencies. See example below:

    plugins {
        id 'java' // so that there are some configurations
    }

    configurations.all {
      resolutionStrategy.failOnVersionConflict()
    }

#### `ResolutionStrategy` `force`(``Object`...` moduleVersionSelectorNotations)

Allows forcing certain versions of dependencies, including transitive dependencies. Appends new forced modules to be considered when resolving dependencies.

It accepts following notations:

- String in a format of: 'group:name:version', for example: 'org.gradle:gradle-core:1.0'
- instance of `ModuleVersionSelector`
- any collection or array of above will be automatically flattened

Example:

    plugins {
        id 'java' // so that there are some configurations
    }

    configurations.all {
      resolutionStrategy.force 'asm:asm-all:3.3.1', 'commons-io:commons-io:1.4'
    }

#### ``Property`<`Boolean`>` `getUseGlobalDependencySubstitutionRules`()

Note: This method is incubating and may change in a future version of Gradle.

Gradle implicitly registers dependency substitution rules for all configurations in the whole build tree to find projects in other included builds. These rules are always active by default. There are however cases, where a certain configuration should not apply these rules when resolving. For example, if a binary version of a module should be discovered that is also represented by a project in another build. This property may be used to deactivate these global substitution rules.

#### `void` `preferProjectModules`()

Gradle can resolve conflicts purely by version number or prioritize project dependencies over binary. The default is by version number.

This applies to both first level and transitive dependencies. See example below:

    plugins {
        id 'java' // so that there are some configurations
    }

    configurations.all {
      resolutionStrategy.preferProjectModules()
    }