- Documentation (2.0.0)
- Release Notes
- Tutorials
- Reference
- Developer doc
Packager resolver
| Tag | packager |
| Handle latest | yes with http urls (and apache server) and with file urls, no with other urls |
| Handle publish | no |
Since 2.0.
This resolver accesses ivy files and "packaging instructions" from an online "packager" repository. "Packager" repositories contain no actual artifacts. To get the artifacts, the packaging instructions are downloaded from the repository and executed locally. These instructions specify additional resource(s) to download and how to create the artifacts from them, for example, by downloading a project's original distribution archive directly from their web site and extracting the desired artifacts.
Packager repositories allow the creation of Ivy repositories that require neither the participation of any of the modules' creators nor setting up a huge mirror site. One such repository on the web is Ivy RoundUp. Of course, private packager repositories are feasible as well.
The Packager resolver supports a "resource cache", where downloaded archives can be stored to avoid duplicate downloads. This cache is entirely separate from the normal Ivy cache: it is "private" to the Packager resolver, and it stores unmodified original software archives, not Ivy artifacts. See the resourceCache attribute below for details.
The packaging instructions are contained in "packager.xml" in a simple XML format. At resolve time this file gets converted into a "build.xml" file via XSLT and then executed using ant. Therefore, ant must be available as an executable on the platform. The ant task executes in a separate ant project and so is not affected by properties, etc. that may be set in any existing ant environment in which Ivy is running. However, Ivy will define a few properties for convenience; see the "Properties" listed below.
For security reasons, the XSLT transform ensures that (a) all downloaded archives have verified SHA1 checksums (including cached resources); and (b) only a very limited set of ant tasks can be performed during the artifact "build" phase; currently these include move, copy, mkdir, zip, unzip, tar, and untar (this restriction may be overridden however; see below).
The Packager resolver is based on the URL resolver and is configured similarly, except the artifact child tags specify where to find the packager.xml files, rather than the artifacts themselves.
Because the packaging process is relatively slow, it is important to use Ivy's caching support to avoid repeated execution of the packaging instructions.
Attributes
This resolver shares the common attributes of standard resolvers, plus the following:| Attribute | Description | Required |
|---|---|---|
| buildRoot | Defines the root of the temporary build directory hierarchy | Yes |
| resourceCache | Directory where downloaded resources should be cached | No; defaults to none |
| resourceURL | Ivy pattern that specifies a base URL to use for downloading all resources; overrides the URLs in the packaging instructions | No; defaults to none |
| restricted | True if this resolver should only allow "safe" ant tasks in the packaging instructions. Warning: setting restricted to false creates a security problem due to ant tasks like delete, exec, etc. Do not use this setting when your configuration points to an untrusted repository. | No; defaults to true |
| verbose | True to run ant with the -verbose flag | No; defaults to false |
| quiet | True to run ant with the -quiet flag | No; defaults to false |
| validate | True if this resolver should validate (via XSD) the downloaded XML packaging instructions | No; defaults to true |
| preserveBuildDirectories | True if this resolver should not delete the temporary build directories in which the ant tasks are executed (for debugging purposes) | No; defaults to false |
Setting a resourceURL will cause the resolver to override the URLs for resources specified by the packaging instructions. Instead, all resources will be downloaded from an URL constructed by first resolving the resourceURL pattern into a base URL, and then resolving the resource filename relative to that base URL. In other words, the resourceURL pattern specifies the URL "directory", so it should always end in a forward slash.
If a resourceURL download fails, the resolver will fall back to the original URL from the packaging instructions.
Configure a resourceURL in situations where you don't want to rely on (or wait for) the web sites configured in the packaging instructions, and have access to a better (perhaps private) mirror site.
Child elements
| Element | Description | Cardinality |
|---|---|---|
| ivy | Defines a pattern for ivy.xml files, using the pattern attribute | 1..n |
| artifact | Defines a pattern for packager.xml files, using the pattern attribute | 1..n |
Examples
<packager name="ivyroundup"Defines a packager resolver which points to the Ivy RoundUp online repository. Builds will occur in a subdirectory of
buildRoot="${user.home}/.ivy2/packager/build"
resourceCache="${user.home}/.ivy2/packager/cache"
resourceURL="ftp://mirror.example.com/pub/resources/[organisation]/[module]/">
<ivy pattern="http://ivyroundup.googlecode.com/svn/trunk/repo/modules/[organisation]/[module]/[revision]/ivy.xml"/>
<artifact pattern="http://ivyroundup.googlecode.com/svn/trunk/repo/modules/[organisation]/[module]/[revision]/packager.xml"/>
</packager>
${user.home}/.ivy2/packager/build downloaded resources will be cached in ${user.home}/.ivy2/packager/cache and the mirror site ftp://mirror.example.com/pub/resources/[organisation]/[module]/will be tried first for all resources.
Packaging Instructions
The goal of the packaging instructions is to download the required archives, extract the artifacts, and put the artifacts into a subdirectory. Each artifact should be written to artifacts/[type]s/[artifact].[ext] when the ant build completes.
Below is an example of packaging instructions for TestNG 2.5:
<packager-module version="1.0">Of course, packaging instructions must produce artifacts consistent with those listed in the associated ivy.xml file.
<property name="name" value="${ivy.packager.module}"/>
<property name="version" value="${ivy.packager.revision}"/>
<property name="zipname" value="${name}-${version}"/>
<resource dest="archive" url="http://testng.org/${zipname}.zip" sha1="2ea19275dc17453306f8bb780fe6ef6e9af7756b">
<url href="http://mirror.example.com/archives/${zipname}.zip"/>
<include name="${zipname}/src/main/**/*"/>
<include name="${zipname}/src/jdk15/**/*"/>
<include name="${zipname}/javadocs/**/*"/>
<include name="${zipname}/*.jar"/>
</resource>
<build>
<!-- jar -->
<move file="archive/${zipname}/${zipname}-jdk14.jar" tofile="artifacts/jars/${name}-jdk14.jar"/>
<move file="archive/${zipname}/${zipname}-jdk15.jar" tofile="artifacts/jars/${name}-jdk15.jar"/>
<!-- source -->
<zip destfile="artifacts/sources/${name}.zip">
<fileset dir="archive/${zipname}/src/main">
<include name="**/*.java"/>
</fileset>
<fileset dir="archive/${zipname}/src/jdk15">
<include name="**/*.java"/>
</fileset>
</zip>
<!-- javadoc -->
<zip destfile="artifacts/javadocs/javadoc.zip">
<fileset dir="archive/${zipname}/javadocs"/>
</zip>
</build>
</packager-module>
Build-time properties
This resolver ensures following ant properties are defined when it executes the ant build task.| Property | Description |
|---|---|
| ivy.packager.organisation | Organization of the ivy module whose artifacts are being built |
| ivy.packager.module | Module of the ivy module whose artifacts are being built |
| ivy.packager.revision | Revision of the ivy module whose artifacts are being built |
| ivy.packager.branch | Branch of the ivy module whose artifacts are being built |
| ivy.packager.resourceCache | The configured resourceCache if any; otherwise not defined |
| ivy.packager.resourceURL | The resolved resourceURL pattern if any; otherwise not defined |
Packager XML Elements
The packager.xml document element can contain the following child tags.| Element | Description | Cardinality |
|---|---|---|
| property | Set an ant property | 0..n |
| resource | Define a resource to download and (optionally) unpack | 0..n |
| m2resource | Define a Maven2 resource to download and (optionally) unpack | 0..n |
| build | Specify ant tasks that ultimately result in each artifact being placed into artifacts/[type]s/[artifact].[ext] | 0..1 |
Which ant tasks are allowed within the build tag is controlled by the restricted configuration attribute. When true (the default), only the following ant tasks are allowed: copy, jar, mkdir, move, tar, unjar, untar, unwar, unzip, war, and zip. When false, all ant tasks are allowed.
Warning: setting restricted to false creates a security problem due to ant tasks like delete, exec, etc. Do not use this setting when your configuration points to an untrusted repository.
Resource XML Elements
The resource XML tag supports the following attributes:| Attribute | Description | Required |
|---|---|---|
| url | Primary URL for the resource | Yes |
| sha1 | SHA1 checksum of the resource | Yes |
| dest | Defines the name of the subdirectory into which the artifact should be unpacked | No; defaults to "archive" |
| tofile | Where to put the file directly; if present no extraction will be performed | No; if present, "dest" is ignored |
| filename | Name of the file to download | No; if not present, same as the last component of the URL |
| type | Type of archive: "zip", "jar", "war", "tar", "tgz", "tar.gz", "tar.bz2" | No; if not present, will be automatically determined from the filename suffix |
The resource XML tag may contain child elements. An url tag with an href attribute specifies an alternate URL for the resource (see TestNG example above). Any other tags will be included as children of an automatically generated fileset tag.
Maven2 Resources
Special support is included for maven2 resources. For these resources, use the m2resource tag instead of the resource tag. Each m2resource tag specifies one or more artifacts that are downloaded from the Maven2 repository.M2Resource XML Elements
The m2resource XML tag supports the following attributes:| Attribute | Description | Required |
|---|---|---|
| groupId | Maven group ID | No; defaults to ${ivy.packager.organisation} |
| artifactId | Maven artifact ID | No; defaults to ${ivy.packager.module} |
| version | Maven version | No; defaults to ${ivy.packager.revision} |
| repo | Maven repository URL | No; defaults to http://repo1.maven.org/maven2/ |
Each m2resource XML tag must have one or more artifact tags that define the artifacts to directly download. The URL for each artifact is constructed automatically based on the attributes in the m2resource and artifact tags.
M2Resource Artifact Attributes
The artifact children of m2resource tags support the following attributes:| Attribute | Description | Required |
|---|---|---|
| ext | Maven filename extension | No; defaults to "jar" |
| classifier | Maven classifier (e.g., "sources", "javadoc") | No; defaults to none |
| sha1 | SHA1 checksum of the resource | Yes |
| dest | Defines the name of the subdirectory into which the artifact should be unpacked | Exactly one of "dest" or "tofile" must be supplied |
| tofile | Where to put the file; no extraction will be performed | |
| type | Type of archive: "zip", "jar", "war", "tar", "tgz", "tar.gz", "tar.bz2" | No; if not present, will be automatically determined from the filename suffix |
Below is an example of packaging instructions for the Apache Commons Email module. Note that no build tag is required because all of the maven2 artifacts are usable directly (i.e., without unpacking anything).
<packager-module version="1.0">
<m2resource>
<artifact tofile="artifacts/jars/${ivy.packager.module}.jar" sha1="a05c4de7bf2e0579ac0f21e16f3737ec6fa0ff98"/>
<artifact classifier="javadoc" tofile="artifacts/javadocs/javadoc.zip" sha1="8f09630f1600bcd0472a36fb2fa2d2a6f2836535"/>
<artifact classifier="sources" tofile="artifacts/sources/source.zip" sha1="15d67ca689a792ed8f29d0d21e2d0116fa117b7e"/>
</m2resource>
</packager-module>