license

Attributes

ivyauthor

Attributes

repository

Attributes

description

Attributes

conf

Tag: conf Parent: configurations

Declares a configuration of this module. As described in the reference page, a configuration is a way to use or construct a module. Some modules may be used in different ways (think about hibernate which can be used inside or outside an application server), and this way may alter the artifacts you need (in the case of hibernate, jta.jar is needed only if it is used outside an application server). Moreover, a module may need some other modules and artifacts only at build time, and some others at runtime. All those differents ways to use or build a module are called in ivy configurations.

The conf element in the configurations section declares one configuration. This declaration gives the name of the configuration declared, its visibility and the other configurations of the module it extends.

Visibility is used to indicate whether or not a configuration can be used from other modules depending on this one. Thus a private configuration is only used for internal purpose (maybe at build time), and other modules cannot declare to depend on it.

A configuration can also extend one or several other ones of the same module. When a configuration extends another one, then all artifacts required in the extended configuration will also be required in the configuration that extends the other one. For instance, if configuration B extends configuration A, and if artifacts art1 and art2 are required in configuration A, then they will be automatically required in configuration B. On the other hand, artifacts required in configuration B are not necessarily required in configuration A.

This notion is very helpful to define configurations which are similar with some differences.

since 1.4 The extends attribute can use the following wildcards:

since 1.4 A whole configuration can be declared as non transitive, so that all dependencies resolved in this configuration will be resolved with transitivity disabled. Note that the transitivity is disabled for all the configuration dependencies (including those obtained because this conf extends other ones), and only for this configuration (which means that a conf extending this one with transitivityy enabled will get transitive dependencies even for dependencies being part of the non transitive configuration).
This is very useful to build a compile configuration, for instance, forcing the dependency declaration on each direct dependency, with no risk to forget some because of transitivity.

since 1.4 This tag supports extra attributes.

Attributes

Examples

Declares three configurations, core compile and runtime, with only the runtime one accessible from other modules, and with the compile one being non transitive.
Therefore the core configuration will only be composed of dependencies declared in the core configuration itself, the compile configuration will be composed of all dependencies required in either core or compile configuration, but without transivity (neither for core nor compile dependencies), and runtime will be composed of all dependencies, all transitively, including the dependencies declared only in compile.

include

Tag: include Parent: configurations

Include configurations specified in another file. since 1.3

The included file should have a configurations tag as root tag, which follow the same specification as the configurations tag of the ivy file.

This means that it can contain conf declarations, other file inclusion, and also a defaultconfmapping.

When delivering an ivy file with such an inclusion, the included configuration file is inlined, i.e. ivy remove the dependency on the external file.

Attributes

Examples

with included-configurations.xml like this:

Defines 3 configurations, conf1, conf2 and conf3. mymodule1 is required in each configuration, with for each the same configuration (conf1 is needed in conf1, conf2 in conf2, and conf3 in conf3) due to the defaultconfmapping defined in the included file.

artifact

Tag: artifact Parent: publications

Declares an artifact published by this module. This is especially useful for other modules dependending on this one. They thus get all published artifacts belonging to the configurations asked. Indeed, each published artifact declares in which public configuration it is published. Thus a module depending on this module only get artifacts marked with the asked configurations, taking into account configurations extension (see configuration declaration).

The configurations in which an artifact is published can be configured in two ways:

• conf attribute on artifact element
• conf subelement

The twos are equivalent, it is only a matter of preference. However, do not mix both for one artifact.

since 1.4 The artifact element as default values for all its attributes, so if you want to declare a default artifact you can just declare it like that:

If this is the only artifact declared, then it's equivalent to having no publication section at all.

since 1.4 It is possible to give a url at which artifacts can be found. This is not mandatory, and even not recommended. This is only a convenient way to deal with an existing repository with a bad layout, but should not be avoided in an enterprise repository.

Attributes

Child elements

Examples

Declares an artifact with the name of the module as name, type and ext jar, and published in all configurations.

Declares an artifact foo-src, of type 'source' with extension 'zip', and published in the src configuration.

Declares an artifact foo, of type and extension 'jar' located at the url http://www.acme.com/repository/barbaz/foo-1.2-bar.jar. This url will only be used if the artifact cannot be found at its standard location.

dependency

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

selects the latest revision of the dependency module.

• latest.[any status]

selects the latest revision of the dependency module with at least the specified status. since 1.4
For instance latest.milestone will select the latest version being either a milestone or a release, and latest.release will only selects the latest release. Note that in order to find the latest revision with the appropriate status Ivy has to parse all the ivy files in your repository from the last one until it finds such a revision. Hence don't be surprised if the resolution slow down.
See also statuses to see how to configure module statuses.

• end the revision with a +

selects the latest sub-revision of the dependency module. For instance,
if the dependency module exists in revision 1.0.3, 1.0.7 and 1.1.2, "1.0.+" will select 1.0.7.

• version ranges

mathematical notation for ranges can be used to match a range of version. since 1.4
Examples:
[1.0,2.0] matches all versions greater or equal to 1.0 and lower or equal to 2.0
[1.0,2.0[ matches all versions greater or equal to 1.0 and lower than 2.0
]1.0,2.0] matches all versions greater than 1.0 and lower or equal to 2.0
]1.0,2.0[ matches all versions greater than 1.0 and lower than 2.0
[1.0,) matches all versions greater or equal to 1.0
]1.0,) matches all versions greater than 1.0
(,2.0] matches all versions lower or equal to 2.0
(,2.0[ matches all versions lower than 2.0

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.

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

This means that in this master configuration the same dependency configuration is needed (except if a defaultconfmapping has been specified in this ivy file, see configurations for details, or table below for examples).
For instance, if the current module has defined a configuration named 'runtime', and the dependency too, then having an inline mapping configuration set to 'runtime' means that in the runtime master configuration the runtime dependency configuration is required.

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

See this thread on the forum for a more detailed motivation behind this keyword.
If you don't understand really how this works, do not use :-)

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

Child elements

Examples

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.

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

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.

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.

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.

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.

manager

Attributes