Port psyTerm to macOS and package a native app bundle
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# psyTerm
|
||||
|
||||
A Wayland terminal and multiplexer built with [GPUI 0.2.2](https://gpui.rs/)
|
||||
A terminal and multiplexer for macOS and Linux (Wayland), built with [GPUI 0.2.2](https://gpui.rs/)
|
||||
and [alacritty_terminal 0.26.0](https://docs.rs/alacritty_terminal/0.26.0/).
|
||||
A separate server owns terminal emulation, shells, tabs, panes, and scrollback.
|
||||
GUI processes display its snapshots and send input commands. Closing a window
|
||||
@@ -8,8 +8,41 @@ detaches it; the shells keep running for the next local or remote connection.
|
||||
|
||||
## Build and run
|
||||
|
||||
Use recent stable Rust (development uses 1.96) and Linux 5.3 or newer. GUI
|
||||
processes require a running Wayland desktop and a working Vulkan driver.
|
||||
Use recent stable Rust and build with `--locked` to use the dependency versions
|
||||
in `Cargo.lock`.
|
||||
|
||||
### macOS
|
||||
|
||||
Install Xcode or its Command Line Tools (`xcode-select --install`). GPUI embeds
|
||||
its Metal shader source and compiles it when the GUI opens. To launch from a
|
||||
checkout, run `cargo run --locked`.
|
||||
|
||||
Install cargo-bundle once to build the Finder-launchable app. This is the
|
||||
version used by [Zed](https://github.com/zed-industries/zed/blob/main/script/bundle-mac).
|
||||
|
||||
```sh
|
||||
cargo install --locked --git https://github.com/zed-industries/cargo-bundle \
|
||||
--rev 2be2669972dff3ddd4daf89a2cb29d2d06cad7c7 cargo-bundle
|
||||
```
|
||||
|
||||
Build the release executable, package it, and sign the bundle locally.
|
||||
|
||||
```sh
|
||||
cargo build --locked --release
|
||||
CARGO_BUNDLE_SKIP_BUILD=true cargo bundle --release --format osx --select-workspace-root
|
||||
codesign --force --sign - target/release/bundle/osx/psyTerm.app
|
||||
open target/release/bundle/osx/psyTerm.app
|
||||
```
|
||||
|
||||
You can copy `psyTerm.app` to Applications. The bundle and CLI both open a GUI
|
||||
in the launching process and connect to the same local server. Use `open -n`
|
||||
with the app path for another window. The bundle's
|
||||
`Contents/MacOS/psyterm` executable also accepts the CLI commands below.
|
||||
|
||||
### Linux
|
||||
|
||||
Use Linux 5.3 or newer. GUI processes require a running Wayland desktop and
|
||||
a working Vulkan driver.
|
||||
The server and SSH bridge do not initialize GPUI, Wayland, or Vulkan, although
|
||||
the shared executable still needs its dynamically linked libraries installed.
|
||||
|
||||
@@ -44,13 +77,18 @@ cargo build --locked --release
|
||||
|
||||
The default command starts or reuses a local server, asks its zygote to fork a
|
||||
GUI, and returns. Running it again opens another view of the same workspace.
|
||||
The first attachment to an empty server creates a shell. Shells use the
|
||||
server's `$SHELL` (falling back to `/bin/sh`), environment, and startup directory;
|
||||
they receive `TERM=xterm-256color` and `COLORTERM=truecolor`.
|
||||
|
||||
The server retains its startup environment. Set shell or GUI environment
|
||||
preferences before starting that server, or use `--gui` to launch a diagnostic
|
||||
GUI directly from the current environment. After rebuilding, the server refreshes
|
||||
### Shells and sessions
|
||||
|
||||
The first attachment to an empty server creates a shell in the server's startup
|
||||
directory. Shells inherit the server's environment and receive
|
||||
`TERM=xterm-256color` and `COLORTERM=truecolor`. The server uses `$SHELL`
|
||||
when set. On macOS it starts a login shell and falls back to the shell in
|
||||
your account settings. On Linux the fallback is `/bin/sh`.
|
||||
|
||||
The server retains its startup environment. Set shell preferences before
|
||||
starting the server. On Linux, use `--gui` to launch a diagnostic GUI directly
|
||||
from the current environment. After rebuilding on Linux, the server refreshes
|
||||
its zygote for new GUI windows, preserving existing windows and shells. Changes
|
||||
to server logic or the protocol still require restarting the server;
|
||||
`--shutdown` also ends its shell sessions.
|
||||
@@ -64,9 +102,9 @@ Finish any running work first, since shutdown ends its sessions, then launch
|
||||
|
||||
| Command | Behavior |
|
||||
| --- | --- |
|
||||
| `psyterm` | Open a local window through the server's zygote |
|
||||
| `psyterm` | Open a local window attached to the server |
|
||||
| `psyterm --remote user@host` | Open a local GUI connected to the remote server over SSH |
|
||||
| `psyterm --gui` | Launch a GUI directly, bypassing the zygote |
|
||||
| `psyterm --gui` | Run the GUI in the current process |
|
||||
| `psyterm --list` | Inspect tabs and panes in the running local server |
|
||||
| `psyterm --shutdown` | Stop the local server and end its sessions |
|
||||
| `psyterm --server` | Run the terminal server in the foreground |
|
||||
@@ -75,16 +113,17 @@ Finish any running work first, since shutdown ends its sessions, then launch
|
||||
|
||||
By default the socket is `$XDG_RUNTIME_DIR/psyterm/server.sock`, with a private
|
||||
per-user temporary directory as fallback. A custom socket must have a real,
|
||||
user-owned parent directory with mode `0700`:
|
||||
user-owned parent directory with mode `0700`.
|
||||
|
||||
```sh
|
||||
mkdir -m 700 "$XDG_RUNTIME_DIR/psyterm-dev"
|
||||
cargo run --locked -- --socket "$XDG_RUNTIME_DIR/psyterm-dev/server.sock"
|
||||
socket_dir=$(mktemp -d /tmp/psyterm.XXXXXXXX)
|
||||
cargo run --locked -- --socket "$socket_dir/server.sock"
|
||||
```
|
||||
|
||||
Sockets and log files are private to the current UID; peers are checked with
|
||||
Linux credentials. Server and zygote logs are beside the socket as
|
||||
`server.sock.log` and `server.sock.zygote.log`.
|
||||
Sockets and log files are private to the current UID. psyTerm checks the peer's
|
||||
UID using `getpeereid` on macOS and `SO_PEERCRED` on Linux. The server logs
|
||||
to `server.sock.log` beside the socket. The Linux zygote logs to
|
||||
`server.sock.zygote.log`.
|
||||
|
||||
SSH uses `BatchMode=yes`: configure key/agent authentication and known-host trust
|
||||
before connecting. The remote host needs a compatible `psyterm` executable in
|
||||
@@ -210,7 +249,7 @@ scrollback by default.
|
||||
| --- | --- |
|
||||
| `server.rs`, `session.rs` | Authoritative workspace, PTYs, child processes, parser, terminal grids, selection, scrolling, and resize |
|
||||
| `protocol.rs`, `client.rs` | Versioned bounded messages, local socket / SSH transport, snapshot delivery |
|
||||
| `launcher.rs` | Server startup, private paths, lifecycle locks, and the server-owned GUI zygote |
|
||||
| `launcher.rs` | Server startup, private paths, lifecycle locks, and platform-specific GUI launch |
|
||||
| `terminal.rs` | Snapshot-only GUI workspace and panes, command dispatch, focus, and animation scheduling |
|
||||
| `commands.rs`, `bindings.rs`, `palette.rs` | Extensible command metadata, optional shortcuts, searchable nested menus |
|
||||
| `pane_name.rs`, `label.rs` | Pane name editor, Unicode composition, and middle-truncated labels |
|
||||
@@ -218,7 +257,7 @@ scrollback by default.
|
||||
| `chrome.rs`, `colors.rs`, `fonts.rs` | Window chrome, terminal colors, font selection |
|
||||
| `input.rs`, `main.rs` | Key/paste encoding and CLI/process-role dispatch |
|
||||
|
||||
The server starts the zygote on demand and manages its lifetime. The zygote
|
||||
On Linux, the server starts the zygote on demand and manages its lifetime. The zygote
|
||||
checks that it is single-threaded and forks GUI children **before** GPUI,
|
||||
Wayland, Vulkan, font discovery, or executors initialize. Children inherit the
|
||||
loaded executable mappings and avoid another `exec`; graphics and font setup
|
||||
@@ -289,10 +328,8 @@ executable refreshed its zygote while the original GUI and shell stayed alive.
|
||||
New live checks cover palette search/submenus and input isolation, Zellij
|
||||
navigation bindings, stack insertion in both directions, collapsed-pane focus,
|
||||
exit cleanup, and stack reattachment. A second client's focus changes preserve
|
||||
palette input. These are Linux checks; remote-network latency and macOS remain
|
||||
unverified.
|
||||
palette input. These checks cover Linux Wayland.
|
||||
|
||||
Linux Wayland is the implemented platform; macOS is a future target. Current
|
||||
limits include no arbitrary split trees or floating panes, shared per-server
|
||||
Current limits include no arbitrary split trees or floating panes, shared per-server
|
||||
viewport state, no disk-restored sessions, no configuration files, no application mouse reporting,
|
||||
no Kitty keyboard protocol, no OSC 52 clipboard access, and no clickable links.
|
||||
|
||||
Reference in New Issue
Block a user