You are reading Pauta Next: changes waiting for the edition after 6.1.0. They are not an edition yet and may change before one is released. Never cite a rule from these pages or audit an app against them: apps are built and audited to a numbered edition. See the latest edition.
Command line and launch
Every app takes the same command-line flags, and they mean the same thing in each: print the help or the version, use another config folder, start without the last session, write a problem report, open the files named. They work the same on every OS, Windows’ console included, and refuse an option they don’t know. A second launch doesn’t start a second app: it hands its arguments to the one already running for that config folder and exits. Scripts and habits depend on these names, so a flag a rule names is required as written.
Rules on this page 13
| 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, a folder in
the user’s home on Windows, macOS and Linux alike.
|
| CLI-03 | SHOULD | --new-instance starts a second process instead of handing off to the running one.
|
| CLI-04 | SHOULD | An app that reopens what was open in its last session (documents, tabs, folders) takes
--no-session, which starts it without them.
|
| CLI-05 | MUST | --report writes a redacted problem report to a file in the current folder, prints the file’s
path and opens the GitHub issue, without starting the GUI. Where the current folder can’t be written, the file
goes to the temp folder.
|
| CLI-12 | MUST | An option the app does not know stops the launch: it names the option on standard error, says
how to get help, and exits with status 2 before the GUI starts. That holds for an option with one dash as for one
with two: it is never ignored and never taken for a file. Two kinds of argument are not unknown options. In an app
that opens files named on its command line, a lone -, and every argument after --, is one of those files,
whatever it starts with; that sentence does not cover an app that opens none. And the JVM options a launcher can
leave among the program’s arguments, --add-exports, --add-opens and -p, are skipped by name, each with its
value, whether the value is the next argument or follows = in the same one (--add-exports=…): never refused,
and the value never opened as a file. On Windows the message prints in the console, which is
CLI-11.
|
| CLI-13 | SHOULD | The short flags are the same in every app: -h for --help, and both -v and -V for
--version.
|
| CLI-11 | MUST | On Windows, --help, --version and --report print in the console they were typed in, and
so does the message that refuses an unknown option (CLI-12). A GUI launcher has no console, so the
installer also carries a console launcher (jpackage’s win-console) that runs the same entry point, or main
attaches to the parent’s console before it prints.
|
| CLI-06 | SHOULD | An app that opens files or folders (documents, images, a .torrent) opens the ones named
as arguments on its command line, which its --help lists as [files…].
|
| Launch | ||
| CLI-07 | MUST | One instance runs per config folder, unless a launch asks for another with --new-instance
(CLI-03). Any other second launch hands its arguments, when it has any, to the running app over a
local endpoint and exits. In an app that opens files, the openFiles Apple Events of macOS reach the running app
too.
|
| 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. Only these uses make AWT
headful, in an app that has them: the tray on Windows and macOS, and on macOS the dock badge, the open-file
handlers and Move to Trash. Linux never needs it. main decides once, before that point, which of them the
settings ask for on this OS. What a tray app says when its tray is turned on after that is
TRAY-14.
|
| CLI-10 | SHOULD | An app that starts external tools ( git, a compiler, ffmpeg) resolves them through the
login shell’s PATH on macOS and Linux. Windows has no login shell’s PATH to ask for, and the one the app
inherits is used there.
|
- 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, a folder in the user’s home on Windows, macOS and Linux alike.- Check (code): the config folder is resolved from both flags before anything reads
~/.<app>, and what--devresolves to is<user.home>/.<app>-devon Windows, macOS and Linux alike, with no branch on the OS. - 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 An app that reopens what was open in its last session (documents, tabs, folders) takes
--no-session, which starts it without them.- Check (by hand): launch with
--no-sessionand find only the items given on the command line. - Reference: Editora
App.helpText. Mirada reopens nothing from its last session, so the rule does not cover it; it takes the flag and does nothing with it (Launch.java).
- Check (by hand): launch with
- CLI-05 MUST
--reportwrites a redacted problem report to a file in the current folder, prints the file’s path and opens the GitHub issue, without starting the GUI. Where the current folder can’t be written, the file goes to the temp folder.- Why: the person who ran the command is looking at that folder, and has to attach the file. A report in the config folder is hidden from them, and one printed to the terminal is cut by its scrollback.
- Check (code):
mainhandles--reportbeforelaunch: it writes the redacted report to a file in the current folder, or in the temp folder when that one can’t be written, prints the file’s path and opens the new-issue page. A test that runs the report command in a folder and finds the redacted report there, with its path printed, is the surest evidence. - Reference: Editora
report/ReportCommand.java(ReportCommandTest); Torrenta’sReportCommand.javadoes the same, and so does the app template’sreport/ReportCommand.java(ReportTest,theReportGoesInTheCurrentFolderAndItsPathIsPrintedandaCurrentFolderThatCantBeWrittenSendsTheReportToTheTempFolder). Mirada writes its report beside the settings, and Termina prints its report without writing a file (ReportCommand.java).
- CLI-12 MUST An option the app does not know stops the launch: it names the option on standard error, says
how to get help, and exits with status 2 before the GUI starts. That holds for an option with one dash as for one
with two: it is never ignored and never taken for a file. Two kinds of argument are not unknown options. In an app
that opens files named on its command line, a lone
-, and every argument after--, is one of those files, whatever it starts with; that sentence does not cover an app that opens none. And the JVM options a launcher can leave among the program’s arguments,--add-exports,--add-opensand-p, are skipped by name, each with its value, whether the value is the next argument or follows=in the same one (--add-exports=…): never refused, and the value never opened as a file. On Windows the message prints in the console, which is CLI-11.- Why: a mistyped
--config-dirthat is ignored starts the app on the real settings, which is the one thing the flag was typed to avoid. Status 2 is what a script tests for a usage error.--is how a file whose name starts with a dash is opened at all. A launcher’s own option is not the user’s mistake, so it must not stop the app; it is skipped by name because a parser that skips whatever it does not know is the one that ignores a typo. - Check (code): the parser
mainruns before the GUI refuses an option the app does not define, with two dashes or with one, andmainthen prints the option and how to get help on standard error and exits with status 2 beforelaunch. In an app that opens files named on its command line, the parser takes a lone-, and a name that starts with a dash after--, for files; in an app that opens none, this part has nothing to find. And the parser skips--add-exports,--add-opensand-pwith their values, in both forms a launcher writes (--add-exports <value>and--add-exports=<value>), with no error and no file. A test that hands the parser each of these arguments is the surest evidence. - Reference: the app template’s
cli/CommandLine.javadoes all of it: it refuses an unknown option with one dash or two (Main.runprints the message and returns 2) and takes-and whatever follows--for files, and skips--add-exports,--add-opensand-pwith their values in both forms (CommandLineTest,reportsMistakes,acceptsTheEqualsFormAndDoubleDashandskipsTheLaunchersJvmOptionsAndTakesCapitalVForVersion). No other app does all of it yet. Termina’scli/CommandLine.javaand Torrenta’scli/CommandLine.javarefuse both kinds of unknown option with status 2, and the launcher’s options with them. Torrenta, which opens the.torrentfiles and magnet links named on its command line, also refuses-and--: anything that starts with a dash and is not a magnet link. Termina opens no files from its command line, so that part of the rule does not cover it (it refuses-as an unexpected argument and--as an unknown option); the launcher’s options are all it misses. Mirada’sLaunch.javaexits 2 on an unknown option with two dashes,--add-exportsand--add-opensamong them, and takes-and whatever follows--for files, but it takes a single-dash option,-pincluded, for a file too. Editora skips every option it does not know without a word, a lone-included, and has no--(App.fileTargets); that is how it gets past a leaked--add-exports,--add-opensor-p, whose value it opens only when a file of that name exists (AppArgsTest). nux reads--minimizedand--screenshot=and ignores every other argument (App.java), and Modula reads none (ModulaApp.java); neither opens files, so what they miss is the refusal.
- Why: a mistyped
- CLI-13 SHOULD The short flags are the same in every app:
-hfor--help, and both-vand-Vfor--version.- Check (code): the command-line parser takes
-hfor--help, and-vand-Vfor--version. - Reference: Termina’s
cli/CommandLine.javaand Torrenta’scli/CommandLine.java; the--helptext of both lists-hand-vand leaves-Vout. The app template’scli/CommandLine.javatakes all three, and its--helptext lists them. Editora takes-hand-Vbut not-v, Mirada has no short flags, and Modula and nux take neither flag in any form.
- Check (code): the command-line parser takes
- CLI-11 MUST On Windows,
--help,--versionand--reportprint in the console they were typed in, and so does the message that refuses an unknown option (CLI-12). A GUI launcher has no console, so the installer also carries a console launcher (jpackage’swin-console) that runs the same entry point, ormainattaches to the parent’s console before it prints.- Why: without it, the three flags and a mistyped option 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=truethat runs the app’s own main class and lets the three flags and an unknown option reach it, ormaincallsAttachConsolebefore printing. - Reference: Torrenta meets it with its second launcher,
torrenta-nox:src/jpackage/torrenta-nox-windows.propertiessetswin-console=true, and itspom.xmladds that launcher to the image on Windows (theos-windowsprofile picks the file), beside the main launcher and on the same module and main class. The launcher’s ownarguments=--headlessapplies only when the person gives none (itsCLAUDE.mdsays so), sotorrenta-nox --help,--version,--reportand an option it does not know reachmainas typed, andmainrefuses the unknown option and answers the three flags before it looks for--headless(App.java). The app template does it the same way: itsos-windowsprofile inpom.xmladds a second launcher,exampleapp-cli, whosepackaging/windows/exampleapp-cli.propertiessetswin-console=trueand nothing else, so it runs the same main class with the arguments as typed. No other app has awin-consolelauncher or callsAttachConsole. Mirada’s one Windows executable is its native image, copied over jpackage’s launcher (native-app-image.sh); whether it prints in the console depends on how that image is linked, which Mirada’s files do not say, and no Windows run has confirmed it.
- CLI-06 SHOULD An app that opens files or folders (documents, images, a
.torrent) opens the ones named as arguments on its command line, which its--helplists as[files…].- Check (by hand): launch with two files and find both open, and run
--helpand find[files…]in its usage line. - Reference: Editora
App.fileTargets. Termina, Modula and nux open no files, so the rule does not cover them.
- Check (by hand): launch with two files and find both open, and run
Launch
Section titled “Launch”- CLI-07 MUST One instance runs per config folder, unless a launch asks for another with
--new-instance(CLI-03). Any other second launch hands its arguments, when it has any, to the running app over a local endpoint and exits. In an app that opens files, theopenFilesApple Events of macOS reach the running app too.- Check (code): the first launch on a config folder becomes the primary and listens on a local endpoint; a
second launch without
--new-instancesends it its arguments and exits; and, in an app that opens files, a handler for the macOS open-files event passes them to the running app (Editora’sMacOpenFiles). A test that makes the first launch primary and delivers a second launch’s arguments to it is the surest evidence. - Reference: Editora
ipc/SingleInstance.java(SingleInstanceTest),MacOpenFiles.java. nux doesn’t yet: its second launch asks the running app to show its window and exits, handing over none of its arguments (instance/SingleInstance.java,NUX-SHOW), and what lets a second instance run on the folder is a setting (singleInstance, read inmainofApp.java), not--new-instance.
- Check (code): the first launch on a config folder becomes the primary and listens on a local endpoint; a
second launch without
- CLI-08 SHOULD An advisory lock tells two processes on one config folder about each other.
- Check (code): each process takes an advisory file lock in its config folder, and can tell that another process already holds one there. A test that takes the lock from two processes is the surest evidence.
- Reference: Editora
config/InstanceLock.java(InstanceLockTest).
- CLI-09 SHOULD
mainsetsjava.awt.headless=truebefore any AWT class loads. Only these uses make AWT headful, in an app that has them: the tray on Windows and macOS, and on macOS the dock badge, the open-file handlers and Move to Trash. Linux never needs it.maindecides once, before that point, which of them the settings ask for on this OS. What a tray app says when its tray is turned on after that is 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):
maincallsSystem.setProperty("java.awt.headless", …)beforelaunchand before anything that loads an AWT class, and the value is"true"unless one of the listed uses is wanted on this OS: always on Linux, on Windows unless the tray is on, and on macOS unless the tray, the dock badge, an open-file handler or, in an app that trashes through AWT, Move to Trash is. - Reference: Editora
App.main, always headless, as Termina (App.java) and the app template (Main.java) are. Torrentaos/AwtUse.java(headful, which itsApp.mainasks once: never on Linux, for the tray on Windows, and for the tray, the dock badge or the open-file handlers on macOS). MiradaApp.java(headless except on macOS, for Move to Trash:os/Trash.java,headless). Modula and nux never set the property, so AWT is headful on every OS, Linux included.
- CLI-10 SHOULD An app that starts external tools (
git, a compiler,ffmpeg) resolves them through the login shell’sPATHon macOS and Linux. Windows has no login shell’sPATHto ask for, and the one the app inherits is used there.- Why: a
.applaunched from Finder inherits a strippedPATH. - Check (code): on macOS and Linux, every process the app starts gets a
PATHthat includes the login shell’s. An app that starts no external tool is outside the rule. - Reference: Editora
process/ProcessRunner.java(augmentedPath; on Windows its login-shell probe returns nothing and the inheritedPATHis used). The app template’ssync/ShellPath.javadoes the same for thegitandghit starts: the login shell’sPATHbefore the inherited one on macOS and Linux, the inherited one on Windows (ShellPathTest).
- Why: a
Pauta Next · unreleased changes after 6.1.0 · Changelog · This page in the latest edition