Home

Tag: dependency Parent: dependencies

Declares a dependency for this module. A dependency is described by the module on which the current module depends (identified by its name, organisation and revision), and a mapping of configurations.

Fixed and dynamic revisions

The revision can be given as a fixed one (1.5.2, for instance) or as a latest (or dynamic) one. Several possibilities for dynamic revisions are implemented in Ivy:

latest.integration
latest.[any status]

since 1.4

end the revision with a +

version ranges

since 1.4

since 1.4 If you don't find a way to expression your dependency version constraint among these, you can plug your own.
The way to determine which revision is the "latest" between two is configurable through the use of pluggable LatestStrategy. See ivy main concepts for details about this.

Revision constraint

since 2.0 The dependency tag supports two revision attributes: rev, corresponding to the default required dependency revision, and revConstraint, corresponding to a dynamic revision constraint applied on this dependency.

Depending on the resolve mode used, the actual revision used during dependency resolution may vary. These revisions usually differ only for modules published in a repository. When deliver is used, dynamic version constraints are replaced by a stic version constraint, to help build reproducibility. However, the information of the original version constraint is not lost, but rather put in the revConstraint attribute. This both ensure better metadata in the repository while still allowing easier build reproducibility.

Configurations mapping

This mapping indicates which configurations of the dependency are required in which configurations of the current module, also called master configurations.

There are several ways to declare this mapping of configurations, choose depending more on preference than on possibilities. Try to avoid mixing usage in a single dependency element: do not use both nested and inline mapping declaration.

The first way to declare this mapping is called the inline mapping. It is maybe the less natural at first, but it's powerful and concise. Inline mapping can take several forms.

Specify one configuration name

More examples:
The table below indicates how ivy interpret the conf attribute according to how defaultconfmapping is set:

defaultconfmapping	conf	ivy interpretation
		->
	runtime	runtime->runtime
	test	test->test
runtime->*;test->default		runtime->*;test->default
runtime->*;test->default	runtime	runtime->*
runtime->*;test->default	test	test->default

Specify a configuration mapping using the '->' operator separating a comma separated list of master configurations (left operand) of a comma separated list of dependency configurations (right operand).

A good way to remember which side is for the master configuration (i.e. the configuration of the module defining the dependency) and which side is for the dependency configuration is to read the '->' as 'depends on'.

In this case, all specified dependency configurations are required in all specified master configurations.
For instance, 'A, B, C -> E, F' means that dependency configurations E & F are required in master configurations A, B and C.

Note that you can use the wildcard '*' as a configuration name, meaning that all configurations (either master or dependency public ones depending on the side) are wanted. For instance, '* -> B, C' means that B & C dependency configurations are required in all master configurations.

since 1.4 you can use * wildcard followed by negated configurations to mean all but xxx. For instance, '*, !A, !B -> X' means that X dependency configuration is required in all master configurations except A and B.

since 1.2 '@' also has a special meaning as a right operand of the dependency mapping, it means map to self. This is particularly useful with '*', '*->@' meaning that all configurations of the module maps to their equivalent (same name) in the dependency.

since 1.4 '#' can be used as right side operand to mean 'this' configuration, and thus refers to the configuration being resolved. It is slightly similar to @, except that it takes into account the configuration being actually resolved in case of a configuration extending another one.

Example:
Let's foo be a module with two configurations, A and B, B extending A.
Then a dependency declaring conf A-># will get A dep conf in its confs A (when resolving A, ivy will find interpret the # symbol as A) and B dep conf in its conf B (when resolving B, ivy will interpret the # symbol as B, even if this dependency is only required because of the A dependency).

If you don't understand really how this works, do not use it :-)

since 1.4 '%' can be used as left side operand to mean 'all the other configurations'. This can be usefull when you only have a specific mapping for some configurations and a default mapping for all the others.

Example:

test->runtime;%->default

means that the

test

configuration is mapped to the

runtime

configuration, but all the other configurations are mapped to the

default

configuration.

since 1.3 a fallback mechanism can be used when you are not sure that the dependency will have the required conf. You can indicate to ivy that you want one configuration, but if it isn't present, use another one.
The syntax for specifying this adds the fallback conf between parenthesis right after the required conf.
For instance,

test->runtime(default)

means that in the test configuration of the module the

runtime

conf of the dependency is required, but if doesn't exist, it will use the

default

conf instead. If

default

conf doesn't exist then it will be considered as an error. Note that the

wildcard can be used as fallback conf.

