doc/use/buildlist.html - ant-ivy - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
 <!--
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
 -->
 <html>
 <head>
 	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
 	<script type="text/javascript">var xookiConfig = {level: 1};</script>
 	<script type="text/javascript" src="../xooki/xooki.js"></script>
 </head>
 <body>
 	<textarea id="xooki-source">
 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. (<span class="since">since 1.2</span>)

 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 <a href="../ivyfile/info.html">revision</a> 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 <a href="../ivyfile/info.html">revision</a> 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.

 <span class="since">since 1.3</span> 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.

 <span class="since">since 1.4.1</span> 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.

 <span class="since">since 1.4</span> 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.

 <span class="since">since 2.0</span> 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.

 <span class="since">since 2.0</span> 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 <a href="../settings/conf.html#circularDependencyStrategy">settings</a>

 <span class="since">since 2.0</span> 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.

 <span class="since">since 2.0</span> 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).


 <table class="ant">
 <thead>
     <tr><th class="ant-att">Attribute</th><th class="ant-desc">Description</th><th class="ant-req">Required</th></tr>
 </thead>
 <tbody>
     <tr><td>reference</td><td>the reference of the path to set</td>
         <td>Yes</td></tr>
     <tr><td>ivyfilepath</td><td>the relative path from files to order to corresponding ivy files</td><td>No. Defaults to ${ivy.buildlist.ivyfilepath}</td></tr>
     <tr><td>root</td><td><span class="since">since 2.0</span> the names of the modules which should be considered as the root of the buildlist. <br/><span class="since">since 1.3</span> Was limited to only one module name before 2.0.</td><td>No. Defaults to no root (all modules are used in the build list)</td></tr>
     <tr><td>excluderoot</td><td><span class="since">since 1.3</span> true if the root defined should be excluded from the list</td><td>No. Defaults to false</td></tr>
     <tr><td>leaf</td><td><span class="since">since 2.0</span> the names of the modules which should be considered as the leaf of the buildlist. <br/><span class="since">since 1.4.1</span> Was limited to only one module name before 2.0.</td><td>No. Defaults to no leaf (all modules are used in the build list)</td></tr>
   <tr><td>onlydirectdep</td><td><span class="since">since 2.0</span> true if the
 resulting list should be restricted to direct dependencies of root modules or modules that directly depends on the leaf modules.<br/>
 This field is ignored when neither root neither leaf is filled.
      </td><td>No. Defaults to no false</td></tr>
     <tr><td>delimiter</td><td><span class="since">since 2.0</span> delimiter to use when specifying multiple module names in the root and leaf properties.</td><td>No. Defaults to the comma (,) character.</td></tr>
     <tr><td>excludeleaf</td><td><span class="since">since 1.4.1</span> true if the leaf defined should be excluded from the list</td><td>No. Defaults to false</td></tr>
     <tr><td>haltonerror</td><td>true to halt the build when an invalid ivy file is encountered, false to continue</td><td>No. Defaults to true</td></tr>
     <tr><td>skipbuildwithoutivy</td><td>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.</td><td>No. Defaults to false</td></tr>
     <tr><td>onMissingDescriptor</td><td><span class="since">since 2.0</span> Specify the action to take when no module descriptor file is found for a file of the fileset. Possible values are:
     <ul>
     <li>head</li>put at the head of the built filelist.
     <li>tail</li>put at the tail of the built filelist.
     <li>skip</li>skip the file, which won't be put in the build filelist at all.
     <li>warn</li>warn and put at the head of the build filelist.
     <li>fail</li>halt the build with a failure.
     </ul>
     </td><td>No. Defaults to 'head'</td></tr>
     <tr><td>reverse</td><td>true to obtain the list in the reverse order, i.e. from the most dependent to the least one</td><td>No. Defaults to default false</td></tr>
     <tr><td>restartFrom</td><td><span class="since">since 2.0</span> 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. <br/></td><td>No. Defaults to '*' meaning no restart point (all modules are used in the build list).</td></tr>
     <tr><td>settingsRef</td><td><span class="since">since 2.0</span> A reference to the ivy settings that must be used by this task</td><td>No, 'ivy.instance' is taken by default.</td></tr>
 </tbody>
 </table>

 <h2>Parameters specified as nested elements</h2>
 <h3>fileset</h3>
 FileSets are used to select sets of files to order.
 <h1>Examples</h1>
 <code type="xml">
     <ivy:buildlist reference="build-path">
       <fileset dir="projects" includes="**/build.xml"/>
     </ivy:buildlist>
 </code>
 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:
 <code type="xml">
     <subant target="build" buildpathref="build-path" />
 </code>

 <hr/>
 <code type="xml">
     <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" reverse="true">
       <fileset dir="projects" includes="**/build.xml"/>
     </ivy:buildlist>
 </code>
 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.
 <hr/>
 <code type="xml">
     <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" root="myapp">
       <fileset dir="projects" includes="**/build.xml"/>
     </ivy:buildlist>
 </code>
 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.
 <hr/>
 <code type="xml">
     <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" leaf="mymodule">
       <fileset dir="projects" includes="**/build.xml"/>
     </ivy:buildlist>
 </code>
 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.


 	</textarea>
 <script type="text/javascript">xooki.postProcess();</script>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->
	<html>
	<head>
	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
	<script type="text/javascript">var xookiConfig = {level: 1};</script>
	<script type="text/javascript" src="../xooki/xooki.js"></script>
	</head>
	<body>
	<textarea id="xooki-source">
	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. (<span class="since">since 1.2</span>)

	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 <a href="../ivyfile/info.html">revision</a> 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 <a href="../ivyfile/info.html">revision</a> 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.

	<span class="since">since 1.3</span> 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.

	<span class="since">since 1.4.1</span> 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.

	<span class="since">since 1.4</span> 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.

	<span class="since">since 2.0</span> 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.

	<span class="since">since 2.0</span> 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 <a href="../settings/conf.html#circularDependencyStrategy">settings</a>

	<span class="since">since 2.0</span> 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.

	<span class="since">since 2.0</span> 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).


	<table class="ant">
	<thead>
	<tr><th class="ant-att">Attribute</th><th class="ant-desc">Description</th><th class="ant-req">Required</th></tr>
	</thead>
	<tbody>
	<tr><td>reference</td><td>the reference of the path to set</td>
	<td>Yes</td></tr>
	<tr><td>ivyfilepath</td><td>the relative path from files to order to corresponding ivy files</td><td>No. Defaults to ${ivy.buildlist.ivyfilepath}</td></tr>
	<tr><td>root</td><td><span class="since">since 2.0</span> the names of the modules which should be considered as the root of the buildlist. <br/><span class="since">since 1.3</span> Was limited to only one module name before 2.0.</td><td>No. Defaults to no root (all modules are used in the build list)</td></tr>
	<tr><td>excluderoot</td><td><span class="since">since 1.3</span> true if the root defined should be excluded from the list</td><td>No. Defaults to false</td></tr>
	<tr><td>leaf</td><td><span class="since">since 2.0</span> the names of the modules which should be considered as the leaf of the buildlist. <br/><span class="since">since 1.4.1</span> Was limited to only one module name before 2.0.</td><td>No. Defaults to no leaf (all modules are used in the build list)</td></tr>
	<tr><td>onlydirectdep</td><td><span class="since">since 2.0</span> true if the
	resulting list should be restricted to direct dependencies of root modules or modules that directly depends on the leaf modules.<br/>
	This field is ignored when neither root neither leaf is filled.
	</td><td>No. Defaults to no false</td></tr>
	<tr><td>delimiter</td><td><span class="since">since 2.0</span> delimiter to use when specifying multiple module names in the root and leaf properties.</td><td>No. Defaults to the comma (,) character.</td></tr>
	<tr><td>excludeleaf</td><td><span class="since">since 1.4.1</span> true if the leaf defined should be excluded from the list</td><td>No. Defaults to false</td></tr>
	<tr><td>haltonerror</td><td>true to halt the build when an invalid ivy file is encountered, false to continue</td><td>No. Defaults to true</td></tr>
	<tr><td>skipbuildwithoutivy</td><td>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.</td><td>No. Defaults to false</td></tr>
	<tr><td>onMissingDescriptor</td><td><span class="since">since 2.0</span> Specify the action to take when no module descriptor file is found for a file of the fileset. Possible values are:
	<ul>
	<li>head</li>put at the head of the built filelist.
	<li>tail</li>put at the tail of the built filelist.
	<li>skip</li>skip the file, which won't be put in the build filelist at all.
	<li>warn</li>warn and put at the head of the build filelist.
	<li>fail</li>halt the build with a failure.
	</ul>
	</td><td>No. Defaults to 'head'</td></tr>
	<tr><td>reverse</td><td>true to obtain the list in the reverse order, i.e. from the most dependent to the least one</td><td>No. Defaults to default false</td></tr>
	<tr><td>restartFrom</td><td><span class="since">since 2.0</span> 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. <br/></td><td>No. Defaults to '*' meaning no restart point (all modules are used in the build list).</td></tr>
	<tr><td>settingsRef</td><td><span class="since">since 2.0</span> A reference to the ivy settings that must be used by this task</td><td>No, 'ivy.instance' is taken by default.</td></tr>
	</tbody>
	</table>

	<h2>Parameters specified as nested elements</h2>
	<h3>fileset</h3>
	FileSets are used to select sets of files to order.
	<h1>Examples</h1>
	<code type="xml">
	<ivy:buildlist reference="build-path">
	<fileset dir="projects" includes="**/build.xml"/>
	</ivy:buildlist>
	</code>
	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:
	<code type="xml">
	<subant target="build" buildpathref="build-path" />
	</code>

	<hr/>
	<code type="xml">
	<ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" reverse="true">
	<fileset dir="projects" includes="**/build.xml"/>
	</ivy:buildlist>
	</code>
	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.
	<hr/>
	<code type="xml">
	<ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" root="myapp">
	<fileset dir="projects" includes="**/build.xml"/>
	</ivy:buildlist>
	</code>
	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.
	<hr/>
	<code type="xml">
	<ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" leaf="mymodule">
	<fileset dir="projects" includes="**/build.xml"/>
	</ivy:buildlist>
	</code>
	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.


	</textarea>
	<script type="text/javascript">xooki.postProcess();</script>
	</body>
	</html>