buildlist

[since 1.2]

The buildlist task enables to obtain a filelist of files (usually build.xml files) ordered according to Ivy dependency information from the least dependent to the most one, or the inverse.

This is particularly useful combined with subant, to build a set of interrelated projects being sure that a dependency will be built before any module depending on it.

When the ivy.xml of the modules that you want to order doesn’t contain revision numbers, the rev attributes declared in the dependencies are not used. When the ivy.xml of the modules that you want to order contains revision numbers, the revision numbers are used. If the revision number doesn’t match a dependency description, a warning is logged and the modules are considered to be different modules.

(since 1.3) A root attribute can also be used to include, among all the modules found, only the ones that are dependencies (either direct or transitive) of a root module. This can also be used with the excluderoot attribute, which when set to true will exclude the root itself from the list.

(since 1.4.1) A leaf attribute can also be used to include, among all the modules found, only the ones that have dependencies (either direct or transitive) on a leaf module. This can also be used with the excludeleaf attribute, which when set to true will exclude the leaf itself from the list.

(since 1.4) The ivy.sorted.modules property is set in Ant project at the end of the task with a comma separated list of ordered modules. This can be useful for debug or information purpose.

(since 2.0) The root and leaf attributes can be a delimited list of modules to use as roots. These modules, and all their dependencies will be included in the build list.

(since 2.5) The root and leaf modules can also be specified as nested root and leaf elements. This way, not only the module name can be specified, but also the organisation, revision and branch of the root/leaf.

By default, all the modules included in a circular dependency are grouped together so that any dependency of any module in the loop will appear before the modules in the loop. This guarantees that if there is a dependency path between a module A and a module B (but no dependency path from B to A), B will always appear before A even if A is included in a loop in the provided set of modules to sort. Note that a circular dependency can also trigger a failure depending on the value configured in the circularDependencyStrategy of your settings

When you are specifying root or leaf modules you can limit the resulting list to only direct dependencies of the root modules or to modules that directly depends on your leaf modules.

You can also specify a restartFrom modules. The difference with root or leaf is that you get a list starting at the restartFrom module followed by all the modules that would be after if the parameter would not be there (even if there is no dependency between the restartFrom and the following module).

Attributes

Attribute Description Required

reference

the reference of the path to set

Yes

ivyfilepath

the relative path from files to order to corresponding Ivy files

No. Defaults to ${ivy.buildlist.ivyfilepath}

root

(since 2.0) the names of the modules which should be considered as the root of the buildlist.

(since 1.3) Was limited to only one module name before 2.0.

No. Defaults to no root (all modules are used in the build list)

excluderoot

(since 1.3) true if the root defined should be excluded from the list

No. Defaults to false

leaf

(since 2.0) the names of the modules which should be considered as the leaf of the buildlist.

(since 1.4.1) Was limited to only one module name before 2.0.

No. Defaults to no leaf (all modules are used in the build list)

onlydirectdep

(since 2.0) true if the resulting list should be restricted to direct dependencies of root modules or modules that directly depends on the leaf modules.

This field is ignored when neither root nor leaf is filled.

No. Defaults to no false

delimiter

(since 2.0) delimiter to use when specifying multiple module names in the root and leaf properties.

No. Defaults to the comma (,) character.

excludeleaf

(since 1.4.1) true if the leaf defined should be excluded from the list

No. Defaults to false

haltonerror

true to halt the build when an invalid Ivy file is encountered, false to continue

No. Defaults to true

skipbuildwithoutivy

Deprecated, use onMissingDescriptor instead. true to skip files of the fileset with no corresponding Ivy file, false otherwise. If false the file with no corresponding Ivy file will be considered as independent of the other and put at the beginning of the built filelist.

No. Defaults to false

onMissingDescriptor

(since 2.0) Specify the action to take when no module descriptor file is found for a file of the fileset. Possible values are:
* head: put at the head of the built filelist.
* tail: put at the tail of the built filelist.
* skip: skip the file, which won’t be put in the build filelist at all.
* warn: warn and put at the head of the build filelist.
* fail: halt the build with a failure.

No. Defaults to head

reverse

true to obtain the list in the reverse order, i.e. from the most dependent to the least one

No. Defaults to default false

restartFrom

(since 2.0) The name of the module which should be considered as the starting point in the buildlist. This allows for the build to be started at any point in the dependency chain.

No. Defaults to * meaning no restart point (all modules are used in the build list).

settingsRef

(since 2.0) A reference to Ivy settings that must be used by this task

No, ivy.instance is taken by default.

Child elements

Element Description Cardinality

root

(since 2.5) Declares a root module.

This element takes the following attributes:
* organisation: the organisation of the root module (defaults to *)
* module: the name of the root module (defaults to *)
* revision: the revision of the root module (defaults to *)
* branch: the branch of the root module (default to *) * file: a specific ivy.xml file to use as root module

0..n

leaf

(since 2.5) Declares a leaf module.

This element takes the following attributes:
* organisation: the organisation of the leaf module (defaults to *)
* module: the name of the leaf module (defaults to *)
* revision: the revision of the leaf module (defaults to *)
* branch: the branch of the leaf module (default to *) * file: a specific ivy.xml file to use as leaf module

0..n

Parameters specified as nested elements

fileset

FileSets are used to select sets of files to order.

Examples

    <ivy:buildlist reference="build-path">
      <fileset dir="projects" includes="**/build.xml"/>
    </ivy:buildlist>

Builds a list of build.xml files sorted according to the ivy.xml files found at the same level (the default value for ivyfilepath is ivy.xml).

This list can then be used like that:

    <subant target="build" buildpathref="build-path"/>
    <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" reverse="true">
      <fileset dir="projects" includes="**/build.xml"/>
    </ivy:buildlist>

Builds a list of build.xml files sorted according to the ivy.xml files found in an Ivy directory relative to those build files. The list is sorted from the most dependent to the least one.

    <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" root="myapp">
      <fileset dir="projects" includes="**/build.xml"/>
    </ivy:buildlist>

Builds a list of build.xml files sorted according to the ivy.xml files found in an Ivy directory relative to those build files. Only build.xml files of modules which are dependencies of myapp (either direct or transitive) are put in the result list.

    <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" leaf="mymodule">
      <fileset dir="projects" includes="**/build.xml"/>
    </ivy:buildlist>

Builds a list of build.xml files sorted according to the ivy.xml files found in an Ivy directory relative to those build files. Only build.xml files of modules which have dependencies (direct or transitive) on mymodule are put in the result list.

    <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml">
      <root organisation="myorg" module="myapp" />
      <fileset dir="projects" includes="**/build.xml"/>
    </ivy:buildlist>

Builds a list of build.xml files sorted according to the ivy.xml files found in an Ivy directory relative to those build files. Only build.xml files of modules which are dependencies of myorg#myapp (either direct or transitive) are put in the result list.

    <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml">
      <root file="/path/to/myapp-ivy.xml" />
      <fileset dir="projects" includes="**/build.xml"/>
    </ivy:buildlist>

Builds a list of build.xml files sorted according to the ivy.xml files found in an Ivy directory relative to those build files. Only build.xml files of modules which are dependencies defined in /path/to/myapp-ivy.xml (either direct or transitive) are put in the result list.