Skip to content

Command line Processing

Jump to bottom
Andrew Binstock edited this page Apr 30, 2025 · 4 revisions

There are more than 700 command-line options for the JVM. Just gathering all the options for the current program is a complex task. It's not enough just to check the args, as there are multiple sources of options, as shown next. (A check mark beside a source means that it is also implemented in Jacobin.)

For general purposes, it's convenient to think of options as being divided into two groups: those for the JVM and those for the app itself.

App options are specified by the user; they tell the app what to do. They are generally provided in one of two ways:

  • on the command line ☑
  • in @files (text files that contain one or more options)

JVM options precede app options on the command line and provide execution parameters for the JVM. They are gathered from multiple sources:

  • environment variables:

    • JAVA_TOOL_OPTIONS ☑
    • _JAVA_OPTIONS ☑
    • JDK_JAVA_OPTIONS ☑

  • options files, specified via the -XX:VMOptionsFile option

  • the command line ☑

The JVM first gathers up all the JVM options and then appends the remaining (app) command-line options. The first option it encounters that does not begin with a hyphen and is not a parameter to a previous option is identified as the name of the class to execute. All options after this starting class are considered application options. When executing JAR files, all options found after -jar jarfile.jar are application options.

Looking at the JDK Code

The JVM's call to handle command-line options occurs in the main VM class.

Option processing is done in this package: com.sun.tools.javac.main.Option. The main processing is done in this class.

A lot of the validation of the options is done here.

The normalization of paths and file locations in arguments is done here. As a point of reference regarding the complexity of this work, the latter file consists of more than 2100 lines.

Jacobin's CLI Processing

Jacobin attempts to remain close to the syntax used by the OpenJDK JVM, specifically HotSpot. However, Jacobin also has its own set of options and switches that it uses. This section discusses their syntax.

  • All options begin with a hyphen
  • Options that are normally off are enabled by specifying them on the command-line: -doIt
  • Options that take a value use a colon, with the exception of options that are ganged together. So: -hypothetical:1024
  • Options that accept multiple values are separated from the values by a colon; the values are comma-separated, if a value itself takes a value, it's specified with an = For example, -trace:methods,statics,maxAlloc=1024m
  • The equivalent of OpenJDK's -XX: experimental options is -JJ: in Jacobin (for Jacobin JVM): -JJ:galt
Clone this wiki locally