From 334b38f63aa877e872b635a2d4dcf189014528a6 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Fri, 12 Nov 2021 11:01:28 +0100 Subject: [PATCH] Extend documentation on argument files: - handling of UTF8 encoded argument files - limitation for quoted argument values --- docs/index.adoc | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/index.adoc b/docs/index.adoc index 6ec12e715..295a8222e 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -1021,6 +1021,10 @@ 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`. +CAUTION: Argument files do have a limitation: parameter or option values enclosed in quotes must not be preceded by an equal sign. +Something like `myoption="foo bar"` does *not* work inside an argument file. +To work around this, either omit the equal sign (`myoption "foo bar"`) or enclose the whole expression in quotes (`"myoption=\"foo bar\""`). + Lines starting with `#` are comments and are ignored. The comment character can be configured with `CommandLine.setAtFileCommentChar(Character)`, and comments can be switched off by setting the comment character to `null`. @@ -1049,6 +1053,19 @@ The above will be expanded to the contents of the file: java MyCommand ABC -option=123 "X Y Z" ---- +CAUTION: Handling of UTF-8 encoded argument files is tricky on Windows OS. +Either use `-DFile.encoding=UTF8` as VM argument or set the environment variable `JAVA_TOOL_OPTIONS`. +So both command calls given below will work on a Windows command line: +[source,cmd] +---- +java -DFile.encoding=UTF8 MyCommand ABC -option=123 "X Y Z" +---- +[source,cmd] +---- +SET JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF8 +java MyCommand ABC -option=123 "X Y Z" +---- + @-file expansion can be switched off by calling `CommandLine::setExpandAtFiles` with `false`. If turned on, you can still pass a real parameter with an initial '@' character by escaping it