Debugging

First of all, use a --variant=debug build https://github.com/jacobdufault/cquery/wiki/Build . It is compiled with -O0 -g while the default --variant=release is -O3 -g.

Dump LSP requests/responses

Pass the command line option --log-stdin-stdout-to-stderr to the cquery executable (bin/cquery --language-server --log-file=/tmp/cq.log --log-stdin-stdout-to-stderr). You can find stderr output in:

• LanguageClient-neovim: /tmp/LanguageServer.log (default)
• Emacs lsp-mode: *lsp-cquery stderr* buffer
• VSCode: TODO

Another way in emacs, M-:: (setq lsp-print-io t).

You can use sysdig on Linux:

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

Stopping at the start to debug early issues

If you use LanguageClient-neovim and your cacheDirectory is /tmp/cquery/:

# vimrc
nn ,al :LanguageClientStart<cr>

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

Poor man's breakpoint

Insert an infinite loop volatile static int z=0;while(!z); somewhere and cquery will stop there. Attach to the cquery process with gdb -p $(pgrep -fn cquery). 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. CQUERY_TRACEME=1 causes the cquery process to stop at the start of main(). You may attach to the process with:

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

libclang or indexer callback issues

Add --debug option to the cquery command line, which disabled libclang crash recovery. In case of libclang or indexer callback issues, you will not see libclang: crash detected in the log file but get a process crash. And if you attach a debugger before it crashes, you can get the stack trace.

Build/Test cycle

$ ./waf ; ./build/${variant}/bin/cquery --test-unit --test-index

Extension Development / In-Editor Testing

VSCode has Reload Window command which makes it pretty quick to restart cquery.

The preference "cquery.launch.autoRestart": false will prevent cquery binary from automatically restarting if it crashes.

Common issues

Crashing in Reflect when parsing JSON

Issues: #247 and #185.

Problem: the LSP client is not strictly conforming to the spec e.g. passing null instead of do-no-exist for optional objects, making cquery crash.

Solution: report this to the corresponding LSP client.