Vim, Emacs, and Other Editors

SerenityOS can be developed using various terminal-based editors with clangd integration for code comprehension.

Vim
Neovim
Emacs
Helix

Vim Configuration

Vim can be configured with the YouCompleteMe plugin to provide code completion.

Setup

Install YouCompleteMe

Follow the installation instructions for your platform.

Whitelist Configuration File

Add the following to your .vimrc file:

let g:ycm_extra_conf_globlist = ['~/serenity/.ycm_extra_conf.py']

This whitelists the configuration file included in the SerenityOS repository.

Features

With YouCompleteMe configured, you’ll have:

Code completion
Jump to definition
Error/warning diagnostics
Semantic highlighting

Neovim Configuration

Neovim can be configured with COC-clangd for code completion and git-blame for inline git information.

Make sure you’ve run Meta/serenity.sh run at least once before configuring Neovim.

Install vim-plug

See https://github.com/junegunn/vim-plug for installation instructions.

Install coc.nvim

Add Plugin to init.vim

The config file is at ~/.config/nvim/init.vim or $XDG_CONFIG_HOME/nvim/init.vim.Add the plugin:

Plug 'neoclide/coc.nvim', { 'branch': 'release' }

Install Plugin

Run inside nvim:

:PlugInstall

Install coc-clangd

Install via CocInstall

:CocInstall coc-clangd

Install clangd (if needed)

If you don’t have clangd installed:

:CocCommand clangd.install

This installs a separate clangd version just for neovim.

This guide is tested with clangd version 14.0.6 and 15.0.6.

Configure coc-clangd

Edit ~/.config/nvim/coc-settings.json or run :CocConfig:

{
    "clangd.fallbackFlags": ["-std=c++26"],
    "clangd.arguments": ["--query-driver=${workspaceFolder}/Toolchain/Local/**/*"],
    "semanticTokens.enable": true,
    "inlayHint.subSeparator": "︴",
    "inlayHints.enableParameter": true,
    "clangd.inlayHints.sep": "⇝"
}

If you had another C++ language server configured, remove it first to avoid conflicts
If you configured clangd as a languageServer in coc-settings.json, remove it to avoid running clangd twice
clangd.inlayHints.sep breaks on clangd 15.0.6

Formatting

Install the formatter plugin:

Plug 'mhartington/formatter.nvim'

Configure in Lua to use clang-format for C++ files:

require("formatter").setup{
    filetype = {
        cpp = {
            require("formatter.filetypes.cpp").clangformat
        }
    }
}

Git Blame (Optional)

Add Plugin

Plug 'f-person/git-blame.nvim'

Install Plugin

:PlugInstall

Complete init.vim Configuration

View complete init.vim excerpt

"IMPORTANT: the leader key for <leader> keycombos
let mapleader = "\\"

"BEGIN: git blame (optional)
hi GitBlame guifg=#7b7b7b
let g:gitblame_date_format = '%d.%m.%y %H:%M'
let g:gitblame_highlight_group = 'GitBlame'
let g:gitblame_message_when_not_committed = 'You: Uncommitted changes'
let g:gitblame_message_template = '   <author> (<committer>), <date> <sha> • <summary>'
"END: git blame

"BEGIN: coc
"inline hints (depending on clangd version one or another gets used)
hi CocHintVirtualText guifg=#84afe0
hi CocInlayHint guifg=#84afe0 guibg=#393939
hi CocInlayHintParameter guifg=#84afe0 guibg=#393939
hi CocInlayHintType guifg=#89ddff guibg=#393939

"semantic highlighting
hi CocSemMethod guifg=#bfaa87 gui=bold
hi CocSemFunction guifg=#bfaaf7 gui=bold
hi CocSemParameter guifg=#a9bfd1 gui=underline
hi CocSemVariable guifg=#8edbdb
hi CocSemProperty guifg=#23ce6d
hi link CocSemEnumMember Constant
hi link CocSemEnum CocSemClass
hi Constant guifg=#f78c6c
hi CocSemClass guifg=#89ddff
hi Statement guifg=#c792ea
hi Type guifg=#db954a


"remap keys for applying refactor code actions (on warnings) (\re)
nmap <silent> <leader>re <Plug>(coc-codeaction-refactor)
xmap <silent> <leader>r  <Plug>(coc-codeaction-refactor-selected)
nmap <silent> <leader>r  <Plug>(coc-codeaction-refactor-selected)

"outline for file (\o)
nmap <silent><nowait> <leader>o :<C-u>CocList outline<cr>

"goto definition etc.
nmap <silent> gd <Plug>(coc-definition)
nmap <silent> gt <Plug>(coc-type-definition)
nmap <silent> gi <Plug>(coc-implementation)
nmap <silent> gr <Plug>(coc-references)

