JEP 293: Guidelines for JDK Command-Line Tool Options

OwnerJonathan Gibbons
Created2016/07/05 22:05
Updated2016/07/11 15:04
TypeInformational
StatusCandidate
Componenttools
ScopeJDK
Discussioncore dash libs dash dev at openjdk dot java dot net
Priority4
Reviewed byAlan Bateman, Alex Buckley, Chris Hegarty, Mandy Chung, Mark Reinhold
Issue8160859

Summary

This informational JEP lays out guidelines for handling options in JDK command-line tools, including the Java launcher.

Motivation

The JDK command-line tools have evolved over the years to use a variety of different conventions for the options they provide. For example:

Even the options used to show command-line help vary between different JDK tools, with -help, -?, --help being amongst the alternatives.

When new options are added to existing tools, and when new tools are added to the platform, it is desirable that options are used in a consistent manner.

In addition, it is becoming increasingly common for the command-line tools used by developers to use the GNU-style syntax, also described in getopt(3), in which the name of an option is given by a short series of words separated with hyphens, or an equivalent single character short form.

It is time for JDK tools to start becoming more consistent both with each other and with common prevailing industry practice. This does not mean that we should change all the options supported by all our tools overnight, but we should set guidelines for the use of new options in new and existing tools.

The GNU-style syntax provides a way forward: it can coexist reasonably well with the existing options of existing JDK tools; it is familiar to many, and it has library support which can be used for new tools.

Existing tools will continue to support existing options, but may also support new-style aliases for those options. And for both pragmatic and compatibility reasons, the new style may never be adopted for some existing options in existing tools.

Option syntax

The rules for option names are as follows:

The HotSpot VM will accept, via the JNI Invocation API, a subset of these rules, in which new options are specified using the long form name, and using = as the separator for any argument value. The HotSpot VM will not change the form of any of the current set of -XX options.

The use of the '=' form will also make it easier to pass options from a tool other than the launcher to the underlying VM using -J. For example, you can use a single J option, as in -J--<name>=<value>, instead of having to use two -J options as before: -J-<name> -J<value>. The = form also makes it possible to use a common form for the set of options which may be provided to the Java launcher, the Hotspot VM (via the JNI interface) and tools like javac.

The jdk.internal.opt module contains a copy of the JOptSimple library for use by JDK modules which provide command-line tools.

Common options

The JDK implementation of the Java Platform Module System introduces a number of new options to configure the module system.

Any tool that supports the ability to configure some aspect of the module system should provide an option that is consistent with other tools supporting equivalent functionality as much as possible. As a baseline, all tools and API should support the long form option, using '=' to separate an argument.

The set of common options is as follows. Note: the list is intended to just indicate the name of the options and the general form of any arguments it may take. The exact details of these options are specified elsewhere, such as JEP 261, or the documentation for the individual tool providing the option.

Not all tools may support all of these options. Some tools may not be able to support the single-character form, if it conflicts with a previously defined option.

Specifies root modules to resolve in addition to the initial module.

In addition, tools currently supporting a -classpath option should support the new-style long form option as equivalent:

Given the existing support for -cp as a short form for -classpath, a single character form will not be introduced.

All tools should provide some amount of command-line help. At a minimum, the following should be supported.

In time, additional options that are common across different tools may be added to this list.

@-files

Users sometimes run into system limitations on the length of a command line when creating a command line with lots of options or with long arguments for options for a specific tool.

Tools for which this is a common problem may choose to support "argument files" or "@-files", containing strings to be expanded in place of the @file argument. Tools are encouraged to support the same syntax for the tokens within such an argument file.

Command-line help

Tools should support command-line help with a --help option. Some options take complex structured values. The command-line help should use the following rules to display such structured values:

Tools should ensure that the output for command line help fits within the width of a terminal using default terminal settings: this is typically 80 characters.

Tools that show command-line help for a long-form option that takes an argument should normally show the option using a space to separate the argument, and provide a note at the end that = may also be used as a separator.

Tools providing equivalent options should provide the same command-line help text.