Summary

Provide finer control over the jpackage console output.

Problem

jpackage's console output is supposed to serve a few purposes:

• Help users customize packaging
• Help debug packaging failures
• Help users track packaging progress

Currently, only the last one is satisfactory.

jpackage supports two output modes: quiet and verbose, controlled by the --verbose option.

In quiet mode, it would print errors and warnings, so it is not truly quiet.

In verbose mode, it would suppress important details. E.g.: it does not print all signing commands on macOS, making it difficult to debug signing errors.

jpackage prints properties of a package being created, but they are scattered across the verbose output and are difficult to locate.

If a user wants to get the command lines of external tools that jpackage executes, they have to filter them from the verbose output.

Overall, the verbose output mode should suit multiple needs, but none of them are addressed satisfactorily.

Solution

Let the user configure which message categories appear in the console output instead of providing the fixed output modes (quiet/verbose).

Curently jpackage has the following message categories:

1. Output bundle properties, versions of the tools being used
2. Configuration warnings. Warnings about input data. E.g., when the user requests bundling of a Linux DEB package but doesn't provide a license file, or when the user requests bundling a signed macOS PKG package from the unsigned application bundle
3. Packaging warnings. Warnings during the packaging phase. E.g., when the user customizes Linux RPM or DEB packaging such that the output package's properties contain unexpected values
4. Command lines and the output of external tools that jpackage executes
5. Sources of configurable resources (default or custom picked from the resource directory)
6. Progress messages
7. Fatal errors

Message categories #2, #3, and #7 are enabled in the quiet mode. All message categories are enabled in the verbose mode.

jpackage will support an additional "trace" (#8) message category. It will consist of non-localized messages that provide a detailed trace of jpackage execution, sufficient for debugging. It will include suppressed exception stacktraces, details of the logic for selecting a specific packaging tool when multiple variants are available, and other information that may help explain jpackage's behavior in the given environment. We will not localize these messages because they should not be a part of regular jpackage output and are intended for debugging.

jpackage will output all messages from category #1, then all messages from category #2, before entering the packaging phase and resolving customizable resources, rather than scattering them across the console output. This will make the information about the bundle being created easy to access; the user can find the details simply by examining the beginning of the console output.

Messages from other categories will be written after messages from categories #1 and #2, in the order they appear in the execution flow.

We will support enabling and disabling of each message category in the console output individually. To achieve this, the --verbose option will accept an optional argument that specifies which message categories to enable.

We will support optional routing of all message categories to the logging framework through the System.Logger API. This will improve integration of jpackage with build tools (Gradle, Maven).

Specification

The format of the optional value of the --verbose option will be:

 <configuration>      ::= <logger> ":" <console>
                       | <console>
                       | <logger>

<logger>             ::= "log"

<console>            ::= <console-categories>
                       | "!" <console-categories>
                       | ""

<console-categories> ::= <console-category>
                       | <console-category> "," <console-categories>

<console-category>   ::= "errors"
                       | "progress"
                       | "resources"
                       | "summary"
                       | "tools"
                       | "trace"
                       | "warnings"

errors

The "errors" token enables output of fatal errors (message category #7).

If the "errors" token is specified without the "trace" token, error messages will be written to the console without the corresponding exception stacktraces.

If the "errors" token is specified with the "trace" token, error messages will be written to the console with the corresponding exception stacktraces.

progress

The "progress" token enables output of progress messages (message category #6).

resources

The "resources" token enables output of messages about the use of the configurable resources (message category #5).

summary

The "summary" token enables output of the bundle properties and the versions of the tools being used (message category #1).

tools

The "tools" token enables output of the command lines executed by the jpackage (message category #4).

If the "tools" token is specified without the "trace" token, the jpackage will print the command lines without the output produced by executing these command lines. Only command lines that are relevant to package customization will be written to the console.

If the "tools" token is specified with the "trace" token, the jpackage will print all command lines and their output.

trace

The "trace" token enables the output of stack traces of suppressed exceptions and details of the jpackage execution (message category #8).

When combined with other tokens, the "trace" token enables additional information in messages from the corresponding message categories, as described above.

warning

The "warning" token enables output of warnings (message categories #2 and #6).

log

The "log" token enables routing of all message categories to the logging framework through the System.Logger API. The logger name will be "jdk.jpackage".

Backward compatibility

If the --verbose option is not on the command line, it is equivalent to --verbose errors,warnings arguments on the command line.

If the --verbose option is specified without the value, it is equivalent to the --verbose errors,progress,resources,summary,tools,warnings arguments on the command line (all but the "trace" message categories are enabled).

Help output changes

Description of the --verbose option in the help output will be changed from

--verbose
          Enables verbose output

to

--verbose [<configuration>]
          Configures verbose output. Where

          <configuration>      ::= <logger> ":" <console>
                                 | <console>
                                 | <logger>

          <logger>             ::= "log"

          <console>            ::= <console-categories>
                                 | "!" <console-categories>
                                 | ""

          <console-categories> ::= <console-category>
                                 | <console-category> "," <console-categories>

          <console-category>   ::= "errors"
                                 | "progress"
                                 | "resources"
                                 | "summary"
                                 | "tools"
                                 | "trace"
                                 | "warnings"

          Suppress all console output, enable logging via System.Logger API:
              --verbose log
          Enable all message categories in the console:
              --verbose !
          Enable all message categories, but "trace" and "tools" in the console:
              --verbose !trace,tools
          Enable "trace" and "tools" message categories in the console:
              --verbose trace,tools
          Enable "trace" and "tools" message categories in the console and
          enable logging via System.Logger API:
              --verbose log:trace,tools

          If the verbose option is specified without the value, it is equivalent to
              --verbose !trace
          If the verbose option is not specified it is equivalent to
              --verbose errors,warnings