Skip to content
Pauta5.0.0

Command line and launch

Rules on this page 11
IDLevelRule
Flags
CLI-01MUST
--help and --version print before the GUI starts, in plain English, not translated.
CLI-02MUST
--config-dir <dir> uses another config folder, and --dev uses ~/.<app>-dev.
CLI-03SHOULD
--new-instance starts a second process instead of handing off to the running one.
CLI-04SHOULD
--no-session does not restore the last session.
CLI-05MUST
--report writes a redacted problem report and opens the GitHub issue, without starting the GUI.
CLI-11MUST
On Windows, --help, --version and --report print in the console they were typed in. A GUI launcher has no console, so the installer also carries a console launcher (jpackage’s win-console, named <app>-cli) that runs the same entry point, or main attaches to the parent’s console before it prints.
CLI-06SHOULD
[files…] opens these items.
Launch
CLI-07MUST
One instance runs per config folder. A second launch hands its arguments to the running app over a local endpoint and exits; on macOS, openFiles Apple Events reach the running app.
CLI-08SHOULD
An advisory lock tells two processes on one config folder about each other.
CLI-09SHOULD
main sets java.awt.headless=true before any AWT class loads. The one exception is an AWT tray on Windows or macOS, which main decides once, before that point (TRAY-14).
CLI-10SHOULD
External tools are resolved through the login shell’s PATH.
  • CLI-01 MUST --help and --version print before the GUI starts, in plain English, not translated.
    • Check (code): main handles both and exits before launch, printing fixed English text rather than catalog messages.
    • Reference: Editora App.main, App.helpText; AppArgsTest.
  • CLI-02 MUST --config-dir <dir> uses another config folder, and --dev uses ~/.<app>-dev.
  • CLI-03 SHOULD --new-instance starts a second process instead of handing off to the running one.
    • Check (code): the flag skips the single-instance hand-off.
    • Reference: Editora App.newInstanceFlag.
  • CLI-04 SHOULD --no-session does not restore the last session.
    • Check (by hand): launch with --no-session and find only the items given on the command line.
    • Reference: Editora App.helpText.
  • CLI-05 MUST --report writes a redacted problem report and opens the GitHub issue, without starting the GUI.
  • CLI-11 MUST On Windows, --help, --version and --report print in the console they were typed in. A GUI launcher has no console, so the installer also carries a console launcher (jpackage’s win-console, named <app>-cli) that runs the same entry point, or main attaches to the parent’s console before it prints.
    • Why: without it, the three flags print nothing from cmd or PowerShell, and the command line differs on one OS.
    • Check (code): the Windows jpackage configuration adds a launcher with win-console=true, or main calls AttachConsole before printing.
    • Reference: no app yet for the GUI. Torrenta’s headless launcher is a console program (src/jpackage/torrenta-nox-windows.properties, win-console=true).
  • CLI-06 SHOULD [files…] opens these items.
    • Check (by hand): launch with two files and find both open.
    • Reference: Editora App.fileTargets.
  • CLI-07 MUST One instance runs per config folder. A second launch hands its arguments to the running app over a local endpoint and exits; on macOS, openFiles Apple Events reach the running app.
  • CLI-08 SHOULD An advisory lock tells two processes on one config folder about each other.
  • CLI-09 SHOULD main sets java.awt.headless=true before any AWT class loads. The one exception is an AWT tray on Windows or macOS, which main decides once, before that point (TRAY-14).
    • Why: on macOS, AWT’s native toolkit and JavaFX contend for the one AppKit run loop and can hang; headless Java2D still draws to images.
    • Check (code): System.setProperty("java.awt.headless", …) is among the first statements of main, and it is "true" unless the tray needs AWT.
    • Reference: Editora App.main.
  • CLI-10 SHOULD External tools are resolved through the login shell’s PATH.
    • Why: a .app launched from Finder inherits a stripped PATH.
    • Check (code): every process the app starts gets a PATH that includes the login shell’s.
    • Reference: Editora process/ProcessRunner.java (augmentedPath).

Pauta 5.0.0 · · Changelog · This page in the latest edition