From d4fc26b3d3edd190872d1a771cc29bcb54a7a2f9 Mon Sep 17 00:00:00 2001 From: "Jeffrey C. Ollie" Date: Tue, 1 Jul 2025 14:22:55 -0500 Subject: [PATCH] linux: add some docs on launching/managing Ghostty The addition of D-Bus activation and systemd user services in #7679 has made the "default" launching of Ghostty a little more complicated. This PR attempts to document that process works and commands for managing/controlling that process. --- README-LINUX.md | 148 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 README-LINUX.md diff --git a/README-LINUX.md b/README-LINUX.md new file mode 100644 index 000000000..f47113564 --- /dev/null +++ b/README-LINUX.md @@ -0,0 +1,148 @@ +# Notes on Running Ghostty on Linux + +## Launching + +If installed by a system package or by compiling from source and installing into +`$HOME/.local` (with `zig build -p $HOME/.local -Doptimize=ReleaseFast`) several +configuration files will be installed which allow Ghostty to be launched from +most GUI application launchers (like Gnome Shell or KDE Plasma). + +These are the files that control the launching of Ghostty if installed as +a user: + +``` +$PREFIX/share/applications/com.mitchellh.ghostty.desktop +$PREFIX/share/dbus-1/services/com.mitchellh.ghostty.service +$PREFIX/share/systemd/user/com.mitchellh.ghostty.service +``` + +If installed as a system package, the files will be found in the following +locations: + +``` +$PREFIX/share/applications/com.mitchellh.ghostty.desktop +$PREFIX/share/dbus-1/services/com.mitchellh.ghostty.service +$PREFiX/lib/systemd/user/com.mitchellh.ghostty.service +``` + +Ghostty takes advantage of D-Bus activation and `systemd` user services to provide +the best experience possible. + +The application launcher, instead of executing Ghostty directly, will send a +signal to the D-Bus session broker asking it to open a Ghostty window. The +D-Bus session broker will check D-Bus to see if Ghostty is already running. If +Ghostty is already running, the broker will send a D-Bus signal to Ghostty to +create a new window. + +```mermaid +sequenceDiagram + actor Launcher + participant D-Bus + participant Ghostty + Launcher->>D-Bus: Start a Ghostty window + D-Bus->>Ghostty: Create a new window + Ghostty->>D-Bus: OK +``` + +If Ghostty is not running, the D-Bus session broker will ask `systemd` to start +Ghostty in a user service, and then will send Ghostty a D-Bus signal to create a +new window. + +```mermaid +sequenceDiagram + actor Launcher + participant D-Bus + participant systemd + Launcher->>D-Bus: Start a Ghostty window + D-Bus->>systemd: Start Ghostty service + create participant Ghostty + systemd->>Ghostty: Start Ghostty service + Ghostty->>systemd: Started + Ghostty->>D-Bus: I'm here! + D-Bus->>Ghostty: Create a new window + Ghostty->>D-Bus: OK +``` + +This ensures that any startup delay caused by GTK (or any other initialization) is +only incurred once per login. + +The Ghostty `systemd` user service can be configured to start up as soon as you +log in by running this command: + +```sh +systemctl enable --user com.mitchell.ghostty.service +``` + +By doing so any startup delay will be "hidden" by the time that your system +needs to finish setting up everything after logging in. + +## Stopping Ghostty + +The Ghostty `systemd` user service can be stopped by running: + +```sh +systemctl stop --user com.mitchellh.ghostty.service +``` + +> [!WARNING] +> +> There is a chance of data loss if the above command is run while there are any +> open Ghostty windows with programs running in them. Any programs running in +> Ghostty windows will be killed without asking for any confirmation. + +## Logs + +Any logs emitted by the Ghostty `systemd` user service can be seen by running +this command: + +```sh +journalctl -a -f --user -u com.mitchellh.ghostty.service +``` + +## Creating New Windows + +With D-Bus activation and `systemd` user services in use, simply launching +`ghostty` from the CLI (or through a global keybind) will not create a new +Ghostty terminal window. The following command can be used to send a D-Bus +signal to Ghostty to create a new window: + +```sh +gdbus call --session --dest com.mitchellh.ghostty --object-path /com/mitchellh/ghostty --method org.gtk.Actions.Activate new-window [] [] +``` + +This command will create a new Ghostty window even if Ghostty is not already +running as D-Bus activation will cause Ghostty to be launched. + +## Reloading the Config + +In addition to other methods, sending the `USR2` signal to the Ghostty process +will trigger a configuration reload. + +## Debug Installations + +If you have installed a debug version of Ghostty, the above commands and file +paths need to be altered slightly: + +```sh +systemctl enable --user com.mitchell.ghostty-debug.service +journalctl -a -f --user -u com.mitchellh.ghostty-debug.service +gdbus call --session --dest com.mitchellh.ghostty-debug --object-path /com/mitchellh/ghostty_debug --method org.gtk.Actions.Activate new-window [] [] +``` + +These are the files that control the launching of Ghostty if installed as +a user: + +``` +$PREFIX/share/applications/com.mitchellh.ghostty-debug.desktop +$PREFIX/share/dbus-1/services/com.mitchellh.ghostty-debug.service +$PREFIX/share/systemd/user/com.mitchellh.ghostty-debug.service +``` + +If installed as a system package, the files will be found in the following +locations: + +``` +$PREFIX/share/applications/com.mitchellh.ghostty-debug.desktop +$PREFIX/share/dbus-1/services/com.mitchellh.ghostty-debug.service +$PREFiX/lib/systemd/user/com.mitchellh.ghostty-debug.service +```