From 1acac2b73cee36b90316e24ddf38d18fd1cbb396 Mon Sep 17 00:00:00 2001 From: Lazar Bulovan Date: Sun, 19 Jul 2026 15:09:58 +0200 Subject: [PATCH] docs: rewrite installation with architecture overview, troubleshooting, and cross-references --- README.md | 170 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 112 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index f3688ce..6e9922f 100644 --- a/README.md +++ b/README.md @@ -15,77 +15,120 @@ A Neovim/LazyVim plugin that launches the [`tia-lsp`](https://gitea.l-tech.rs/la | **Attribute Block Toggle** | Interactive expand/collapse of `{...}` blocks with `xa` | | **Tree-sitter Highlighting** | Syntax highlighting via tree-sitter queries | +## Architecture + +This plugin is part of a three-repo ecosystem: + +``` +tia-lsp.nvim ← Neovim plugin (you are here) — launches the LSP client, +│ adds editor features (auto-# prefix, blink.cmp source, +│ attribute toggle, workspace scanning, ...) +▼ +tia-lsp ← Standalone LSP server — reads JSON-RPC over stdio, +│ provides hover, completion, diagnostics, formatting +│ Requires: lua src/main.lua + compiled parser.so +▲ +tia-mason-registry ← mason.nvim recipe — tells mason how to download tia-lsp, + compile parser.so, and create the tia-lsp executable +``` + +- **tia-lsp** ([repo](https://gitea.l-tech.rs/lazar/tia-lsp)) — the actual language server, editor-agnostic +- **tia-mason-registry** ([repo](https://gitea.l-tech.rs/lazar/tia-mason-registry)) — a single `package.yaml` for mason +- **tia-lsp.nvim** (this repo) — the Neovim-specific integration + ## Installation -The plugin auto-detects the mason-installed `tia-lsp` executable via `vim.fn.exepath("tia-lsp")` and falls back to `lua ` for manual installs. +The plugin auto-detects the mason-installed `tia-lsp` executable via `vim.fn.exepath("tia-lsp")`. If not found, it falls back to running `lua ` (configurable). ### LazyVim + Mason (Recommended) -1. Add the mason registry as a lazy.nvim plugin: - ```lua - -- ~/.config/nvim/lua/plugins/tia-mason-registry.lua - return { - url = "https://gitea.l-tech.rs/lazar/tia-mason-registry.git", - name = "tia-mason-registry", - lazy = false, -- must be available before mason setup - } - ``` +Mason downloads and builds the `tia-lsp` server; this plugin configures the LSP client. -2. Register the registry with mason: - ```lua - -- ~/.config/nvim/lua/plugins/mason.lua - return { - "mason-org/mason.nvim", - opts = { - registries = { - "file:" .. vim.fn.expand("~/.local/share/nvim/lazy/tia-mason-registry"), - "github:mason-org/mason-registry", - }, - }, - } - ``` +**Step 1: Add the mason registry as a lazy.nvim plugin** -3. Add the plugin: - ```lua - -- ~/.config/nvim/lua/plugins/tia-lsp.lua - return { - "lazar/tia-lsp.nvim", - ft = "scl", - lazy = true, - dependencies = { - "neovim/nvim-lspconfig", - "nvim-treesitter/nvim-treesitter", - "saghen/blink.cmp", - }, - config = function() - require("tia_lsp").setup({ - lsp = { - on_attach = function(client, bufnr) - -- custom keymaps - end, - }, - cmp = true, -- Enable blink.cmp integration - workspace_types = true, -- Enable workspace UDT scanning - auto_prefix = true, -- Enable auto-# prefixing - debug = false, - }) - end, - } - ``` +mason needs a local copy of the registry to read the install recipe. Adding it as a lazy.nvim plugin gets it cloned automatically: -4. Install: - ``` - :MasonInstall yq " one-time prerequisite for file: registry - :MasonInstall tia-lsp " installs the LSP server - ``` +```lua +-- ~/.config/nvim/lua/plugins/tia-mason-registry.lua +return { + url = "https://gitea.l-tech.rs/lazar/tia-mason-registry.git", + name = "tia-mason-registry", +} +``` -5. Verify: open a `.scl` file and run `:LspInfo` — `tia_lsp` should be attached. +**Step 2: Register the registry with mason** + +```lua +-- ~/.config/nvim/lua/plugins/mason.lua +return { + "mason-org/mason.nvim", + opts = { + registries = { + "file:" .. vim.fn.expand("~/.local/share/nvim/lazy/tia-mason-registry"), + "github:mason-org/mason-registry", + }, + }, +} +``` + +> **Why this works:** lazy.nvim clones `tia-mason-registry` to `~/.local/share/nvim/lazy/tia-mason-registry`. The `file:` registry path points mason to that directory, where it finds `packages/tia-lsp/package.yaml`. Mason needs [`yq`](https://github.com/mikefarah/yq) to parse YAML custom registries — install it once: `:MasonInstall yq` + +**Step 3: Install the LSP server** + +``` +:MasonInstall tia-lsp +``` + +This clones `tia-lsp` from the source repo, compiles `parser.so` (tree-sitter), and places the `tia-lsp` executable on PATH. + +**Step 4: Add this plugin** + +```lua +-- ~/.config/nvim/lua/plugins/tia-lsp.lua +return { + "https://gitea.l-tech.rs/lazar/tia-lsp.nvim", + ft = "scl", + lazy = true, + dependencies = { + "neovim/nvim-lspconfig", + "nvim-treesitter/nvim-treesitter", + "saghen/blink.cmp", -- optional, for completion + }, + opts = { + lsp = { + -- on_attach = function(client, bufnr) ... end, + }, + cmp = true, -- enable blink.cmp integration + workspace_types = true, -- scan project for UDTs and DBs + auto_prefix = true, -- auto-# prefix for local variables + }, +} +``` + +**Step 5: Verify** + +Open a `.scl` file and run `:LspInfo`. `tia_lsp` should be attached. Run `:checkhealth` for detailed diagnostics. + +--- ### Manual Setup (without Mason) +Clone and build the server manually, then point the plugin at it. + +```bash +# 1. Clone the LSP server +git clone --depth 1 https://gitea.l-tech.rs/lazar/tia-lsp.git ~/tia-lsp + +# 2. Compile the tree-sitter parser (required for parsing SCL) +cc -fPIC -I ~/tia-lsp/src/tree_sitter -c ~/tia-lsp/src/parser.c -o ~/tia-lsp/parser.o +cc -shared ~/tia-lsp/parser.o -o ~/tia-lsp/parser.so +``` + +Then configure the plugin. The plugin first looks for `tia-lsp` on PATH; if not found, it falls back to running `lua `. The tree-sitter parser is loaded from `parser.so` adjacent to the server. + ```lua require("tia_lsp").setup({ - server_path = "/path/to/tia-lsp/src/main.lua", -- only used if tia-lsp is not on PATH + server_path = "~/tia-lsp/src/main.lua", -- fallback if tia-lsp not on PATH ts_parser_url = "https://gitea.l-tech.rs/lazar/tia-lsp.git", cmp = true, workspace_types = true, @@ -97,7 +140,7 @@ require("tia_lsp").setup({ | Option | Type | Default | Description | |--------|------|---------|-------------| -| `server_path` | string | `~/dev/tia-lsp/src/main.lua` | Path to LSP server (only used if `tia-lsp` is not on PATH) | +| `server_path` | string | `~/dev/tia-lsp/src/main.lua` | Path to LSP server (fallback when `tia-lsp` not on PATH; change for manual installs) | | `ts_parser_url` | string | `file://~/dev/tia-lsp` | URL passed to nvim-treesitter for the SCL parser source | | `lsp.on_attach` | function | `nil` | Custom LSP attach callback | | `lsp.formatting` | boolean | `false` | Enable format command | @@ -211,6 +254,17 @@ tia-lsp.nvim/ - **blink.cmp** — Optional, for completion - **Lua 5.1+** — LSP server runtime +## Troubleshooting + +| Symptom | Likely Cause | Fix | +|---------|-------------|-----| +| `:MasonInstall tia-lsp` fails with "unknown package" | Custom registry not registered with mason | Check the `registries` list in your mason config includes the `file:` path to the cloned registry | +| `:MasonInstall tia-lsp` fails with "yq: command not found" | Mason needs `yq` to parse the YAML registry | Run `:MasonInstall yq` to install it, then retry `:MasonInstall tia-lsp` | +| `tia_lsp` not attached after opening `.scl` | Server not on PATH or `server_path` points to wrong location | Run `:LspInfo` to see what server is configured. Check `vim.fn.exepath("tia-lsp")` returns a path | +| LSP starts but no syntax highlighting | Tree-sitter parser (`parser.so`) not found | mason install generates it automatically. For manual setups, run the `cc` commands in the Manual Setup section | +| `parser.so` load error at startup | Compiled for wrong architecture or Lua version | Recompile: clean the old `.so` and run the `cc` build commands again | +| LSP starts but no completions/hover | Server can't find its modules | Mason installs to a managed directory. If using manual setup, ensure `src/` contents are present next to `main.lua` | + ## Testing ```bash