Added: ant/ivy/site/target/history/2.2.0/use/deliver.html URL: http://svn.apache.org/viewvc/ant/ivy/site/target/history/2.2.0/use/deliver.html?rev=1005260&view=auto ============================================================================== --- ant/ivy/site/target/history/2.2.0/use/deliver.html (added) +++ ant/ivy/site/target/history/2.2.0/use/deliver.html Wed Oct 6 21:25:29 2010 @@ -0,0 +1,184 @@ + + + + + + + + +deliver | Apache Ivy + + + + + + + + + + +
+ + + + + + + + + + + + + +
+ +
+ +
+ + + + +
+ + +
+ + +
+ + + + + + + +
+
+ +

deliver

+
Deliver a resolved descriptor of the current module, and possibly perform a recursive delivery of dependencies.

This task does two main things:

Generate a resolved ivy file

+This task generates a resolved descriptor of the current module, based upon the last resolve done. The resolved ivy file contains updated information about the delivered module, such as revision and status.

Moreover, all included configurations' files are included in the ivy file, and variables are replaced by their values.

Finally, in the resolved ivy file, dynamic revisions are replaced by the static ones that have been found during the resolve step, so the ivy file can be used later safely to obtain the same dependencies (providing that a revision uniquely identifies a module, which should be the case for proper ivy use).

since 1.3 The replacement of dynamic revisions by static ones can be turned off, so that dynamic revisions are kept in the ivy file. This is an exception to the recommended standard that published mod ule descriptors be fully resolved, so use it with caution.

do recursive delivery

+This is done only if a deliver target is given to the deliver task.

If a deliver target is set, then it is called (via an antcall) for each dependency which has not a suffisant status compared to the deliver status set for this task. This means that if you deliver an integration revision, no recursive delivery will be done.

If you deliver a milestone or a release revision, deliver target will be called with each integration dependency.

The deliver target is called with the following properties available: +
    +
  • dependency.name
  • +the name of the dependency to recursively deliver
  • dependency.published.status
  • +the status to which the dependency should be delivered
  • dependency.published.version
  • +the revision to which the dependency should be delivered
  • dependency.version
  • +the revision of the dependency that should be delivered (the one that was retrieved during last resolve) +
+Both
dependency.published.status
and
dependency.published.version
can be either asked to the user through ant input tasks (default behaviour), or be always the same for the whole recursive delivery process if the following properties are set: +
    +
  • recursive.delivery.status
  • set to the status to which all dependencies requiring to be delivered will be +
  • recursive.delivery.version
  • set to the version to which all dependencies requiring to be delivered will be +
+ +Usually the deliver target itself triggers an another ant build (using ant task) even if this is up to you to decide.

The delivered ivy file will update its dependency revisions with those given here.

deliver and publish

+The deliver task is most of the time not called explicitly, but rather called automatically by the publish task. So, when shall the deliver task be called explictly? When you actually need to separate what is performed by the deliver task (see above), from what is performed by the publish task, i.e. upload a module to a repository.

And this can be particularly useful if you want to process the generated ivy file before uploading it (if you want to add automatically more information like an SCM tag used, the user who performed the release, ...).

