Bug ID: JDK-8178442 JEP 311: Java Packager API & CLI

JDK-8178442 : JEP 311: Java Packager API & CLI

Type: JEP
Component: deploy
Sub-Component: packager

Priority: P2
Status: Closed
Resolution: Withdrawn

Submitted: 2017-04-11
Updated: 2018-04-05
Resolved: 2017-11-28

Related Reports

Blocks :	JDK-8175574 - Singleton App
Duplicate :	JDK-8160195 - [packager] Research Public API
Duplicate :	JDK-8148264 - New Java Packager Arguments
Duplicate :	JDK-8138944 - Support command line arguments to the JVM passed to self-contained app launchers
Relates :	JDK-8186997 - Deprecate classes in legacy.* package
Relates :	JDK-8183144 - add support for locale & platform (see JNLP spec)
Relates :	JDK-8200758 - JEP 343: Packaging Tool (Incubator)
Relates :	JDK-8148265 - Deprecate Java Packager Arguments
Relates :	JDK-8184806 - Remove Deprecated Java Packager CLI Arguments

Sub Tasks

JDK-8180142 :	Deprecate ant-javafx.jar - Resolved
JDK-8180143 :	Add ant-java.jar - Resolved
JDK-8180145 :	Change all scopes from "fx" to "packager" - Resolved
JDK-8180146 :	ant-java.jar to use ToolProvider - Resolved
JDK-8180147 :	Refactor existing CLI (prepare for future removal) - Resolved
JDK-8180148 :	Design and implement new CLI - Resolved
JDK-8180150 :	Add config file support - Resolved
JDK-8180333 :	Add ToolProvider implementation for java packager - Resolved
JDK-8181748 :	Check main jar manifest if "main-class" is omitted - Resolved
JDK-8181749 :	If only one jar is specified, consider it as main - Resolved
JDK-8186444 :	Change javapackager entry point - Resolved
JDK-8186619 :	Add checks for mutually exclusive arguments - Resolved
JDK-8186996 :	Add mechanism for validating dependent arguments - Resolved
JDK-8186997 :	Deprecate classes in legacy.* package - Resolved
JDK-8187055 :	Add secondaryLaunchers support for CLI - Resolved
JDK-8187524 :	Add missing arguments in new CLI - Resolved
JDK-8187892 :	Add new parameter for predefined app image in the new CLI - Resolved
JDK-8187895 :	"--main-jar" shouldn't be mandatory parameter for image or installer - Resolved
JDK-8187897 :	For ant-java.jar, should accept only new arguments - Resolved
JDK-8189207 :	Add new parameter ("--jnlp") for generating images/installers from .jnlp files - Resolved
JDK-8189322 :	Add "--help" for new CLI - Resolved
JDK-8189709 :	Implement a mechanism for parsing .jnlp and creating a cmd line based on the parsed file. - Closed
JDK-8189710 :	Implement a mechanism for creating a bundle for downloaded files (from .jnlp). - Closed

Description

Summary
-------

Create a new, long-term API and CLI for the Java Packager.


Motivation
----------

The Java Packager API is not currently documented or supported. It is used by build tools such as `ant-javafx.jar`, and by Gradle and Maven plugins. Currently they use an API that is located in the packages:

    com.oracle.tools.packager
    com.sun.javafx.tools.packager
    com.sun.javafx.tools.packager.bundlers
    com.sun.javafx.tools.resource

The API is far too broad. It should be more consistent with the platform, and no longer export `com.sun.*` or `com.oracle.*` packages. These are all deprecated in JDK 10 and will be removed in JDK 11. All package names should share a common prefix. Every option should be available via the CLI.

The current Java Packager CLI is not intuitive, not consistent with other Java tools, and not all features are accessible. The Java Packager needs to provide a new CLI that exposes all features, and is available via a ToolProvider. 


Description
-----------

