asciidoc/resolver/packager.adoc

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

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

= 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__*)

[ivysettings.resolvers.packager]#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 link:../concept{outfilesuffix}#cache[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 link:https://ant.apache.org/[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 link:url{outfilesuffix}[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 link:../concept{outfilesuffix}#cache[Ivy's caching support] to avoid repeated execution of the packaging instructions.

== Attributes

This resolver shares the link:../settings/resolvers{outfilesuffix}#common[common attributes] of standard resolvers, plus the following:

[options="header",cols="15%,50%,35%"]
|=======
|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


[options="header"]
|=======
|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


[source, xml]
----

<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 `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 link:http://testng.org/[TestNG]:

[source, xml]
----

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

[options="header",cols="15%,50%"]
|=======
|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.

[options="header"]
|=======
|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:

[options="header",cols="15%,50%,35%"]
|=======
|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:

[options="header",cols="15%,50%,35%"]
|=======
|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:

[options="header",cols="15%,50%,35%"]
|=======
|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
.2+|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 link:https://commons.apache.org/proper/commons-email/[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).

[source]
----

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

----