Hello,
While migrating the Apache Maven JAR plugin (apache/maven-jar-plugin#508
<https://github.com/apache/maven-jar-plugin/pull/508>) to create archives with
the "jar" tool (via ToolProvider) instead of a library, I ran into a
documentation inconsistency around the -C option that I would like to check
before reporting it.
The "jar --help" option description reads
-C DIR Change to the specified directory and include the following file
i.e. a single following file, which matches the implementation in
src/jdk.jartool/share/classes/sun/tools/jar/Main.java (it joins the directory
to the single next argument). Two other parts of the documentation, however,
suggest that "-C dir" applies to several following files -- the usage synopsis
jar [OPTION...] [ [--release VERSION] [-C dir] files] ...
(note "files", plural) and the example
-C foo/ classes resources
(two operands after one "-C"). The man page, e.g.
https://docs.oracle.com/en/java/javase/25/docs/specs/man/jar.html, reads the
same way.
In practice only the operand immediately after "-C" is resolved relative to
that directory; any further operand is resolved relative to the current working
directory. For example,
mkdir d && touch d/a d/b d/c
jar --create --file x.jar -C d a b c
fails with
b : no such file or directory
c : no such file or directory
(only "a" is archived), because "b" and "c" are looked up in the current
directory rather than in "d".
The forms that work all produce the same archive, with entries a, b and c. One
can repeat the option before each file,
jar --create --file x.jar -C d a -C d b -C d c
add the whole directory,
jar --create --file x.jar -C d .
or write the later operands relative to the current directory,
jar --create --file x.jar -C d a d/b d/c
where "b" and "c" are found as "d/b" and "d/c", and because the "-C" directory
"d" is stripped from every matching entry name the entries are still a, b and
c. What does not work is listing several bare file names after a single "-C
dir", which is exactly what the synopsis and the example suggest.
I reproduced this identically on Eclipse Temurin 17, 21 and 25, Azul Zulu 17
and Amazon Corretto 21, on macOS and Linux; the behaviour and the "--help"
wording are the same everywhere, as expected for the shared jdk.jartool.
The runtime behaviour looks correct and intentional, so this seems to be a
documentation issue only. It might be enough to adjust the synopsis so that
each "-C dir" binds to a single following operand, to correct the "-C foo/
classes resources" example (for instance "-C foo/ ."), to align the man page,
and perhaps to add a note that several inputs relative to a directory require
repeating "-C dir" per input or using "-C dir .”.
I do not have JBS credentials to file this myself; could someone confirm
whether it is worth a documentation issue and, if so, file it?
BTW: Filing bug reports via https://bugreport.java.com/bugreport didn’t work in
the last 24 hours.
Thanks,
Gerd Aschemann
--
Gerd Aschemann (er/he) --- Veröffentlichen heißt Verändern (Carmen Thomas)
+49/173/3264070 -- [email protected] -- https://aschemann.net