"coc rename (\rn)
nmap <leader>rn <Plug>(coc-rename)

"prev or next error
nmap <silent> [g <Plug>(coc-diagnostic-prev)
nmap <silent> ]g <Plug>(coc-diagnostic-next)

"confirm coc-suggestion with enter
imap <silent><expr> <CR> coc#pum#visible() ? coc#pum#confirm() : "\<CR>"

"ctrl+space for completion
imap <silent><expr> <c-space> coc#refresh()

"show documentation with ctrl+k
nmap <silent><c-k> :call ShowDocumentation()<CR>

"show documentation if it's available
function! ShowDocumentation()
  if CocAction('hasProvider', 'hover')
    call CocActionAsync('doHover')
  else
    call feedkeys('K', 'in')
  endif
endfunction

"coc-clangd switch between header and source
nmap <silent>gs :CocCommand clangd.switchSourceHeader vsplit<CR>
"END: coc

Configure .clangd

Configure .clangd as explained in ClangdConfiguration.

Emacs Configuration

Emacs can be configured with lsp-mode and clangd for excellent SerenityOS development support.

clangd Setup

The official clangd extension provides C++ comprehension. See ClangdConfiguration for configuration details.There are several ways to specify which clangd to use:

Default: lsp-mode will find and use your system clangd (easiest, but may be outdated)
Manual path: Specify any clangd binary with lsp-clangd-binary-path
Managed installation: Use lsp-install-server to let lsp-mode manage the installation

lsp-mode Configuration

(use-package lsp-mode
  :hook ((c++-mode) . lsp-deferred)
  :commands lsp
  :config
  ;; clangd arguments, refer to ClangdConfiguration.md for what other arguments may be needed.
  (setq lsp-clients-clangd-args '("-j=4" "-background-index" "--log=error" "--clang-tidy" "--enable-config"))
  ;; Optionally, set the location of clangd -- See above for options.
  (setq lsp-clangd-binary-path "/usr/bin/clangd"))

clang-format Integration

There are multiple packages for auto-formatting with clang-format:

Alternative: Use lsp-mode for Formatting

You can format without additional packages by using lsp-mode. Create .dir-locals.el in the project root:

((c++-mode
  (eval add-hook 'before-save-hook #'lsp-format-buffer nil t)))

This automatically formats C++ files on save.

Helix Configuration

Helix comes with support for clangd and clang-format out of the box!

Setup

See ClangdConfiguration for how to configure clangd.To configure clangd command-line arguments, create .helix/languages.toml in the project root:

[language-server.serenity]
command = "clangd"
# clangd arguments, refer to ClangdConfiguration.md for what may be needed.
args = []

[[language]]
name = "cpp"
language-servers = ["serenity"]

Features

Helix provides out of the box:

Code completion via clangd
Jump to definition
Find references
Automatic formatting with clang-format
Syntax highlighting
Error diagnostics

Common clangd Configuration

All editors using clangd should configure it according to ClangdConfiguration for optimal SerenityOS development support.

Setup

Debugging & Profiling

Virtualization

Vim, Emacs, and Other Editors

Vim Configuration

Setup

Features

Neovim Configuration

Install vim-plug

Install coc.nvim

Install coc-clangd

Configure coc-clangd

Formatting

Git Blame (Optional)

Complete init.vim Configuration

Configure .clangd

Emacs Configuration

clangd Setup

lsp-mode Configuration

clang-format Integration

Alternative: Use lsp-mode for Formatting

Helix Configuration

Setup

Features

Common clangd Configuration

Build docs developers (and LLMs) love

Setup

Debugging & Profiling

Virtualization

​Vim Configuration

​Setup

​Features

​Neovim Configuration

​Install vim-plug

​Install coc.nvim

​Install coc-clangd

​Configure coc-clangd

​Formatting

​Git Blame (Optional)

​Complete init.vim Configuration

​Configure .clangd

​Emacs Configuration

​clangd Setup

​lsp-mode Configuration

​clang-format Integration

​Alternative: Use lsp-mode for Formatting

​Helix Configuration

​Setup

​Features

​Common clangd Configuration

Build docs developers (and LLMs) love

Vim Configuration

Setup

Features

Neovim Configuration

Install vim-plug

Install coc.nvim

Install coc-clangd

Configure coc-clangd

Formatting

Git Blame (Optional)

Complete init.vim Configuration

Configure .clangd

Emacs Configuration

clangd Setup

lsp-mode Configuration

clang-format Integration

Alternative: Use lsp-mode for Formatting

Helix Configuration

Setup

Features

Common clangd Configuration