GNU-style options for the Jar Tool

[Chris Hegarty]

Please reply-to core-libs-dev at openjdk.java.net, which is more appropriate for
discussion on Jar Tool.

-Chris.

On 19 Jan 2016, at 16:54, Chris Hegarty <chris.hegarty at oracle.com> wrote:

> GNU-style options for Jar Tool
> 
> Prompted by the impending addition of new options for both multi-release jars
> and jigsaw, it became immediately obvious that we were running out of single
> characters that could be used to represent these new options. I'd like to 
> propose an update to the Jar Tool CLI to accept GNU-style options ( all short
> forms being compatible with the existing current options ), so that we can
> evolve the CLI in a reasonable fashion going forward.
> 
> For example:
> # Create an archive called classes.jar with two class files:
> jar --create --file classes.jar Foo.class Bar.class
> # Create an archive using an existing manifest, with all the files in foo/:
> jar --create --file classes.jar --manifest mymanifest -C foo/ .
> 
> The complete output of '--help' can be seen below [*]
> 
> Short forms are the same as existing current options.
> 
> It was suggested over on jigsaw-dev that the help output could drop the 
> compatibility interface. Only printing it if '--help:compatility', or similar.
> 
> http://cr.openjdk.java.net/~chegar/jartool.options/
> 
> -Chris
> 
> P.S. jigsaw and multi-release jars will add the current list of exiting
> options.
> 
> [*]  ( there may be some formatting issue in email )
> $ ./jdk/bin/jar --help
> Usage: jar [OPTION...] [-C dir] files ...
> jar creates an archive for classes and resources, and can manipulate or
> restore individual classes or resources from an archive.
> 
> Examples:
> # Create an archive called classes.jar with two class files:
> jar --create --file classes.jar Foo.class Bar.class
> # Create an archive using an existing manifest, with all the files in foo/:
> jar --create --file classes.jar --manifest mymanifest -C foo/ .
> 
> 
>  Main operation mode:
>    -c, --create               Create the archive
>    -i, --generate-index=FILE  Generate index information for the specified jar
>                               archives
>    -t, --list                 List the table of contents for the archive
>    -u, --update               Update an existing jar archive
>    -x, --extract              Extract named (or all) files from the archive
> 
>  Operation modifiers valid in any mode:
> 
>    -C DIR,                    Change to the specified directory and include the
>                               following file
>    -f, --file=FILE            The archive file name
>    -v, --verbose              Generate verbose output on standard output
> 
>   Operation modifiers valid only in create mode:
>    -n, --pack200              Perform Pack200 normalization after creating a
>                               new archive
> 
>   Operation modifiers valid only in create and update mode:
>    -e, --main-class=CLASSNAME The application entry point for stand-alone
>                               applications bundled into a modular, or executable,
>                               jar archive
>    -m, --manifest=FILE        Include the manifest information from the given
>                               manifest file
>    -M, --no-manifest          Do not create a manifest file for the entries
> 
>   Operation modifiers valid only in create, update, and generate-index mode:
>    -0, --no-compress          Store only; use no ZIP compression
> 
>   Other options:
>    -?, --help                 give this help list
>        --version              print program version
> 
>  Mandatory or optional arguments to long options are also mandatory or optional
>  for any corresponding short options.
> 
> 
> Compatibility Interface:
> 
> Usage: jar {ctxui}[vfmn0PMe] [jar-file] [manifest-file] [entry-point] [-C dir] files ...
> Options:
>    -c  create new archive
>    -t  list table of contents for archive
>    -x  extract named (or all) files from archive
>    -u  update existing archive
>    -v  generate verbose output on standard output
>    -f  specify archive file name
>    -m  include manifest information from specified manifest file
>    -n  perform Pack200 normalization after creating a new archive
>    -e  specify application entry point for stand-alone application 
>        bundled into an executable jar file
>    -0  store only; use no ZIP compression
>    -P  preserve leading '/' (absolute path) and ".." (parent directory) components from file names
>    -M  do not create a manifest file for the entries
>    -i  generate index information for the specified jar files
>    -C  change to the specified directory and include the following file
> If any file is a directory then it is processed recursively.
> The manifest file name, the archive file name and the entry point name are
> specified in the same order as the 'm', 'f' and 'e' flags.
> 
> Example 1: to archive two class files into an archive called classes.jar: 
>       jar cvf classes.jar Foo.class Bar.class 
> Example 2: use an existing manifest file 'mymanifest' and archive all the
>           files in the foo/ directory into 'classes.jar': 
>       jar cvfm classes.jar mymanifest -C foo/ .
> 
>