Apache™ > Apache Ant™ > Apache Ivy™ > Documentation (2.4.0-rc1) > Reference > Ant Tasks > buildlist

buildlist

The buildlist task enable 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. (since 1.2)

This is particularly useful combined with subant, to build a set of interelated 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 contains a revision numbers, the rev attributes declared in the dependency is not used.
When the ivy.xml of the modules that you want to order contains a revision numbers, the revision numbers are used. If the revision number doesn't match a dependency description a warning is logged and the modules is considered as different modules.

since 1.3 A root attribute can also be used to include, among all the modules found, only the one 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 one 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 the ant 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.0 By default, all the modules included in a circular dependency are grouped together so that any dependency of any module in the loop will apear before the modules in the loop. This garantee that if there is a depedendency path between a module A and a module B (but no dependency path from B to A), B will alway apear before A even if A is included in a loop in the provided set of modules to sort.
Note that circular dependency can also trigger a failure depending on the value configured in the circularDependencyStrategy of your settings

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

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

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 neither 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 the ivy settings that must be used by this task	No, 'ivy.instance' is taken by default.

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.