Eclipse update packing tool readme

# Eclipse update packing tool

### Overview

The update packing tool processes a hierarchy of arbitrarily nested JARs and ZIP files. It is a generic utility that performs a depth first traversal of a nested hierarchy of ZIPs and JARs, performs various commands on each of the JARs in the hierarchy, and then rebuilds the same hierarchy of ZIPs and JARs again. Currently its main functions are:

- Packing JARs using the Java 1.5 pack200 command.
- Unpacking PACK.GZs using the Java 1.5 unpack200 command.
- Normalizing JARs for future compression by pack200. This is accomplished by running the pack200 command with the `--repack` command line argument.
- Signing JARs to allow for authentication of the origin of JARs. This is accomplished by running a supplied command (typically the command will just be a wrapper around the Java jarsigner tool).

The packing tool is used in the following contexts:

- During a PDE build, to prepare JARs for uploading to an Eclipse update site. In this usage, it is used to both nomalize JAR contents (pack200 -repack), and sign JARs.
- On an update site, to convert traditional JAR content into the compressed pack200 format.
- From an Eclipse client application during update, to convert compressed pack200 format content into executable JAR files.

### Tool usage

To run the packing tool, you need a 1.5 JRE installed. The tool is run by invoking Java as follows:

    	java jarprocessor.jar [options] input

Where `input` is either a zip file, a directory, or a JAR (or a pack.gz file). All files ending in ".jar" or ".pack.gz" in the provided zip or directory hierarchy will be processed. The following additional command line arguments are supported:

- -repack : Normalize the jars using pack200 `--repack`
- -sign <cmd> : signs the jars by executing the provided command. The command will be provided a single argument that will be the full path of the JAR to process.
- -pack : for each input in JAR form, produce a corresponding output in packed form. For an input "a.jar", the output is a.jar.pack.gz.
- -unpack : for each input in packed form, produce a corresponding output in unpacked form. For an input "a.jar.pack.gz", the output is "a.jar". -unpack is mutually exclusive with -repack, -pack and -sign.
- -outputDir <dir> : The directory to put the tool's output into. If the input was a zip file, then an output zip file will be created containg all the output files. If the input was a directory, for each input file there is a corresponding output file in the output directory. By default the current working directory is used. If the input is in the same directory as the output, the input files may be overwritten.

Additionally, when the input is a zip file, it may contain a file called `pack.properties`. The pack.properties file supports the following values:

- pack.excludes = jarName[, jarName]* : A comma-delimited list of JARs that should not be packed or repacked.
- sign.excludes = jarName[, jarName]* : A comma-delimited list of JARs that should not be signed.
- <jarname>.pack.args = option[, option]* : A comma-delimited list of additional arguments that should be passed to pack200 when packing any jar with name <jarname>.

Copyright (c) IBM Corporation and others 2006. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0.