Command line and launch
Rules on this page 11
| ID | Level | Rule |
|---|---|---|
| Flags | ||
| CLI-01 | MUST | --help and --version print before the GUI starts, in plain English, not translated.
|
| 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.
|
| CLI-04 | SHOULD | --no-session does not restore the last session.
|
| 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.
|
| CLI-06 | SHOULD | [files…] opens these items.
|
| Launch | ||
| 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).
|
| CLI-10 | SHOULD | External tools are resolved through the login shell’s PATH.
|
- CLI-01 MUST
--helpand--versionprint before the GUI starts, in plain English, not translated.- Check (code):
mainhandles both and exits beforelaunch, printing fixed English text rather than catalog messages. - Reference: Editora
App.main,App.helpText;AppArgsTest.
- Check (code):
- CLI-02 MUST
--config-dir <dir>uses another config folder, and--devuses~/.<app>-dev.- Check (code): the config folder is resolved from both flags before anything reads
~/.<app>. - Reference: Editora
App.main(ConfigManager.configDirFor,App.devFlag).
- Check (code): the config folder is resolved from both flags before anything reads
- CLI-03 SHOULD
--new-instancestarts 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-sessiondoes not restore the last session.- Check (by hand): launch with
--no-sessionand find only the items given on the command line. - Reference: Editora
App.helpText.
- Check (by hand): launch with
- CLI-05 MUST
--reportwrites a redacted problem report and opens the GitHub issue, without starting the GUI.- Check (test): a test runs the report command and finds the redacted report written.
- Reference: Editora
report/ReportCommand.java(ReportCommandTest).
- CLI-11 MUST On Windows,
--help,--versionand--reportprint in the console they were typed in. A GUI launcher has no console, so the installer also carries a console launcher (jpackage’swin-console, named<app>-cli) that runs the same entry point, ormainattaches 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, ormaincallsAttachConsolebefore 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.
Launch
Section titled “Launch”- 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,
openFilesApple Events reach the running app.- Check (test): a test makes the first launch primary and delivers a second launch’s arguments to it.
- Reference: Editora
ipc/SingleInstance.java(SingleInstanceTest),MacOpenFiles.java.
- CLI-08 SHOULD An advisory lock tells two processes on one config folder about each other.
- Check (test): a test takes the lock from two processes.
- Reference: Editora
config/InstanceLock.java(InstanceLockTest).
- CLI-09 SHOULD
mainsetsjava.awt.headless=truebefore any AWT class loads. The one exception is an AWT tray on Windows or macOS, whichmaindecides 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 ofmain, 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
.applaunched from Finder inherits a strippedPATH. - Check (code): every process the app starts gets a
PATHthat includes the login shell’s. - Reference: Editora
process/ProcessRunner.java(augmentedPath).
- Why: a
Pauta 5.0.0 · · Changelog · This page in the latest edition