80 lines
3.7 KiB
Markdown
80 lines
3.7 KiB
Markdown
|
# Using gasm-devkit with Zed
|
||
|
|
|
||
|
|
This document is deliberately blunt, because the situation is a genuine
|
||
|
|
conflict between two of the project's own commitments, and papering over it
|
||
|
|
would be dishonest.
|
||
|
|
|
||
|
|
## The conflict
|
||
|
|
|
||
|
|
gasm-devkit is **pure Go, no C, no cgo, no JavaScript runtimes, no native
|
||
|
|
binaries, no vendor lock-in, no platform-specific IDE internals.**
|
||
|
|
|
||
|
|
Zed's extension model, as verified against Zed's own documentation, is:
|
||
|
|
|
||
|
|
- Extensions are written in **Rust** and compiled to **WebAssembly**
|
||
|
|
(`wasm32-wasip2`).
|
||
|
|
- Syntax highlighting is provided by **Tree-sitter** grammars, which are
|
||
|
|
**C** compiled to WebAssembly with the wasi-sdk, from a grammar written in a
|
||
|
|
**JavaScript** DSL.
|
||
|
|
- A *new* language cannot be registered through configuration alone. Defining
|
||
|
|
a language requires an extension, and every language extension must name a
|
||
|
|
Tree-sitter grammar. (Zed's `lsp` settings section configures
|
||
|
|
already-registered servers; it does not register an arbitrary external binary
|
||
|
|
for a brand-new language.)
|
||
|
|
|
||
|
|
There is therefore **no pure-Go path into Zed's extension host.** This is a
|
||
|
|
property of Zed, not of gasm-devkit: no language tooling author can feed Zed a
|
||
|
|
pure-Go highlighting grammar, because Zed's highlighting engine is Tree-sitter
|
||
|
|
and its plugin runtime is Rust/WASM.
|
||
|
|
|
||
|
|
## What gasm-devkit gives Zed regardless
|
||
|
|
|
||
|
|
The toolkit's integration surface is the **Language Server Protocol**, an open
|
||
|
|
standard. Through `gasm lsp` it provides, with zero editor-specific code:
|
||
|
|
|
||
|
|
- autocomplete (instructions, registers, pseudo-registers, labels),
|
||
|
|
- hover documentation,
|
||
|
|
- diagnostics (the linter, pushed as you type),
|
||
|
|
- document outline (functions and labels),
|
||
|
|
- **syntax highlighting, delivered as LSP semantic tokens.**
|
||
|
|
|
||
|
|
That last point matters: Zed can render highlighting entirely from LSP semantic
|
||
|
|
tokens (`"semantic_tokens": "full"` replaces Tree-sitter highlighting for a
|
||
|
|
language). So the highlighting *capability* exists in pure Go; what Zed needs
|
||
|
|
is merely to be told that `.s` files are a language served by `gasm lsp`.
|
||
|
|
|
||
|
|
## The honest options
|
||
|
|
|
||
|
|
1. **Use an editor that registers an external LSP by configuration.**
|
||
|
|
Neovim, Helix, VS Code and Sublime all let you associate `.s` with the
|
||
|
|
`gasm lsp` binary and use its semantic tokens — no Rust, no C, no lock-in.
|
||
|
|
This is the option that satisfies every stated constraint with no
|
||
|
|
exception.
|
||
|
|
|
||
|
|
2. **Treat a Zed adapter as one quarantined exception.** A minimal Zed
|
||
|
|
extension — a few lines of Rust that register the language and launch
|
||
|
|
`gasm lsp` — plus either a Tree-sitter grammar or `"full"` semantic tokens
|
||
|
|
for highlighting. Crucially, this adapter is the *editor's plugin format*;
|
||
|
|
it is sandboxed inside Zed and never linked into, compiled into, or shipped
|
||
|
|
with the Go toolkit. gasm-devkit itself stays pure Go. But producing it
|
||
|
|
uses the Rust/wasi-sdk/Tree-sitter toolchain, which the project constraints
|
||
|
|
forbid — so it must be a conscious, explicit decision, not a silent one.
|
||
|
|
|
||
|
|
The author's philosophy — digital sovereignty, no dependency on toolchains he
|
||
|
|
does not control — is the tie-breaker, and it is a value judgement rather than
|
||
|
|
a technical one. gasm-devkit is built so that **either** choice keeps the
|
||
|
|
toolkit itself clean: the pure-Go core and the LSP are the product; a Zed
|
||
|
|
adapter, if ever wanted, is a thin, separable leaf.
|
||
|
|
|
||
|
|
## Wiring the LSP (editor-agnostic)
|
||
|
|
|
||
|
|
Run the server and point an LSP client at it:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
go run ./cmd/gasm lsp # or: go install ./cmd/gasm && gasm lsp
|
||
|
|
```
|
||
|
|
|
||
|
|
Associate the command with `*.s` (and `*_amd64.s` / `*_arm64.s`) in whichever
|
||
|
|
editor you use. The server infers the target architecture from the file-name
|
||
|
|
suffix and selects the amd64 or arm64 instruction tables accordingly.
|