Debugging

First of all, use a Debug build. It is compiled with -O0 -g while the default Release build is -O3.

Logs

Enable logging and verbose mode when starting the server.

-log-file=/tmp/ccls.log -v=1

stderr

You can find stderr output in:

• LanguageClient-neovim: /tmp/LanguageServer.log (default)
• Emacs lsp-mode: *lsp-ccls stderr* buffer. They will also go to *message* buffer if (setq lsp-print-io t)
• VSCode: TODO

Dump LSP requests/responses

On Linux:

# sysdig
sudo sysdig -As999 --unbuffered -p '%evt.type %proc.name %evt.buffer' "proc.exe contains ccls and fd.type=pipe" | egrep -v '^Content|^$'

# strace
strace -s999 -e read,write -fp $(pgrep -fn ccls)

Stopping at the start to debug early issues

To debug individual LSP requests, you can attach your debugger after ccls has done indexing. However, for many other issues, such as project file loading (project.cc) and C/C++ parsing and indexing indexer.cc, you need to set an early breakpoint to be able to trace the code.

It is simplest to use LC-neovim for debugging (even if you use Emacs or VSCode) because it can be started with simple shell command.

# vimrc
nn ,al :LanguageClientStart<cr>

rm -r /tmp/ccls && CCLS_TRACEME=1 nvim a.cc +'normal ,al'

The Neovim buffer will hang there because CCLS_TRACEME=1 causes the ccls process to SIGTSTP itself. In another shell, gdb -p $(pgrep -fn debug/ccls)

Poor man's breakpoint

Insert an infinite loop volatile static int z=0;while(!z); somewhere and ccls will stop there. Attach to the ccls process with gdb -p $(pgrep -fn ccls). Set some breakpoints, use print commands, and execute p z=1 for continuing.

When setting breakpoints, if several threads may stop on the same breakpoint (e.g. concurrent indexer threads), execute set scheduler-locking on.

Using a debugger

Cache files are deleted to avoid possible issues related to stale cache. CCLS_TRACEME=1 causes the ccls process to stop at the start of main(). You may attach to the process with:

Use CCLS_TRACEME=s to raise(SIGSTOP), if SIGTSTP does not work.

• gdb -p $(pgrep -fn ccls). Invoke signal SIGCONT if you want ccls to continue running after detaching of gdb.
• lldb -p $(pgrep -fn ccls). Invoke pro sig SIGCONT when the process resumes (with a c command) if you want ccls to continue running after detaching.

Indexer issues

export CCLS_CRASH_RECOVERY=0 disables clang crash recovery. In case of clangIndex issues, you will not see clang crashed in the log file but get a process crash. And if you attach a debugger before it crashes, you can get the stack trace.

Developing

Diagnose whether requests are handled correctly

Set breakpoints in src/messages/* files. They are inbound message handlers.