Notes on java Command Line Argument Files

Solution to a too long classpath issue on Windows

From time to time people jump into this problem on Windows. This is not solely a Java issue, but also taints everything which requires the use of classpath like Clojure. Along with escaping issues related to differences in cmd.exe and Powershell (represented by powershell.exe or pwsh.exe) this is extremely limiting but there exist quite elegant solution, no hack, directly supported by Java runtime based on JDK9 and above.

This is what I've found in the documentation and which is the only reliable solution to this problem. I copy pasted this for the sake of posterity as the documentation is very tricky to find. I hope this helps someone.

From JDK9 documentation - Command-Line Argument Files

You can shorten or simplify the java command by using @argument files to specify a text file that contains arguments, such as options and class names, passed to the java command. This let's you to create java commands of any length on any operating system.

In the command line, use the at sign (@) prefix to identify an argument file that contains java options and class names. When the java command encounters a file beginning with the at sign (@), it expands the contents of that file into an argument list just as they would be specified on the command line.

The java launcher expands the argument file contents until it encounters the -Xdisable-@files option. You can use the -Xdisable-@files option anywhere on the command line, including in an argument file, to stop @{argument files} expansion.

The following items describe the syntax of java argument files:

• The argument file must contain only ASCII characters or characters in system default encoding that's ASCII friendly, such as UTF-8.
• The argument file size must not exceed MAXINT (2,147,483,647) bytes.
• The launcher doesn’t expand wildcards that are present within an argument file.
• Use white space or new line characters to separate arguments included in the file.
• White space includes a white space character, \t, \n, \r, and \f.
• For example, it is possible to have a path with a space, such as c:\Program Files that can be specified as either "c:\\Program Files" or, to avoid an escape, c:\Program" "Files.
• Any option that contains spaces, such as a path component, must be within quotation marks using quotation ('"') characters in its entirety.
• A string within quotation marks may contain the characters \n, \r, \t, and \f. They are converted to their respective ASCII codes.
• If a file name contains embedded spaces, then put the whole file name in double quotation marks.
• File names in an argument file are relative to the current directory, not to the location of the argument file.
• Use the number sign # in the argument file to identify comments. All characters following the# are ignored until the end of line.
• Additional at sign @ prefixes to @ prefixed options act as an escape, (the first @ is removed and the rest of the arguments are presented to the launcher literally).
• Lines may be continued using the continuation character (\) at the end-of-line. The two lines are concatenated with the leading white spaces trimmed. To prevent trimming the leading white spaces, a continuation character (\) may be placed at the first column.
• Because backslash (\) is an escape character, a backslash character must be escaped with another backslash character.
• Partial quote is allowed and is closed by an end-of-file.
• An open quote stops at end-of-line unless \ is the last character, which then joins the next line by removing all leading white space characters.
• Wildcards (*) aren't allowed in these lists (such as specifying *.java).
• Use of the at sign (@) to recursively interpret files isn't supported.

Example of Open or Partial Quotes in an Argument File

In the argument file,

-cp "lib/
cool/
app/
jars

this is interpreted as:

-cp lib/cool/app/jars

Example of a Backslash Character Escaped with Another Backslash Character in an Argument File

To output the following:

-cp c:\Program Files (x86)\Java\jre\lib\ext;c:\Program Files\Java\jre9\lib\ext

The backslash character must be specified in the argument file as:

-cp  "c:\\Program Files (x86)\\Java\\jre\\lib\\ext;c:\\Program Files\\Java\\jre9\\lib\\ext"

Example of an EOL Escape Used to Force Concatenation of Lines in an Argument File

In the argument file,

-cp "/lib/cool app/jars:\
    /lib/another app/jars"

This is interpreted as:

-cp /lib/cool app/jars:/lib/another app/jars

Example of Line Continuation with Leading Spaces in an Argument File

In the argument file,

-cp "/lib/cool\ 
\app/jars"

This is interpreted as:

-cp /lib/cool app/jars

Examples of Using Single Argument File

You can use a single argument file, such as myargumentfile in the following example, to hold all required java arguments:

java @myargumentfile

Examples of Using Argument Files with Paths

You can include relative paths in argument files; however, they're relative to the current working directory and not to the paths of the argument files themselves. In the following example, path1/options and path2/options represent argument files with different paths. Any relative paths that they contain are relative to the current working directory and not to the argument files:

java @path1/options @path2/classes

---

References

1. Oracle - java Command-Line Argument Files
2. Gradle plugin to converts classpath JVM arguments into a file-based argument
3. tools.deps.alpha Wiki - long classpath