mirror of https://github.com/apache/ant-ivy
358 lines
20 KiB
HTML
358 lines
20 KiB
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>
|
|
<script type="text/javascript">var xookiConfig = {level: 1};</script>
|
|
<script type="text/javascript" src="../xooki/xooki.js"></script>
|
|
</head>
|
|
<body>
|
|
<textarea id="xooki-source">
|
|
<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 following events are available in Ivy:
|
|
<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 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-retrieve-artifact <br/><span class="since">since 2.1</span></td>
|
|
<td>
|
|
<ul>
|
|
<li>organisation</li>the organisation of the artifact which is about to be retrieved
|
|
<li>module</li>the name of the module of the artifact which is about to be retrieved
|
|
<li>revision</li>the revision of the the artifact which is about to be retrieved
|
|
<li>artifact</li>the name of the the artifact which is about to be retrieved
|
|
<li>type</li>the type of the the artifact which is about to be retrieved
|
|
<li>ext</li>the extension of the the artifact which is about to be retrieved
|
|
<li>metadata</li>true if the retrieved artifact is a metadata artifact, false for published artifacts
|
|
<li>size</li>the size in bytes of the retrieved artifact
|
|
<li>from</li>the absolute path from which it will be retrieved (usually a location in cache)
|
|
<li>to</li>the absolute path to which it will be retrieved
|
|
</ul>
|
|
</td>
|
|
<td>Fired before an artifact is retrieved from the cache to a local location</td>
|
|
</tr>
|
|
<tr><td>post-retrieve-artifact <br/><span class="since">since 2.1</span></td>
|
|
<td>
|
|
<ul>
|
|
<li>organisation</li>the organisation of the artifact which has just been retrieved
|
|
<li>module</li>the name of the module of the artifact which has just been retrieved
|
|
<li>revision</li>the revision of the the artifact which has just been retrieved
|
|
<li>artifact</li>the name of the the artifact which has just been retrieved
|
|
<li>type</li>the type of the the artifact which has just been retrieved
|
|
<li>ext</li>the extension of the the artifact which has just been retrieved
|
|
<li>metadata</li>true if the retrieved artifact is a metadata artifact, false for published artifacts
|
|
<li>size</li>the size in bytes of the retrieved artifact
|
|
<li>from</li>the absolute path from which it has just been retrieved (usually a location in cache)
|
|
<li>to</li>the absolute path to which it has just been retrieved
|
|
</ul>
|
|
</td>
|
|
<td>Fired after an artifact is retrieved from the cache to a local location</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.</textarea>
|
|
<script type="text/javascript">xooki.postProcess();</script>
|
|
</body>
|
|
</html>
|