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.

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

  1. all downloaded archives have verified SHA1 checksums (including cached resources); and

  2. 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 http://ivyroundup.googlecode.com/ 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 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:

<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 that the 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 Maven 2 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.

Maven 2 Resources

Special support is included for Maven 2 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 Maven 2 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 Maven 2 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>