Apache™ > Apache Ant™ > Apache Ivy™ > Documentation (2.4.0) > Reference > Settings Files > resolvers > Packager resolver

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"
         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>

Defines a packager resolver which points to the Ivy RoundUp online repository. Builds will occur in a subdirectory of

${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">

    <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>

Of course, packaging instructions must produce artifacts consistent with those listed in the associated ivy.xml file.

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 https://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>