since 1.4 you can add simple conditions in the dependency mapping. This is done by adding a condition between '[' and ']'. If the condition evaluates to

true

, the mapping is performed. If the condition evaluates to

false

, the mapping will be ignored. For instance,

test->[org=A]runtime,[org=B]default

means that the

test

configuration will be mapped to the

runtime

conf for the dependencies of organisation 'A' and to the

default

conf for dependencies of organisation 'B'.

Specify a semi-column separated list of any of the previous specs.

In this case, it is the union of the mapping which is kept. For instance, 'A -> B; * -> C' means that B conf is needed in A conf and C conf is need in all master conf... so both B & C dep conf are required in A master conf

If you prefer more verbose mapping declaration, everything is also possible with sub elements mapping declaration.

Artifact restriction

Moreover, the dependency element also supports an artifact restriction feature (since 0.6).
See dependency artifact restriction for details.

Forcing revision

Finally, the dependency element also supports an a force attribute (since 0.8), which gives an indication
to conflicts manager to force the revision of a dependency to the one given here.
See conflicts manager for details.

since 1.4 this tag supports extra attributes

Attributes

Attribute	Description	Required
org	the name of the organisation of the dependency.	No, defaults to the master module organisation
name	the module name of the dependency	Yes
branch	the branch of the dependency. since 1.4	No, defaults to the default branch setting for the dependency.
rev	the revision of the dependency. See above for details.	Yes
revConstraint	the dynamic revision constraint originally used for this dependency. See above for details.	No, defaults to the value of rev
force	a boolean to give an indication to conflict manager that this dependency should be forced to this revision (see conflicts manager)	No, defaults to false
conf	an inline mapping configuration spec (see above for details)	No, defaults to defaultconf attribute of dependencies element if neither conf attribute nor conf children element is given
transitive	true to resolve this dependency transitively, false otherwise (since 1.2)	No, defaults to true
changing	true if the dependency artifacts may change without revision change, false otherwise (since 1.2). See cache and change management for details.	No, defaults to false

Child elements

Element	Description	Cardinality
conf	defines configuration mapping has sub element	0..n
artifact / include	defines artifacts inclusion - use only if you do not control dependency ivy file	0..n
exclude	defines artifacts exclusion - use only if you do not control dependency ivy file	0..n

Examples

<dependency org="jayasoft" name="swtbinding" revision="0.2"/>

Declares a dependency on the module swtbinding from jayasoft in its revision 0.2. All the configuration of this dependency will be included in all configurations of the module in which the dependency is declared.

<dependency org="jayasoft" name="swtbinding" branch="fix-103" revision="latest.integration"/>

Same as above except that it will take the latest revision on the branch 'fix-103' instead of revision '0.2'.

<dependency name="mymodule" revision="latest.integration" conf="test->default"/>

Declares a dependency on the module

mymodule

from the same organisation as the module in which the dependency is declared. The latest available revision of this dependency will be used. This dependency will only be included in the test configuration of the module, and it's only the default configuration of the dependency which will be included.

<dependency org="apache" name="commons-lang" revision="2.0" force="true" conf="default"/>

Declares a dependency on the module

commons-lang

from apache, in revision 2.0. The revision 2.0 will be used even if another dependency declares itself a dependency on another version of commons-lang. Moreover, if no defaultconfmapping is defined, only the

default

conf of commons-lang will be used in the

default

conf of the master module. If

*->runtime

was declared as defaultconfmapping, then the runtime conf of commons-lang would be included in the default conf of the master module. Note that whatever the defaultconfmapping is, the dependency only be included in the default conf of the master module. The defaultconfmapping only changes the required dependency confs.

<dependency org="foo" name="bar" revision="3.0" transitive="false" conf="default->@;runtime,test->runtime"/>

Declares a dependency on the module

bar

from foo, in revision 3.0. The dependencies of bar will themselves not be included due to the setting of transitive. The default dependency conf will be included in the default master conf, and the runtime dependency conf will be included in both the runtime and test master conf.

<dependency org="foo" name="bar" revision="3.0" changing="true" conf="compile->runtime(default)"/>

Declares a dependency on the module

bar

from foo, in revision 3.0. This revision is considered to be able to change (

changing="true"

), so even if it is already in ivy cache, Ivy will check if a revision is a more recent last modified date is available on the repository. The runtime conf of bar is required in the compile conf of the master module, but if bar doesn't define a runtime conf, then the

default

conf will be used.