<b>Tag:</b> triggers <span class="since">since 1.4</span> <span class="tagdoc" id="ivysettings.triggers">Defines a list of triggers to activate on some Ivy events.</span> A trigger is an action which is performed whenever a particular event occurs. Ivy supports 3 type of triggers out of the box: <ul> <li>ant-call</li> calls a target in the same build as the original one whenever a particular event occurs. <li>ant-build</li> calls an ant build which may be in another ant build script. <li>log</li> echo a message, usually in a file </ul> If you want to use a different trigger, you can <a href="../extend.html">implement your own</a>. The event available in Ivy are the following ones: <table class="ivy-children"> <thead> <tr><th>Name</th><th>Attributes</th><th>Description</th></tr> </thead> <tbody> <tr><td>pre-resolve</td> <td> <ul> <li>organisation</li>the organisation of the module for which the dependencies will be resolved <li>module</li>the name of the module for which the dependencies will be resolved <li>revision</li>the revision of the module for which the dependencies will be resolved <li>conf</li>comma separated list of configurations which will be resolved </ul> </td> <td>Fired at the beginning of the resolve process, before a module dependencies and transitive dependencies are resolved.</td> </tr> <tr><td>pre-resolve-dependency</td> <td> <ul> <li>organisation</li>the organisation of the dependency resolved <li>module</li>the name of the dependency resolved <li>req-revision</li>the requested revision for the dependency <span class="since">since 2.0</span> (provided for consistency with post-resolve-dependency) <li>req-revision-default</li>the default requested revision constraint for the dependency <span class="since">since 2.0</span> <li>req-revision-dynamic</li>the requested revision dynamic constraint for the dependency <span class="since">since 2.0</span> <li>revision</li>the requested revision for the dependency <li>resolver</li>the name of the resolver used to resolve the dependency </ul> </td> <td>Fired before each dependency is resolved. In this case resolved means resolving the actual revision if the requested revision is a version constraint and not a static version, and downloading all necessary metadata information.</td> </tr> <tr><td>post-resolve-dependency</td> <td> <ul> <li>organisation</li>the organisation of the dependency resolved <li>module</li>the name of the dependency resolved <li>req-revision</li>the requested revision for the dependency <span class="since">since 2.0</span> <li>req-revision-default</li>the default requested revision constraint for the dependency <span class="since">since 2.0</span> <li>req-revision-dynamic</li>the requested revision dynamic constraint for the dependency <span class="since">since 2.0</span> <li>revision</li>the revision of the dependency resolved, or the requested revision if the resolution was not successful <li>resolved</li>true if the resolution was successful, false otherwise <li>duration</li>the time elapsed to resolve the dependency (in ms) <span class="since">since 2.0</span> <li>resolver</li>the name of the resolver used to resolve the dependency <li>any extra attribute</li>all extra attributes found on the info tag of the resolved dependency are available <span class="since">since 2.0</span> </ul> </td> <td>Fired after each dependency is resolved</td> </tr> <tr><td>post-resolve</td> <td> <ul> <li>organisation</li>the organisation of the module for which the dependencies have been resolved <li>module</li>the name of the module for which the dependencies have been resolved <li>revision</li>the revision of the module for which the dependencies have been resolved <li>conf</li>comma separated list of configurations resolved <li>resolve-id</li>the identifier of the resolution process <span class="since">since 2.0</span> <li>nb-dependencies</li>total number of dependencies, including transitive and evicted ones <span class="since">since 2.0</span> <li>nb-artifacts</li>total number of artifacts resolved, excluding metadata artifacts <span class="since">since 2.0</span> <li>resolve-duration</li>the time (in ms) elapsed to resolve dependencies, before dowloading artifacts <span class="since">since 2.0</span> <li>download-duration</li>the time (in ms) elapsed to download all artifacts, excluding metadata artifacts downloaded during the first phase of the resolution process <span class="since">since 2.0</span> <li>download-size</li>the total size (in bytes) of all downloaded artifacts, excluding metadata artifacts. Only artifacts actually downloaded (not in cache or used from their original location) are considered <span class="since">since 2.0</span> </ul> </td> <td>Fired at the end of the resolve process, when all module dependencies have been resolved</td> </tr> <tr><td>pre-download-artifact</td> <td> <ul> <li>organisation</li>the organisation of the artifact which is about to be downloaded <li>module</li>the name of the module of the artifact which is about to be downloaded <li>revision</li>the revision of the the artifact which is about to be downloaded <li>artifact</li>the name of the the artifact which is about to be downloaded <li>type</li>the type of the the artifact which is about to be downloaded <li>ext</li>the extension of the the artifact which is about to be downloaded <li>metadata</li>true if the artifact to be downloaded is a metadata artifact, false for published artifacts <span class="since">since 2.0</span> <li>resolver</li>the name of the resolver used to download the artifact <li>origin</li>the origin location from which it will be downloaded <li>local</li>true if it's a local artifact, false otherwise </ul> </td> <td>Fired before an artifact is downloaded from a repository to the cache</td> </tr> <tr><td>post-download-artifact</td> <td> <ul> <li>organisation</li>the organisation of the artifact which was just downloaded <li>module</li>the name of the module of the artifact which was just downloaded <li>revision</li>the revision of the the artifact which was just downloaded <li>artifact</li>the name of the the artifact which was just downloaded <li>type</li>the type of the the artifact which was just downloaded <li>ext</li>the extension of the the artifact which was just downloaded <li>metadata</li>true if the downloaded artifact is a metadata artifact, false for published artifacts <span class="since">since 2.0</span> <li>resolver</li>the name of the resolver used to download the artifact <li>origin</li>the origin location from which it was downloaded <li>local</li>true if it's a local artifact, false otherwise <li>size</li>the size in bytes of the downloaded artifact <li>duration</li>the time elapsed to download the artifact (in ms) <span class="since">since 2.0</span> <li>file</li>the file to which it has been downloaded </ul> </td> <td>Fired after an artifact has been downloaded from a repository to the cache</td> </tr> <tr><td>pre-retrieve <br/><span class="since">since 2.0</span></td> <td> <ul> <li>organisation</li>the organisation of the module for which the dependencies will be retrieved <li>module</li>the name of the module for which the dependencies will be retrieved <li>revision</li>the revision of the module for which the dependencies will be retrieved <li>conf</li>comma separated list of configurations which will be retrieved <li>symlink</li>true if Ivy will use symbolic links instead of copies on supported platforms, false otherwise <li>sync</li>true if the retrieve process will be performed in sync mode, false otherwise </ul> </td> <td>Fired at the beginning of the retrieve process.</td> </tr> <tr><td>post-retrieve <br/><span class="since">since 2.0</span></td> <td> <ul> <li>organisation</li>the organisation of the module for which the dependencies have been retrieved <li>module</li>the name of the module for which the dependencies will be retrieved <li>revision</li>the revision of the module for which the dependencies have been retrieved <li>conf</li>comma separated list of configurations which have been retrieved <li>symlink</li>true if Ivy used symbolic links instead of copies on supported platforms, false otherwise <li>sync</li>true if the retrieve process has been performed in sync mode, false otherwise <li>duration</li>the time elapsed in ms during the retrieve process <li>size</li>the total size of artifacts which have actually been copied (or symlinked) <li>nbCopied</li>the number of artifacts copied or symlinked <li>nbUptodate</li>the number of artifacts which were already present and up to date at the destination location </ul> </td> <td>Fired at the end of the retrieve process.</td> </tr> <tr><td>pre-publish-artifact <br/><span class="since">since 2.0</span></td> <td> <ul> <li>organisation</li>the organisation of the artifact which is about to be published <li>module</li>the name of the module of the artifact which is about to be published <li>revision</li>the revision of the the artifact which is about to be published <li>artifact</li>the name of the the artifact which is about to be published <li>type</li>the type of the the artifact which is about to be published <li>ext</li>the extension of the the artifact which is about to be published <li>resolver</li>the name of the resolver into which the artifact is about to be published <li>file</li>the absolute path of the source file for the artifact <li>overwrite</li>"true" if the new data will overwrite existing artifacts, "false" otherwise </ul> </td> <td>Fired before an artifact is published into a repository</td> </tr> <tr><td>post-publish-artifact <br/><span class="since">since 2.0</span></td> <td> <ul> <li>organisation</li>the organisation of the artifact that was published <li>module</li>the name of the module of the artifact that was published <li>revision</li>the revision of the the artifact that was published <li>artifact</li>the name of the the artifact that was published <li>type</li>the type of the the artifact that was published <li>ext</li>the extension of the the artifact that was published <li>resolver</li>the name of the resolver into which the artifact was published <li>file</li>the absolute path of the source file for the artifact <li>overwrite</li>"true" if the new data overwrote existing artifacts, "false" otherwise <li>status</li>"successful" if the artifact published successfully; "failed" if the artifact failed to publish, or if the status is unknown </ul> </td> <td>Fired after an artifact is published into a repository. Note that this event is fired whether or not the publication succeeded. The "status" property can be checked to verify success.</td> </tr> </tbody> </table> The child tag used for the dependency resolver must be equal to a name of a trigger type (either built-in or added with the typedef tag). <h1>Child elements</h1> <table class="ivy-children"> <thead> <tr><th class="ivy-chld">Element</th><th class="ivy-chld-desc">Description</th><th class="ivy-chld-card">Cardinality</th></tr> </thead> <tbody> <tr><td>any trigger</td><td>adds a trigger to the list of registered triggers</td> <td>1..n</td></tr> </tbody> </table> <h1>Built-in Triggers</h1> Ivy comes with 3 built-in triggers: <table class="ivy-attributes"> <thead> <tr><th>Name</th><th>Description</th></tr> </thead> <tbody> <tr><td>ant-build</td><td>Triggers an ant build. Note that by default the ant build is triggered only once per build file, the property onlyonce can be set to false to change this.</td></tr> <tr><td>ant-call</td><td>Calls a target in the current ant build.</td></tr> <tr><td>log</td><td>Logs a message on the console or in a log file.</td></tr> </tbody> </table> <h1><a name="common">Common attributes</a></h1> All triggers share some common attributes detailed here. Among these attributes, you will find how to select when the trigger should be performed. You have to provide an event name, which is simple, but you can also use a filter expression. The syntax for this expression is very simple and limited: you can use the = operator to compare an attribute (left operande) with a value (right operande). you can use AND OR NOT as boolean operators you cannot use parenthesis to change the precedence <table class="ivy-attributes"> <thead> <tr><th class="ivy-att">Attribute</th><th class="ivy-att-desc">Description</th><th class="ivy-att-req">Required</th></tr> </thead> <tbody> <tr><td>name</td><td>the name of the trigger for identification purpose only</td> <td>Yes</td> </tr> <tr><td>event</td><td>the name of the event on which the trigger should be performed</td> <td>Yes</td> </tr> <tr><td>filter</td><td>a filter expression used to restrict when the trigger should be performed</td> <td>No, defaults to no filter</td> </tr> </tbody> </table> <h1>Examples</h1> <code type="xml"> <triggers> <ant-build antfile="${ivy.settings.dir}/[module]/build.xml" target="publish" event="pre-resolve-dependency" filter="revision=latest.integration"/> </triggers> </code> Triggers an ant build of the ant file ${ivy.settings.dir}/[module]/build.xml (where [module] is replaced by the name of the dependency resolved) with the target "publish", just before resolving a dependency with a latest.integration revision. Note that by default the ant build is triggered only once per build file. See below to see how to trigger the build more than once. <hr/> <code type="xml"> <triggers> <ant-build antfile="${ivy.settings.dir}/[module]/build.xml" target="publish" event="pre-resolve-dependency" filter="revision=latest.integration" onlyonce="false" /> </triggers> </code> Same as before, but this time the builds will be triggered as many time as the dependency is resolved, instead of only once. <hr/> <code type="xml"> <triggers> <ant-call target="unzip" prefix="dep" event="post-download-artifact" filter="type=zip AND status=successful"/> </triggers> </code> Triggers an ant call of the target unzip just after downloading a zip artifact, prefixing all parameters to the target with 'dep'. Here is how the target can look like: <code type="xml"> <target name="unzip"> <echo> unzipping artifact: organisation=${dep.organisation} module=${dep.module} revision=${dep.revision} artifact=${dep.artifact} type=${dep.type} ext=${dep.ext} origin=${dep.origin} local=${dep.local} size=${dep.size} file=${dep.file} </echo> <mkdir dir="${basedir}/out"/> <unzip src="${dep.file}" dest="${basedir}/out"/> </target> </code> <hr/> <code type="xml"> <triggers> <log file="ivy.log" message='downloaded "${origin}" to "${file}" (${duration}ms - ${size}B)' event="post-download-artifact" filter="status=successful"/> </triggers> </code> Logs any successful artifact download, with information on the source and destination, and details on download size and duration. The file attribute is optional, the log trigger will output messages to console if it isn't provided.