282 lines
13 KiB
Markdown
282 lines
13 KiB
Markdown
# Pmacs
|
|
|
|
Parallel Emacs --- a Rust-cored, Lua-scripted editor in the Emacs tradition.
|
|
|
|
Pmacs runs the editor's hot path (rope, buffers, views, async runtime,
|
|
process supervision) in Rust, and exposes the rest --- commands, keymaps,
|
|
hooks, packages --- through an embedded Lua VM. The design follows Emacs
|
|
in shape (configurable, introspectable, programmable from inside) but
|
|
discards the single-threaded substrate; workers, message bus, and a
|
|
coroutine-based async surface are core primitives, not bolt-ons.
|
|
|
|
The editor is partitioned into a long-lived **instance** (the daemon
|
|
that owns buffers, processes, and language services) and thin
|
|
**frontends** that attach over a typed protocol (currently v14). Two
|
|
frontends ship today:
|
|
|
|
- a **TUI** (crossterm cell grid), attachable locally over a Unix
|
|
socket or remotely over SSH, with reconnect-on-drop modeled on
|
|
`mosh`; and
|
|
- **pmacs-gpu**, a GPU frontend (wgpu + winit + glyphon) that renders
|
|
from a *semantic projection* of editor state --- style spans,
|
|
decorations, inlay adornments --- rather than a character grid, and
|
|
edits optimistically against a local CRDT replica for
|
|
latency-free typing.
|
|
|
|
Buffers are optionally CRDT-backed (`loro`, behind `--features crdt`),
|
|
so multiple frontends --- TUI and GPU, local and remote --- can edit
|
|
the same buffers concurrently with live cursor/selection presence.
|
|
|
|
## Status
|
|
|
|
**v1.0.0 --- stable core, active development.** The v1.0 gate (the
|
|
instance/frontend partition, the Lua surface, and a REPL package
|
|
audited to use zero direct Rust core access) shipped some time ago;
|
|
development since has landed the GPU frontend at near input/render
|
|
parity with the TUI, the semantic-frontend protocol (v6 → v14), the
|
|
LSP feature arc, in-buffer search, the context menu + OS clipboard,
|
|
the line-number gutter with diagnostic signs, and the package-manager
|
|
hardening pass. Current direction lives in `docs/roadmap-2026-07.md`.
|
|
Public contributions are open: use, evaluate, file issues, send pull
|
|
requests.
|
|
|
|
## Highlights
|
|
|
|
**Editing & UI.** CUA-style region editing plus Emacs kill/yank
|
|
bindings; linear undo/redo; incremental search, substring and regex
|
|
(`C-s` / `C-r` / `C-M-s`); line-number gutter with absolute, relative,
|
|
and hybrid modes; diagnostic gutter signs; right-click context menu;
|
|
OS clipboard integration (OSC 52 in the TUI, native in the GPU);
|
|
minibuffer with completion dropdown and per-bucket persisted history;
|
|
buffer-list mode (`C-x C-b`); self-navigable help system
|
|
(`describe-command`, `describe-key`); atomic saves (temp + rename +
|
|
parent fsync, mode-preserving).
|
|
|
|
**Language intelligence.** LSP client with async, never-blocking
|
|
requests: diagnostics (severity-colored underlines/squiggles, gutter
|
|
signs, statusline counts, `M-g n`/`M-g p` navigation), rename with
|
|
`prepareRename`, go-to-definition including cross-file navigation,
|
|
hover, signature help, references, document symbols, code actions,
|
|
buffer formatting, semantic tokens, and inlay hints (rendered inline
|
|
in the GPU frontend). Servers are preconfigured for rust-analyzer,
|
|
clangd (C/C++), basedpyright, gopls, typescript-language-server
|
|
(TS/TSX/JS/JSX), lua-language-server, bash-language-server, taplo
|
|
(TOML), and zls (Zig). Syntax highlighting is dual-authority:
|
|
bundled tree-sitter grammars (Rust, Lua, Markdown, C, C++) paint
|
|
lexical structure and LSP semantic tokens refine it --- languages
|
|
without a bundled grammar still get full semantic coloring. A
|
|
persistent project symbol index (`.pmacs/index.json`) rides the same
|
|
worker infrastructure.
|
|
|
|
**Collaboration & frontends.** With `--features crdt`, buffers are
|
|
CRDT-backed and any number of frontends attach to one daemon and edit
|
|
concurrently; peers see each other's cursors and selections as
|
|
translucent washes. The GPU frontend adds a live minimap (click to
|
|
jump, drag to scrub), wavy diagnostic squiggles, a status band with
|
|
live diagnostic counts, and optimistic local editing that rebases
|
|
in-flight edits through authoritative frames.
|
|
|
|
**Extensibility.** ~37 `pmacs.*` Lua namespaces cover buffers,
|
|
windows, commands, keymaps (global/mode/buffer scope), hooks, themes
|
|
(truecolor-capable syntax palette), tree-sitter, LSP stores, async
|
|
workers, and a PTY-aware process supervisor with an ECMA-48 ANSI
|
|
parser. A package manager installs from git (`github:owner/repo`,
|
|
version/branch/commit pins) with transitive dependency resolution and
|
|
a SHA-256 lockfile. Pmacs is also an **MCP client**: packages can
|
|
spawn MCP servers and consume their tools, resources, and prompts ---
|
|
AI integrations are packages over a transport, not a built-in
|
|
feature. The bundled REPL package (PTY shells, ANSI rendering,
|
|
multi-REPL, scrollback retention) is written entirely against the
|
|
public Lua API.
|
|
|
|
## Running
|
|
|
|
Single-process TUI:
|
|
|
|
```sh
|
|
pmacs [FILE] # TUI; -nw reserved for when a GUI default lands
|
|
```
|
|
|
|
Daemon + attached frontends (build with `--features crdt` for
|
|
multi-frontend editing and the GPU frontend):
|
|
|
|
```sh
|
|
pmacs --daemon --socket NAME # foreground daemon; bare NAME →
|
|
# <runtime>/pmacs/NAME.sock
|
|
pmacs --attach --socket NAME # TUI frontend; F12 detaches
|
|
pmacs --attach user@host # remote TUI over SSH
|
|
pmacs-gpu --attach /run/user/$UID/pmacs/NAME.sock # GPU frontend
|
|
```
|
|
|
|
`pmacs --attach` also understands `ssh:user@host/instance`,
|
|
`local:/path.sock`, and bare hostnames (treated as SSH). See
|
|
`pmacs --help` for the full matrix.
|
|
|
|
User configuration is plain Lua at
|
|
`$XDG_CONFIG_HOME/pmacs/init.lua` (default `~/.config/pmacs/init.lua`),
|
|
loaded after the builtin runtime so plain assignments override
|
|
defaults --- keybindings, `pmacs.lsp.config`, theme overrides, and
|
|
package installs all live there.
|
|
|
|
## Build
|
|
|
|
Builds on the toolchain pinned in `rust-toolchain.toml` (Rust
|
|
`1.95.0`, edition 2024); rustup selects it automatically.
|
|
|
|
```sh
|
|
cargo build --release # target/release/pmacs (LuaJIT flavor)
|
|
cargo build --release --features crdt # + CRDT buffers (daemon use)
|
|
cargo build --release -p pmacs-gpu # the GPU frontend binary
|
|
cargo run --release -- <file> # build and run on a file
|
|
cargo test --workspace # unit + integration tests (all crates)
|
|
cargo fmt --check
|
|
cargo clippy --workspace --all-targets -- -D warnings # incl. pmacs-gpu
|
|
```
|
|
|
|
### Feature matrix
|
|
|
|
Cargo features fall into two independent axes. **Do not use
|
|
`--all-features`** — it enables both Lua flavors at once, which cannot
|
|
build (see below).
|
|
|
|
| Feature | Axis | Notes |
|
|
| -------- | ---------- | ---------------------------------------------------------- |
|
|
| `luajit` | Lua flavor | **Default.** LuaJIT backend via `mlua` (vendored). |
|
|
| `lua54` | Lua flavor | Lua 5.4 fallback for hosts without LuaJIT (big-endian, …). |
|
|
| `crdt` | Buffer | Opt-in CRDT-backed buffer mode (adds the `loro` dep). v1.0 builds enable it; orthogonal to the flavor. |
|
|
|
|
**Exactly one Lua flavor must be enabled** — `luajit` *or* `lua54`, never
|
|
both (and never neither). They map to `mlua`'s mutually-exclusive Lua
|
|
backends, so `--all-features` (or `--features luajit,lua54`, or
|
|
`--no-default-features` with no flavor) fails in the `mlua-sys` build
|
|
script with *"You can enable only one of the features: …"*. That check
|
|
lives in a dependency cargo builds first, so pmacs can't replace it with a
|
|
friendlier error — the fix is to build a specific flavor. Supported build
|
|
lines:
|
|
|
|
```sh
|
|
cargo build --release # luajit (default)
|
|
cargo build --release --no-default-features --features lua54
|
|
cargo build --release --features crdt # luajit + crdt
|
|
cargo build --release --no-default-features --features lua54,crdt
|
|
```
|
|
|
|
CI, `cargo hack`, and distro tooling should iterate the flavors
|
|
explicitly (`--no-default-features --features <flavor>[,crdt]`) rather
|
|
than reaching for `--all-features`. Both flavors pass the full test suite;
|
|
CI runs the matrix on every push.
|
|
|
|
Release-only perf gates (M5 keystroke-to-render, M6 ingest/RSS/cancel
|
|
and scrollback navigation/search) are `#[ignore]`'d during normal
|
|
test runs and exercised in CI under dedicated jobs. The GPU frontend
|
|
has headless render tests (offscreen wgpu, pixels read back) that run
|
|
in CI under lavapipe and skip gracefully on machines without a Vulkan
|
|
adapter (`PMACS_REQUIRE_GPU=1` turns a missing adapter into a hard
|
|
failure).
|
|
|
|
## Runtime requirements
|
|
|
|
The pmacs binary depends on a small set of POSIX command-line tools
|
|
at runtime. The dependency exists because the project enforces
|
|
`#![forbid(unsafe_code)]` everywhere, including in tests; calls that
|
|
would otherwise need `unsafe` (PTY raw-mode setup, signal name
|
|
translation) are routed through trampolines that exec these tools.
|
|
|
|
- **`/bin/sh`** (POSIX shell). Used for the PTY raw-mode trampoline:
|
|
`/bin/sh -c 'stty raw -echo </dev/tty 2>/dev/null; exec "$@"' --`
|
|
configures the controlling TTY's line discipline before exec'ing
|
|
the actual subprocess. Required by the REPL package and any other
|
|
caller that spawns a process in raw PTY mode.
|
|
- **`stty`** (coreutils). The line-discipline configurator invoked
|
|
by the trampoline above.
|
|
- **`coreutils`** more broadly. The M6 process-supervisor tests
|
|
spawn `cat`, `yes`, and `which`; absent these the test suite (not
|
|
the editor itself) degrades. `which` is also used by the M6.5
|
|
shell-locator helper to find `bash` / `zsh` / `fish` for
|
|
per-shell integration tests. The M7.2 fetcher's timeout test
|
|
uses `sleep`.
|
|
- **`git`** (added in M7.2). Required for any package operation:
|
|
the package fetcher shells out to `git` to clone, fetch, and
|
|
resolve refs, with a deterministic environment
|
|
(`GIT_TERMINAL_PROMPT=0`, `GIT_CONFIG_NOSYSTEM=1`, `LC_ALL=C`,
|
|
inherited `GIT_*` variables stripped). Authentication for
|
|
private repositories rides the user's existing git configuration
|
|
(credential helpers, SSH agent), so packagers do not need a
|
|
separate auth story. Pre-M7 builds without package operations
|
|
do not need git.
|
|
- **`tar`** (added in M7.3). Required for `pmacs.packages.install`:
|
|
the installer materializes a snapshot via `git archive --format=tar`
|
|
piped into `tar -x -C <dest>`, which keeps the on-disk install
|
|
directory self-contained (no `.git` linkage back to the bare
|
|
cache, no working-tree state). GNU tar and bsdtar both work.
|
|
Pre-M7 builds and any path that doesn't call
|
|
`pmacs.packages.install{...}` do not need tar.
|
|
|
|
Distribution packagers should ensure these are runtime dependencies
|
|
of the pmacs package. On a typical Linux distribution, busybox or
|
|
GNU coreutils plus a shell of any kind satisfies the requirement; on
|
|
macOS the system shell and `/usr/bin/stty` are both standard.
|
|
|
|
The Lua VM (LuaJIT or Lua 5.4) is statically vendored via `mlua`'s
|
|
`vendored` feature, so there is no external Lua dependency at
|
|
runtime.
|
|
|
|
The GPU frontend additionally needs a Vulkan-capable driver stack
|
|
(any real GPU driver, or lavapipe for software rendering); its font
|
|
(JetBrains Mono, OFL-licensed) is bundled into the binary.
|
|
|
|
## Layout
|
|
|
|
The workspace has three first-party crates:
|
|
|
|
```
|
|
src/ pmacs — the core + TUI + daemon
|
|
rope.rs persistent byte-sequence backing every buffer
|
|
buffer.rs buffer + view chain + undo/redo
|
|
editor_core.rs cursor + commands + edit dispatch
|
|
crdt.rs loro-backed CRDT buffer state (feature `crdt`)
|
|
daemon.rs instance side of the frontend partition
|
|
attach.rs frontend side; transports + reconnect
|
|
semantic_render.rs semantic-frame producer (StyleSpans, Decorations, …)
|
|
lsp.rs language-server client
|
|
diag.rs, highlight.rs diagnostic + syntax/semantic-token rendering
|
|
syntax.rs tree-sitter integration
|
|
search.rs incremental search (substring + regex)
|
|
minibuffer.rs prompt, completion, persisted history
|
|
menu.rs context-menu model
|
|
file_io.rs atomic saves + external-modification detection
|
|
async_runtime.rs worker pool + message bus
|
|
process.rs PTY-aware process supervisor
|
|
ansi.rs ECMA-48 parser
|
|
project.rs, project_index.rs project detection + symbol index
|
|
packages/ resolver, fetcher, installer, lockfile, loader
|
|
mcp.rs MCP client (packages speak to MCP servers)
|
|
lua_bindings/ pmacs.* Lua surface installers
|
|
text_view.rs cell-grid renderer
|
|
frontend.rs crossterm TUI
|
|
main.rs entry point (TUI / daemon / attach modes)
|
|
|
|
pmacs-protocol/ wire types + framing codec shared by all frontends
|
|
pmacs-gpu/ the GPU frontend (wgpu + winit + glyphon)
|
|
|
|
builtin/ Lua runtime shipped with the binary
|
|
commands/default.lua named commands for every editor primitive
|
|
keymaps/default.lua default key bindings
|
|
hooks/default.lua built-in hook definitions
|
|
menus/default.lua context-menu items
|
|
runtime/ async, lsp, syntax, mcp, fs runtimes
|
|
packages/repl/ the bundled REPL package
|
|
|
|
docs/ design notes, framing docs, and the roadmap
|
|
tests/ integration tests (acceptance gates per milestone)
|
|
```
|
|
|
|
## License
|
|
|
|
Dual-licensed under either of:
|
|
|
|
- MIT License ([LICENSE-MIT](LICENSE-MIT))
|
|
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
|
|
|
|
at your option.
|