JEP 293: Guidelines for JDK Command-Line Tool Options

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:

• various tools: -classpath (short-form -cp)
• javac: -verbose, -version, -XprintRounds, -Xlint:unchecked
• jar, in JDK 8: -c, -t, -x, etc.
• pack200: -g, --no-gzip, --gzip, --version

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:

• Options have a long name, which is a short series of words, beginning with '--' and separated by '-'. For example: --example-option

• Options may have a short, single character form. For example, -e

• Options can require an argument to be provided. For a long-form options, the argument may be separated from the option name by either white space or '='. For single character options, the argument may immediately follow the character or may be separated by white space. For example:

  • --example-option value
  • --example-option=value
  • -e value
  • -evalue

• Options can allow an argument to be provided. If such an argument is present, then the syntax of the option is the same as if the option required the argument. For example:

  • --example-option
  • --example-option value
  • --example-option=value

• Case is always significant, in both the long name or single character forms. For example, --Example-Option is not the same as --example-option.

• Long form names may not be abbreviated on the command line. For example, --example-o is not the same as --example-option.

• The use of options for subcommands is not included in the rules.

• Single character options may be grouped into a single token. For example, if -a and -b are single character options, they may be specified together on the command line as -ab.

• Although some option-decoding libraries may support grouping the single character form of a group of options into a single word, it is not required that this should be supported when the options being used require arguments to be provided. For example, a single character option that takes an argument may conflict with the use of an existing JDK-style argument.

• For some options, the argument may be a series of values. When the values are file system locations, such as for directories or files, the values should be separated by the platform-specific path separator character (; on Windows systems, : on other platforms.) Otherwise, the recommended separator is a comma.

• The use of -X as a prefix to indicate "non-standard" options will be discontinued for new options, although command-line help may continue to draw a distinction between more commonly used options and those for advanced use.

• Some forms on the command-line may be ambiguous; tools may try and be clever to disambiguate such cases. In general, tools are encouraged not to support combinations which might be ambiguous, and users are encouraged not to use forms which might be ambiguous. For example, tools which support the old short form option -cp for classpath may choose not to support both -c and -p as single-character forms for new options.

• Existing options defined in existing tools will continue to be supported until phased out or replaced, on a case by case basis. In some cases, that may be never.

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.

• --module-path <path>,   -p <path>

  Specifies the application module path.

• --upgrade-module-path <path>

  Specifies the module path for upgradeable modules.

• --add-modules <module>(,<module>)*

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

• --limit-modules <module>(,<module>)*

  Limits the universe of observable modules.

• --add-reads <module>=<target-module>(,<target-module>)*

  Add a read edge from <module> to each <target-module>.

• --add-exports <module>/<package>=<target-module>(,<target-module>)*

  Add a qualified export of <package> from <module> to <target-module>.

• --patch-module <module>=<file>(:<file>)*

  Override or augment a module with classes and resources in JAR files or directories.

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

• --class-path <path>

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.

• --help

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:

• Display the names of place-holders using <name>.

• Use parentheses for grouping: (...)

• Use * for repetition, zero or more times.

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.