GNU-style options for the Jar Tool

[Chris Hegarty]

> On 20 Jan 2016, at 22:27, Dmitry Samersoff <dmitry.samersoff at oracle.com> wrote:
> 
> Chris,
> 
> (slightly offtopic)
> 
> Is there any plan to introduce standard command line parsing routine?

Glad you brought this up Dmitry.

We have been using JOpt Simple [1] in jigsaw/jake [2] for parsing
command line arguments for any new tools. I plan to propose to bring
this into the JDK 9 mainline soon. Where possible, any new tools should
consider using it.

Given the compatibility constrains of existing command line arguments
in the Jar Tool, JOpt Simple was not a good fit.  

-Chris.

[1] https://pholser.github.io/jopt-simple/ <https://pholser.github.io/jopt-simple/>
[2] http://hg.openjdk.java.net/jigsaw/jake/jdk/file/tip/src/jdk.internal.opt/share/classes

> e.g.
> http://hg.openjdk.java.net/jdk9/hs-rt/hotspot/file/tip/src/jdk.hotspot.agent/share/classes/sun/jvm/hotspot/SAGetopt.java
> 
> -Dmitry
> 
> On 2016-01-19 19:54, Chris Hegarty 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/ .
>> 
>> 
> 
> 
> -- 
> Dmitry Samersoff
> Oracle Java development team, Saint Petersburg, Russia
> * I would love to change the world, but they won't give me the sources.