dap-example/devstation/README.md

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	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

# 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/ 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.

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.