`ant-javafx.jar` will be deprecated, and replaced with `ant-java.jar`, which uses the new `ToolProvider` API and and changes all scopes from "fx" to "packager". The Java Packager will be accessible by a `ToolProvider` in a manner similar to the [javac compiler](https://docs.oracle.com/javase/7/docs/api/javax/tools/JavaCompiler.html) and the jdeps tool.
Java Web Start support(JNLP files) will be removed in the new CLI.

### CLI arguments

For backward compatibility, existing CLI arguments will be left as-is for JDK 10, and refactored into a method that can be removed later.

The CLI will be reworked to be simpler and expose all Java Packager features. 
Argument syntax will be more robust, and support one of four options:

    -name=value
    -name value
    --name=value
    --name value

### New CLI arguments

NOTE: This is just a preliminary list of arguments.

These are the first order arguments that determine what the operation that the Java Packager will be performing:

    -create-image
    -create-installer

### `-create-image`

    -verbose
    -name
    --module
    --module-path
    --add-modules
    --limit-modules
    -icon
    -outdir <directory>
    --strip-native-commands <true/false>
    -title
    -vendor
    -description
    -category
    -copyright
    -license
    -secondaryLauncher.name
    -secondaryLauncher.module
    -secondaryLauncher.mainclass
    -srcdir
    -srcfiles
    -version
    -mainclass
    -classpath
    -mainJar/-appclass
    -daemon
    -preloader
    -jvmargs <name,value>(:<name,value>)*
    -jvmuserargs <name,value>(:<name,value>)*
    -daemon/-service
    -BapplicationCategory=
    -BappVersion=
    -Bmac.CFBundleIdentifier=
    -Bmac.category=
    -Bmac.CFBundleVersion=
    -BsignBundle=false
    -mac.file.associations <extension,"description">(:<extension,"description">)*
    -default-arguments <value>(:<value>)*
    -Bicon.png

### `-create-installer`

    -Bmac.dmg.simple=true
    -file.associations <extension,"description">(:<extension,"description">)*
    -BsignBundle=false
    -Bmac.app-store-entitlements=<filename>
    -installdirChooser
    -Bwin.menuGroup
    -Bwin.64Bit
    -Bwin.64BitJreRuntime
    -Bwin.registryName
    -Bwin.installerName
    -Blinux.bundleName
    -Blinux.deb.fullPackageName
    -Blinux.deb.imageDir
    -Blinux.deb.imageRoot
    -Blinux.deb.configDir
    -Blinux.deb.maintainer
    -Blinux.deb.licenseText
    -Blinux.xdg-prefix

### Configuration-file support

There will be support similar to `java.exe`, to pass all arguments via a configuration file. This will be a properties file.

Comments

Please make sure to consider JEP 293 (http://openjdk.java.net/jeps/293). New options should only support long forms that use the double-dash (--) prefix. Please consider using a bare verb rather than an option to specify the operation to be performed, as done in newer tools such as jmod. This makes it easier to read CLI invocations.
31-08-2017
Probably not, let's get rid of them. (I just added what we already have)
16-06-2017
Does it still make sense to have those 64-bit windows arguments?
16-06-2017
Could we do: javapackager -create-image <output directory> <directory> when the main class is encountered the default in this situation could be to use the name of the main class as the -name <name> argument? Just a thought.
09-06-2017
>> No -outdir specified so MyApp is generated to the current directory. I'm OK with that but it's confusing when 3 below is also supported. I think input directory should always be specified. >>javapackager -create-image MyApp <directory or files> <directory> it could be a bit confusing in the case when there are many files I think we can try cmd like this: javapackager -create-image <app name> <directory> [-files <directory or files>] [-outdir <directory>]
08-06-2017
Wouldn't that be odd to use all the files in the current directory and generate the app image to the current directory? What is the default for tools like zip, tar etc? I think the default is to require a folder to compress and an archive name, two arguments. So my point is I think there'd be too many special cases: 1. javapackager -create-image -name MyApp If run a second time, MyApp would be a directory in . and be included into the app image. 2. javapackager -create-image <directory> -name MyApp No -outdir specified so MyApp is generated to the current directory. I'm OK with that but it's confusing when 3 below is also supported. 3. javapackager -create-image -name MyApp -outdir <directory> I think I'd rather have MyApp as the argument to -create-image rather than the input directory. This is what I'm thinking makes the most sense. javapackager -create-image MyApp -outdir <directory> -files <directory or files> And remove -srcdir all together. All files specified in -files will be copied to app directory and all directories specified by -files will be copied to the app directory. I might be convinced that this is a good way to go: javapackager -create-image MyApp <directory or files> <directory> So -create-image can have 3 optional arguments (-name, -files, -outdir). In that order optional from left to right. But I'd have to look at -create-installer and the other arguments to see if this makes sense.
08-06-2017
I think this looks ok: javapackager -create-image <directory> -files <jar1> "-files" can be omitted (so use all files from directory) why you don't want to use current directory if "-outdir" is omitted?
08-06-2017
My only concern with that approach is the minimum arguments are "-outdir <directory> -name <name>" (app class, main jar can be detected, -native image is already specified) and it seems a bit odd to have one argument that is seemingly out of place and the default has always been the current working directory and in this case would probably be required. Maybe it isn't required, but then special processing is needed. Unless it is treated as an optional argument to -create-image? The problem with defaulting to the current directory is it would include everything unless -files is specified. We should come up with a better name than -srcdir. directory? javapackager -create-image <directory> -files <jar1> Could we encode everything in -files and have only one argument?
08-06-2017
I'm not sure. We can try to get rid of it and use something very simple, for example: javapackager -create-image <srcdir> This could be simplest command line. All other parameters could be auto-generated. For me it looks very intuitive, like zip or tar. If needed, user can add "-files", like this: javapackager -create-image <srcdir> -files <jar1> or add another patameters. It will be easy to create "--help" for this approach.
08-06-2017
Agreed. For the new options I wouldn't rename it but rather choose a new name. I think srcdir and srcfiles was left over from the time when the java packager built from .java files which made it a build too and thankfully nobody used because it really never worked and I was able to remove/deprecate. What name do you propose?
07-06-2017
By the way, what I don't like about "srcdir"/ "srcfiles" is that in software development "src" is used to specify code sources (like .java, .cpp files). We use it for jars, modules, which is misleading. Well, jars and modules are actually sources for our packager, but in general "src" should be used for the files that contain code. We may consider renaming the options.
07-06-2017
That's an interesting idea. We'd have to define required commands, which depending on how the CLI parser is implemented isn't difficult. The only problem is it may get confusing trying to mix this and the old CLI arguments.
07-06-2017
Also we can consider adding something like default configuration for every platform. For example, .exe installer for Windows, .dmg for Mac... User will need to provide minimal info (like jars, modules,etc), and if type(like "-create-image") is omitted, we can generate default bundle for curent platform. It will be like entry point to javapackager for new users. Full command line we can display in logs (therefore it will be easy to correct it if any specific parameter is needed).
06-06-2017
1. I'm fine with that. Adding create was input from others. Let's discuss it the sprint planning meeting. 2. I think we should always require outdir. 3. I think this already happens. But I don't like how srcfiles and srcdirs is currently implemented. 4. Agreed. Some of this was implemented at some point but never complete. 5. Agreed.
05-06-2017
In addition we can consider following: 1) remove "create-" prefix for the first order arguments, so it will be like: -image -installer -patch -keys -webstart Anyway, it's clear that we create something. 2) if "outdir" is not specified, we can generate it (for example, current dir + "output_" + current time/date). Same for "outfile". 3) if users specifies only "srcfiles" without "srcdir", we can look for src files in the curent directory. 4) if "main-class" is omitted, we can check main jar manifest ("Main-class: ..."). 5) if there is only one jar in "srcfiles", we can automatically consider it as main (therefore, there will be no need to add "-mainJar")
19-05-2017