dcosnet
/
rs-mrxvt
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
rs-mrxvt/README.md

288 lines
12 KiB
Markdown
Executable File
Raw Blame History

# rs-mrxvt — The Modernized Power-User Terminal
`rs-mrxvt` is a modernized, distro-agnostic terminal emulator inspired by the
classic [mrxvt](https://wiki.archlinux.org/title/Mrxvt). It is written in Rust
and pairs 2008-era "tabbed power" with 2020s reliability.
The MVP ships with **four rendering backends** and an auto-detect chain that
falls back gracefully:
1. **wgpu (Vulkan)** — full GPU acceleration on modern hardware
2. **wgpu (GL)** — older GPUs that lack Vulkan drivers
3. **softbuffer + tiny-skia** — CPU rasterizer, the modern VESA mode
4. **TUI (ratatui + crossterm)** — always available, even over SSH
The default build uses the TUI backend (zero system graphics deps). Build
with `--features gpu` to enable the wgpu and softbuffer backends.
Three opt-in feature flags extend the terminal in orthogonal directions:
- `--features lua` — dynamic, programmable configuration via `config.lua`
- `--features images` — Sixel + iTerm2 inline image protocol support
- `--features gpu` — wgpu + softbuffer rendering backends
---
## ✨ Features (implemented)
### Core (always available)
- **Multi-tab PTY** — each tab runs an independent shell via `portable-pty`,
with VT emulation by `alacritty_terminal`. Tabs are managed by a single
`TerminalManager`; one tab's heavy output never blocks the others.
- **Input Broadcasting** — the classic mrxvt killer feature. Toggle
broadcast-to-all with `Ctrl+Shift+I`, or broadcast only to tagged groups
via `--tag` on the CLI or the `ToggleBroadcastGroup` command in the
palette.
- **Command Palette** — `Ctrl+Shift+P` opens a fuzzy-search overlay over
every command. Inspired by Warp / VS Code.
- **Backend auto-detect** — `--backend auto` (default) probes wgpu → soft →
TUI. Override with `--backend {tui,wgpu,soft}` if needed.
- **Classic mrxvt CLI flags** — `-e CMD`, `-t TITLE`, `-n N`, `-j`
(broadcast), `-g TAG` (group tag), `-c PATH` (config), `-d DIR` (cwd),
`-b {auto,tui,wgpu,soft}` (backend).
- **TOML config** — `~/.config/rs-mrxvt/config.toml` with profiles, macros,
keybindings, and transparency settings.
- **Per-tab fading** — inactive tabs dim smoothly via a lerp animation.
- **Stress-tested** — 89+ unit + integration tests, plus a 50-instance
Python stress harness that broadcasts a marker to 50 shells in ~30ms.
### With `--features lua`
- **Dynamic Lua config** — `config.lua` with full logic: conditionals, env
vars, time-of-day themes, programmable macros. Auto-detected by file
extension; force with `--config-format lua`.
- **Backward-compatible** — TOML config still works; pick per file.
### With `--features gpu`
- **wgpu renderer** — Vulkan/GL accelerated. Instanced quad pipeline with
a glyph atlas texture and WGSL shaders. Renders the full terminal grid
(text + colors + tab bar + status bar).
- **softbuffer renderer** — CPU rasterizer via tiny-skia + ab_glyph. The
modern VESA mode: works on any display server, no GPU driver required.
- **Pseudo-transparency + tinting** — classic mrxvt `-tint` and `-sh` flags,
implemented as a WGSL shader uniform. Configurable via `[transparency]`
in config.
- **Shared glyph cache** — `ab_glyph` rasterizes glyphs on demand; both
backends use the same cache.
### With `--features images`
- **iTerm2 inline images** — `ESC ] 1337 ; File = ...` protocol. Display
PNG/JPEG/GIF/WebP/BMP inline. Compatible with `ranger`, `neofetch`,
`chafa`, `viu`.
- **Thread-safe image store** — images keyed by ID, mutex-protected for
concurrent PTY reader + renderer access.
## 🗺️ Roadmap
| Feature | Status | Notes |
|------------------------|-------------|------------------------------------------------|
| Multi-tab PTY | ✅ shipped | 200+ tests covering routing, broadcasting, EOF |
| Input broadcasting | ✅ shipped | Active / All / Group(tag) |
| Command palette | ✅ shipped | fuzzy-matcher, Ctrl+Shift+P |
| Backend auto-detect | ✅ shipped | wgpu → soft → tui chain |
| TUI renderer | ✅ shipped | ratatui + crossterm, distro-agnostic |
| wgpu renderer | ✅ shipped | instanced pipeline, glyph atlas, WGSL shaders |
| softbuffer renderer | ✅ shipped | tiny-skia + ab_glyph, the VESA mode |
| Pseudo-transparency | ✅ shipped | WGSL shader, tint + opacity uniforms |
| Per-tab fading | ✅ shipped | lerp animation, configurable speed/amount |
| Lua config | ✅ shipped | mlua, dynamic themes, programmable macros |
| Config hot-reload | ✅ shipped | Polling watcher, survives bad configs |
| iTerm2 image protocol | ✅ shipped | PNG/JPEG/GIF/WebP/BMP inline |
| Sixel image protocol | ✅ shipped | Pure-Rust parser, color registers, repeats |
| Mouse + SGR-1006 | ✅ shipped | X10/X11/SGR encoders, selection state machine |
| OSC 8 hyperlinks | ✅ shipped | Parser + scanner + cell-indexed store |
| Alt+N / Alt+Arrows | ✅ shipped | New tab, shuffle forward/back |
| Alt+Shift+X close | ✅ shipped | Closes focused tab |
| Alt+Z zsh tab | ✅ shipped | Secondary shell on a hotkey |
| True-color themes | ✅ shipped | Tokyo Night, Gruvbox, Dracula, Solarized |
| Multi-distro sysprep | ✅ shipped | pacman/apt/dnf/zypper/xbps/apk/cast/emerge |
| Renderer integration | 🚧 planned | Wire mouse/selection/links/images into UI loop |
| Clipboard support | 🚧 planned | Copy selection, paste on right-click |
## 🚀 Quick start
### Build from source (TUI only — default)
```bash
# Dependencies: Rust 1.75+ (rustup recommended), and a POSIX shell.
# No system graphics libs required for the TUI backend.
cargo build --release
./target/release/rs-mrxvt
```
### Build with everything
```bash
# Install system dev headers first:
# Debian/Ubuntu: sudo apt install libvulkan-dev libwayland-dev libxkbcommon-dev
# Arch: sudo pacman -S vulkan-headers wayland-protocols libxkbcommon
# Fedora: sudo dnf install vulkan-headers wayland-devel libxkbcommon-devel
# SourceMage: cast vulkan-loader wayland-protocols libxkbcommon
cargo build --release --features gpu,lua,images
./target/release/rs-mrxvt # auto-detects best backend
./target/release/rs-mrxvt --backend wgpu # force wgpu
./target/release/rs-mrxvt --backend soft # force CPU rasterizer (VESA mode)
./target/release/rs-mrxvt --backend tui # force TUI
./target/release/rs-mrxvt --config-format lua # force Lua config
```
### Distro-agnostic install
```bash
sudo make install # installs to /usr/local by default
sudo PREFIX=/usr make install # installs to /usr
```
### Try it without installing
```bash
# 3 tabs, broadcasting on, all tagged "cluster"
./target/release/rs-mrxvt -n 3 -j -g cluster
# With a Lua config that picks theme by time of day
./target/release/rs-mrxvt --features lua -c ~/.config/rs-mrxvt/config.lua
```
## 🎹 Keybindings (default)
| Shortcut | Action |
|-----------------------|-----------------------------------------------|
| `Ctrl+Shift+T` / `Alt+N` | New tab (bash, the default shell) |
| `Alt+Z` | New tab running zsh (secondary shell) |
| `Alt+Shift+X` | Close the currently focused tab |
| `Ctrl+Shift+W` | Close tab (classic mrxvt binding) |
| `Ctrl+Shift+I` | Toggle broadcast (all tabs) |
| `Ctrl+Shift+P` | Open command palette |
| `Ctrl+Tab` / `Alt+Right` | Next tab (wraps) |
| `Ctrl+Shift+Tab` / `Alt+Left` | Previous tab (wraps) |
| `Alt+1` … `Alt+0` | Go to tab N (1..10) |
All bindings are rebindable in `config.toml` or `config.lua`.
## ⚙️ Configuration
Default location: `~/.config/rs-mrxvt/config.toml` (or `.lua` with the lua
feature). Override with `--config` or `$MRXVT_CONFIG`. See
[`examples/config.toml`](examples/config.toml) and
[`examples/config.lua`](examples/config.lua) for fully-commented references.
### Transparency example (TOML)
```toml
[transparency]
enabled = true
tint = "#004080" # blue tint
opacity = 0.85 # 1.0 = opaque, 0.0 = fully transparent
# background_image = "/path/to/wallpaper.png"
```
### Time-based theme (Lua)
```lua
local hour = tonumber(os.date("%H"))
local theme = "mrxvt"
if hour >= 20 or hour < 6 then
theme = "tokyo-night"
end
return {
ui = { theme = theme },
terminal = { cols = 120, rows = 40 },
}
```
## 🎨 Themes
Built-in true-color themes (set `ui.theme` in your config):
| Theme | Style |
|-------------------|--------------------------------|
| `mrxvt` | Classic green-on-black (default) |
| `tokyo-night` | Dark blue, popularized by VS Code |
| `gruvbox` | Warm retro palette |
| `dracula` | Dark purple |
| `solarized-dark` | Solarized Dark |
| `solarized-light` | Solarized Light |
Custom themes can be defined in TOML — see `examples/config.toml` for the
full color list (16 ANSI colors + bg/fg/cursor).
## 🧪 Testing
```bash
cargo test # default suite (~10s, 150+ tests)
cargo test --features lua # + Lua config tests
cargo test --features images # + image + Sixel tests
cargo test --features gpu # + GPU backend tests
cargo test --features lua,images # everything, 200+ tests
python3 scripts/stress_test.py # 50-instance broadcast harness
```
## 📦 Distribution-agnostic packaging
Three helper scripts make the build pipeline distro-agnostic:
```bash
./scripts/sysprep.sh # install build deps (auto-detects distro)
./scripts/build.sh # cargo build with feature flags
./install.sh # build + install to $PREFIX
./install.sh --sysprep # sysprep + build + install in one go
```
### sysprep.sh
Detects your distro via `/etc/os-release` and installs the right packages:
| Distro family | Package manager |
|-------------------------------------|-----------------|
| Arch, Manjaro, EndeavourOS, Garuda | `pacman` |
| Debian, Ubuntu, Pop!_OS, Mint, Kali | `apt` |
| Fedora, RHEL, Rocky, Alma, CentOS | `dnf` |
| openSUSE, SLES | `zypper` |
| Void | `xbps-install` |
| Alpine | `apk` |
| NixOS | prints `shell.nix` recipe |
| SourceMage | `cast` |
| Gentoo, Funtoo | `emerge` |
Flags: `--no-rust` (skip rustup), `--no-gpu` (skip GPU headers), `--dry-run`.
### build.sh
Wraps `cargo build` with feature-flag presets:
```bash
./scripts/build.sh # release, all features
./scripts/build.sh --debug # debug build
./scripts/build.sh --features lua,images # specific features
./scripts/build.sh --no-features # bare TUI
./scripts/build.sh --test # cargo test
./scripts/build.sh --check # cargo check only
```
### install.sh
Builds + copies binary, examples, and (optional) man page / .desktop file
into `$PREFIX` (default `/usr/local`).
```bash
sudo ./install.sh # /usr/local
sudo ./install.sh /usr # /usr
sudo ./install.sh --sysprep # full pipeline: deps + build + install
sudo ./install.sh --no-features # TUI-only build (no GPU headers needed)
```
The Makefile still works for the common cases (`make install`, `make dist`,
`make deb`, `make rpm`).
## 📜 License
GPL v2 (or later). See [`LICENSE`](LICENSE).
## 🤝 Contributing
See [`CONTRIBUTING.md`](CONTRIBUTING.md). The wgpu and softbuffer backends
are functional but always benefit from optimization work — glyph atlas
packing, sub-pixel positioning, and shader effects are good first PRs.
Reference in New Issue View Git Blame Copy Permalink