It can also be useful if you want to trigger a recursive delivery and then ensure that you get the recursively delivered modules as dependencies. In this case your build order may look like this:
- ivy:configure
- ivy:resolve
- ivy:deliver with recursive delivery
- ivy:resolve again with the ivy file generated by the recursive delivery
- do your build stuff (compile, jar, whatever)
- ivy:publish
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
deliverpatternthe pattern to use for ivy file deliveryNo. Defaults to ${ivy.deliver.ivy.pattern}
pubrevisionthe revision to use for the publicationNo. Defaults to ${ivy.deliver.revision} if set, or the revision resolved if set, or a timestamp
pubbranchthe branch to use for the publicationNo. Defaults to ${ivy.deliver.branch} if set, or the branch resolved if set, or nothing (branch info won't be updated)
pubdatethe publication date to use for the publication. This date should be either 'now', or a date given with the following pattern: yyyyMMddHHmmssNo. Defaults to 'now'
statusthe status to use for the publicationNo. Defaults to ${ivy.status}
delivertargetthe target to call for recursive deliveryNo. No recursive delivery is done by default
validatetrue to force ivy files validation against ivy.xsd, false to force no validationNo. Defaults to default ivy value (as configured in configuration file)
replacedynamicrevtrue to replace dynamic revisions by static ones in the delivered file, false to avoid this replacement (since 1.3)No. Defaults to true
replaceForcedRevtrue to replace revisions (static or dynamic) by the revision of the resolver in forced mode, false to avoid this replacement (since 2.2)No. Defaults to false
mergeif a descriptor extends a parent, merge the inherited information directly into the delivered descriptor. The extends element itself will be commented out in the delivered descriptor. (since 2.2)No. Defaults to true.
settingsRefA reference to the ivy settings that must be used by this task (since 2.0)No, 'ivy.instance' is taken by default.
confcomma-separated list of configurations to include in the delivered file. Accepts wildcards. (since 2.0)No. Defaults to all configurations
generateRevConstrainttrue to automatically generate a 'revConstraint' attribute in the deliverd file (see the dependency page for more info about this attribute), false to never generate this attribute (since 2.1.0)No. Defaults to true
+ +

Example

+Deliver an ivy file without the private configurations: +
+<deliver conf="*(public)" /> 
+
+ +
+
+ + + + + + + + + + + + +
+ + Added: ant/ivy/site/target/history/2.2.0/use/findrevision.html URL: http://svn.apache.org/viewvc/ant/ivy/site/target/history/2.2.0/use/findrevision.html?rev=1005260&view=auto ============================================================================== --- ant/ivy/site/target/history/2.2.0/use/findrevision.html (added) +++ ant/ivy/site/target/history/2.2.0/use/findrevision.html Wed Oct 6 21:25:29 2010 @@ -0,0 +1,156 @@ + + + + + + + + +findrevision | Apache Ivy + + + + + + + + + + +
+ + + + + + + + + + + + + +
+ +
+ +
+ + + + +
+ + +
+ + +
+ + + + + + + +
+
+ +

findrevision

+
since 1.4 +Finds the latest revision of a module matching a given version constraint.

A version constraint is what is used when declaring a dependency on a module.
If the module is not found the property is not set.

Attributes

+ + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
organisationthe organisation of the module to findYes
modulethe the name of the module to findYes
branchthe branch of the module to findNo, defaults to the default branch for the given module
revisionthe revision constraint to applyYes
propertythe property to set with the found revisionNo, defaults to ivy.revision
settingsRefA reference to the ivy settings that must be used by this task (since 2.0)No, 'ivy.instance' is taken by default.
+

Examples

+
+<ivy:findrevision organisation="apache" module="ivy" revision="latest.integration"/>
+
+finds the latest version of ivy available in the repository and sets the property ivy.revision according to what was found.


+ +
+<ivy:findrevision organisation="apache" module="ivy" revision="1.0+"/>
+
+same as above but only with 1.0 sub versions.


+
+
+ + + + + + + + + + + + +
+ + Added: ant/ivy/site/target/history/2.2.0/use/info.html URL: http://svn.apache.org/viewvc/ant/ivy/site/target/history/2.2.0/use/info.html?rev=1005260&view=auto ============================================================================== --- ant/ivy/site/target/history/2.2.0/use/info.html (added) +++ ant/ivy/site/target/history/2.2.0/use/info.html Wed Oct 6 21:25:29 2010 @@ -0,0 +1,201 @@ + + + + + + + + +info | Apache Ivy + + + + + + + + + + +
+ + + + + + + + + + + + + +
+ +
+ +
+ + + + +
+ + +
+ + +
+ + + + + + + +
+
+ +

info

+
since 1.4 +The info task ease the access to some essential data contained in an ivy file without performing a dependency resolution.

The information is retrieved by setting ant properties: + + + + + + + + + + + + + + + + + + + + + +
PropertyDescription
ivy.organisationThe organisation of the module, as found in the info tag of the ivy file parsed.
ivy.moduleThe name of the module, as found in the info tag of the ivy file parsed.
ivy.branchThe branch of the module if any, as found in the info tag of the ivy file parsed.
ivy.revisionThe revision of the module, as found in the info tag of the ivy file parsed.
ivy.statusThe status of the module, as found in the info tag of the ivy file parsed.
ivy.publicationThe publication time of the module, as found in the info tag of the ivy file parsed. (Since 2.2)
ivy.extra.[any extra attribute]Corresponding extra attribute value, as found in the info tag of the ivy file parsed
ivy.configurationsA comma separated list of configurations of the module, as declared in the configurations section
ivy.public.configurationsA comma separated list of public configurations of the module, as declared in the configurations section
ivy.configuration.[config name].descFor each configuration with a description, a property is created containing this description. (Since 2.2)
ivy.artifact.[index].nameFor each published artifact, a property is created containing its name. (Since 2.2)
ivy.artifact.[index].typeFor each published artifact, a property is created containing its type. (Since 2.2)
ivy.artifact.[index].extFor each published artifact, a property is created containing its ext. (Since 2.2)
ivy.artifact.[index].confFor each published artifact, a property is created containing its conf. (Since 2.2)
ivy.artifact.[index].extra.[any extra attribute]For each extra attribute of the published artifact, a property is created containing its name. (Since 2.2)
+
+since 2.0 + +Since Ivy 2.0 this task has been enhanced to allow you to retrieve information about ivy modules in a repository. Instead of specifying a local ivy file you may specify the organisation, module, revision pattern and (optionally) the branch of the ivy module in the repository you wish to retrieve the information for.

The revision pattern is what is used when declaring a dependency on a module, identical to how the findrevision task works. In fact this task can now be used in place of the findrevision task.

If no matching module is found then no property values are set.

You may now also set the property attribute to change the first part of the property names that are set by this task e.g. if you set the property attribute to 'mymodule' this task will set the ant properties mymodule.organisation, mymodule.module, mymodule.revision etc.

since 2.2 + +Since Ivy 2.2 this task has been enhanced to also retrieve detailed information about the module's published artifacts, as well as the publication time.

Attributes

+ + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
filethe ivy file to parseYes, if you wish to parse an ivy file.
No, if you are retrieving information about a module from an ivy repository.
organisationthe organisation of the module to find (since 2.0)No, if you wish to parse an ivy file.
Yes, if you are retrieving information about a module from an ivy repository.
modulethe the name of the module to find (since 2.0)No, if you wish to parse an ivy file.
Yes, if you are retrieving information about a module from an ivy repository.
branchthe branch of the module to find (since 2.0)No, defaults to the default branch for the given module if you are retrieving information about a module from an ivy repository.
revisionthe revision constraint to apply (since 2.0)No, if you wish to parse an ivy file.
Yes, if you are retrieving information about a module from an ivy repository.
propertythe name to use as the base of the property names set by this task (since 2.0)No, will default to 'ivy' if not set.
settingsRefA reference to the ivy settings that must be used by this task (since 2.0)No, 'ivy.instance' is taken by default.
+

Examples

+Given this ivy.xml file: +
+<ivy-module version="1.0" xmlns:e="http://ant.apache.org/ivy/extra">
<info organisation="apache"
module="info-all"
branch="trunk"
revision="1.0"
status="release"
e:myextraatt="myvalue"
/>
<configurations>
<conf name="default" />
<conf name="test" />
<conf name="private" visibility="private"/>
</configurations>
<publications>
<artifact name="thing1" type="jar" ext="jar" conf="default" e:data="main"/>
<artifact name="thing2" type="jar" ext="jar" conf="default" e:data="client"/>
</publi cations>
<dependencies>
<dependency org="org1" name="mod1.2" rev="2.0"/>
</dependencies>
</ivy-module> +
+
+<ivy:info file="${basedir}/path/to/ivy.xml" />
+
+Parses ${basedir}/path/to/ivy.xml and set properties as described above accordingly: +
+ivy.organisation=apache
ivy.module=info-all
ivy.branch=trunk
ivy.revision=1.0
ivy.status=release
ivy.extra.myextraatt=myvalue
ivy.configurations=default, test, private
ivy.public.configurations=default, test
ivy.artifact.1.name=thing1
ivy.artifact.1.type=jar
ivy.artifact.1.ext=jar
ivy.artifact.1.conf=default
ivy.artifact.1.extra.data=main
ivy.artifact.2.name=thing2
ivy.artifact.2.type=jar
ivy.artifact.2.ext=jar
ivy.artifact.2.conf=default
ivy.artifact.2.extra.data=client +
+Given the same ivy module in a repository: +
+<ivy:info organisation="apache" module="info-all" revision="1.0" />
+
+will set the exact same set of properties as above. Using: +
+<ivy:info organisation="apache" module="info-all" revision="1.0" property="infotest"/>
+
+will set: +
+infotest.organisation=apache
infotest.module=info-all
infotest.branch=trunk
infotest.revision=1.0
infotest.status=release
infotest.extra.myextraatt=myvalue
infotest.configurations=default, test, private
infotest.public.configurations=default, test
infotest.artifact.1.name=thing1
infotest.artifact.1.type=jar
infotest.artifact.1.ext=jar
infotest.artifact.1.conf=default
infotest.artifact.1.extra.data=main
infotest.artifact.2.name=thing2
infotest.artifact.2.type=jar
infotest.artifact.2.ext=jar
infotest.artifact.2.conf=default
infotest.artifact.2.extra.data=client +
+ + +
+
+ + + + + + + + + + + + +
+ +