JDK-8217687 : jpackage --help improvements
  • Type: Bug
  • Component: tools
  • Sub-Component: jpackage
  • Affected Version: internal
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2019-01-23
  • Updated: 2019-03-22
  • Resolved: 2019-02-14
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
internalFixed
Related Reports
Relates :  
JDK-8217894 - jpackage CLI syntax changes
Relates :  
JDK-8217803 - Change separator used in modular options to a comma.
Relates :  
JDK-8217793 - Modular jars in jpackage are not working
Description
Comments on the jpackage --help contents.

1.) - The create-jre-install doc uses the term "JRE" without definition; is it the same as "Java Runtime" used later, be consistent.

2.) - Use the word colon instead of ":" or both color ":" to make the text more readable, the bare : looks like punctuation.

3.) - --main-jar: combine the 1st and 3rd lines
   The main JAR of the application; containing the main class.

4.) - arguments:  "no arguments are specified by the launcher"
  The "by the launcher" means something but its not clear what.
  or it is unnecessary.
  Do you mean specified, or "supplied by the launcher".
  Do these arguments refer to command line arguments that may be provided on the command line? or from somewhere else.

5.)  - --jvm-args: "JVM flags and options to pass to the application".
  The "to the application" phrase is confusing because JVM flags and options are never passed to the application, only to the java command.

6.)  - If "jvm-args" and "jvm flags" are the same thing, please pick a single term.

7.) - --build-root If this is purely a temporary directory then it should be called temp-dir.  Otherwise, it looks more significant that it really is.

8.) --force: Which directory does "root directory" refer to:  --output-dir or --build-root?  be consistent about references to directories

9.)  --add-modules and --limit-modules refer to "JImage";
   Is that important, it seems just to introduce an additional entity.
  Saying "add to the image" should be sufficient.

10.) --secondary-launcher;  "can be used to describe the secondary launcher"
   I would have called them arguments for the secondary launcher.

11.) The "Sample usage" description line for the first two commands in the help text is incorrect 
  "Generate an application image from a non-modular jar file" should be something like "Create a non-modular application image"
  "Generate an application image from a modular jar file" should be something like "Create a modular application image"
12.) The help text for --add-modules and --limit-modules say they are separated with File.pathSeparator, when actually they are separated with commas.

13.) The new help text for --runtime-installer option (see JDK-8217894) says: "Generates a platform-specific installer for Java runtime." .  It should say "for a java runtime."

14.) Now that there are only two modes, we may want to revisit grouping the options that are only valid in "create-installer" mode
Comments
1.) we are removing create-jre-installer mode as per JDK-8217894 2.) we will leave this as is, it is the same as java command. 3.) we will not change the syntax or main-jar. (as discussed in JDK-8217894 comments.) 4.) we will clarify --arguments as follows: --arguments -a <main class arguments> Command line arguments to pass to the main class if no command line arguments are given to the launcher. 5.) we will change to: --jvm-args <java vm arguments> Java arguments to pass to the virtual machine. 6.) see 5. 7.) needs further discussion - should we change to build-temp 8.) we do not plan to change at this time. 9.) limit-modules will be removed, add-module will be modified as per: JDK-8217803 10.) we will change "... can be used to describe the secondary launcher." to : ... can be used. These options are added to, or used to overwrite, the original command line options when building the secondary launcher. 11.) the sample usage will be modified to say: Generate a modular application image: and Generate a non-modular application image: 12.) The help text for --add-modules will be changed to: --add-modules <module name>[,<module name>...] A comma (",") separated list of modules to add . and --limit-modules was removed, as part of JDK-8217894 13.) we will fix the text for --runtime-installer 14.) may be considered separately.
07-02-2019
make sure to handle following also : 15.) in --add-modules help test, reduce "A comma (",") separated list of modules to add to JImage creation," to just "A comma (",") separated list of modules to add." Shouldld we change to: --add-modules <module name>[,<module name>...] root modules to resolve in addition to the initial module. 16.) rename variables, property keys, and test name from "force" to "overwrite" (left over from 17.) change installer tests that use --installer-type to include EXT on the same line like other options.
06-02-2019