# Devstation container

An Alpine container with Neovim (LazyVim) pre-configured for remote C++ DAP
debugging. It connects to the codelldb DAP server running on the **remote**
container.

## What's inside

| Component | Purpose |
|---|---|
| Neovim (built from source) | Editor — Alpine uses musl, so prebuilt glibc binaries don't run |
| [LazyVim](https://lazyvim.org) | Neovim distribution (pre-installed) |
| Catppuccin (Mocha) | Colour scheme |
| nvim-dap + dap-ui + virtual-text | DAP client, UI panels, inline variable text |
| clangd (via `clang-extra-tools`) | LSP for C/C++ code navigation |
| ripgrep, fd, fzf | Fuzzy finder and search backends |

## Quick start

```bash
# From the repository root:
docker compose build
docker compose up -d remote
docker compose run --rm devstation
```

Neovim launches automatically in `/project`.

## Debugging

1. Open a source file: `:e src/calculator.cpp`
2. Set a breakpoint: `<leader>db`
3. Start debugging: `<leader>dc`
4. Select **"Remote launch (codelldb remote:13000)"**
5. The program runs in the remote container and stops at your breakpoint.
6. dap-ui opens automatically with scopes, watch, call stack, and breakpoints.

## Key bindings

All debug keybindings are under the `<leader>d` prefix:

| Key | Action |
|---|---|
| `<leader>db` | Toggle breakpoint |
| `<leader>dB` | Conditional breakpoint |
| `<leader>dc` | Continue / start debug session |
| `<leader>dC` | Run to cursor |
| `<leader>di` | Step into |
| `<leader>dO` | Step over |
| `<leader>do` | Step out |
| `<leader>dp` | Pause |
| `<leader>dt` | Terminate session |
| `<leader>dr` | Toggle REPL |
| `<leader>du` | Toggle DAP UI |
| `<leader>de` | Evaluate expression (normal or visual mode) |
| `<leader>dw` | Hover (inspect variable under cursor) |
| `<leader>dj` / `<leader>dk` | Navigate call stack (down / up) |
| `<leader>dl` | Run last session |
| `<leader>dg` | Go to line (skip execution) |
| `<leader>ds` | Session info |

## Plugin configuration

LazyVim plugin specs live as regular files under
[`devstation/nvim-config/lua/plugins/`](nvim-config/lua/plugins/) and are
COPY'd into the image at build time:

| File | Contents |
|---|---|
| `theme.lua` | Catppuccin Mocha theme |
| `lsp.lua` | Disables Mason auto-install (glibc binaries crash on musl); uses system clangd |
| `dap.lua` | nvim-dap adapter (connects to `remote:13000`) + debug config + all `<leader>d` keybindings |

The treesitter pre-compilation script is at
[`devstation/scripts/precompile-treesitter.lua`](scripts/precompile-treesitter.lua).

To customise the DAP adapter (e.g. change host or port), edit the
`dap.adapters.codelldb` table in `dap.lua` and rebuild.

## Notes

- Named volumes (`nvim-data`, `nvim-state`, `nvim-cache`) persist plugins and
  state across container restarts. Remove them with
  `docker compose down -v` to start fresh.
- Mason's prebuilt binaries are glibc-linked and crash on Alpine/musl. LSP
  servers are provided by system packages instead (`clang-extra-tools`).
- Treesitter parsers are pre-compiled during the image build.