Clangd

README.md

@@ -58,6 +58,35 @@ Each supplied entry replaces that file's entire configuration. Omitted entries u
 
 The authored `cmake/` directory belongs in Git. `CMakeFiles/`, compiler caches, and generated sources belong in build directories. Modulus rejects project/source-root output directories before clearing configure or LSP caches. Conan may still use its own isolated build folders. Existing build caches are retained; they are not source files.
 
+### Container Clangd
+
+All managed repos use clangd 19 in their build image. `configure` and `lsp` rebuild images whose Dockerfile fingerprint has changed and prepare container headers on the host. `lsp` also refreshes extra databases, such as Pico firmware. Run these commands on the host before starting your editor. Direct/container-only builds do not prepare a host header cache.
+
+Neovim 0.11+ with `exrc` enabled loads the generated, ignored `.nvim.lua` after you review and trust it. The shared Lua helper finishes LazyVim's LSP setup before changing clangd's command and project routing; completion capabilities, keybindings, and attach handlers are preserved. Non-Modulus projects keep their existing server. Content-stable generation avoids repeated trust prompts. An existing hand-authored `.nvim.lua` is never overwritten; it can call `dofile(root .. "/build/build_tools/nvim/modulus.lua").setup(root)` (use `/tools/nvim/` in Modulus itself). Set `tooling.editor.nvim.enabled` to `false` to opt out.
+
+Other editors can launch `python3 modulus.py clangd` in a consumer repo, or `python3 tools/clangd.py` in Modulus. This is a stdio-only transport: no TTY, downloads, builds, credential environment forwarding, Docker socket, or host-server fallback. Startup fails on stderr if the image, database, or header cache needs preparation. Workspace paths stay identical in the container; sources are read-only and `build/` is writable. The container exits on EOF/shutdown and is removed on launcher termination.
+
+Server settings are separate from `.clangd`'s parsing/diagnostic settings:
+
+```json
+{
+  "tooling": {
+    "lsp": {
+      "clangd": {
+        "executable": "/usr/bin/clangd-19",
+        "arguments": ["--background-index", "--completion-style=detailed", "--header-insertion=never"],
+        "query_drivers": ["/usr/bin/gcc-12", "/usr/bin/g++-12", "/usr/bin/aarch64-linux-gnu-gcc", "/usr/bin/aarch64-linux-gnu-g++"],
+        "header_roots": []
+      }
+    }
+  }
+}
+```
+
+Omitted settings use these defaults; supplied lists replace defaults. Compiler paths must be explicit, trusted absolute paths, not wildcards. Add embedded compiler paths and SDK header roots in product config. `--query-driver` and `--path-mappings` are managed by the launcher, not the argument list. The default image uses Debian's clangd layout; custom images must provide `/usr/lib/llvm-<major>/lib/clang/<major>/include` for built-in headers.
+
+Header-only snapshots are shared by immutable image ID and header settings under `$XDG_CACHE_HOME/modulus/clangd` (default `~/.cache/modulus/clangd`). Preparation is locked and atomic. Symlinks are dereferenced in the container, and extracted files are read-only. clangd maps definition locations to these local files; Neovim additionally opens them unmodifiable. Old image caches can be removed when no editor uses them; run `lsp` to recreate a removed cache. Toolchains themselves are not copied to the host.
+
 ## Package
 
 Create Conan packages with: