Getting started

Outline

1. Build ccls / prebuilt binary (below)
2. Setup your editor
3. Project setup: generate compile_commands.json or .ccls

Build the ccls language server

• cmake >= 3.8 for C++17 support
• On Linux, building requires libstdc++ shipped with GCC >= 7.3 for C++17 header files, even if you use clang++.
• Mac OS X >= 10.12, older versions do not provide shared_mutex in libc++

Below are quick commands for the impatient. Detailed instructions can be found at Build.

git clone https://github.com/MaskRay/ccls --depth=1
cd ccls
git submodule update --init
cmake -H. -BRelease # This downloads prebuilt clang+llvm from releases.llvm.org
cmake --build Release

The executable is at Release/ccls.

You may use -DSYSTEM_CLANG=on if you have clang and llvm installed somewhere (can be a releases.llvm.org prebuilt archive, not necessarily installed via the system package manager). But caution is that you need to identify whether the clang library is compiled with -DLLVM_ENABLE_RTTI=on

• Arch Linux
  • aur/ccls-git. There was a SIGSEGV issue caused by LLVM_ENABLE_RTTI which has been fixed.
  • cmake -H. -BRelease -DSYSTEM_CLANG=on -DUSE_SHARED_LLVM=on -DLLVM_ENABLE_RTTI=on
• FreeBSD
  • with devel/llvm60: cmake -H. -BRelease -DSYSTEM_CLANG=on -DUSE_SHARED_LLVM=on -DCMAKE_PREFIX_PATH=/usr/local/llvm60
  • use releases.llvm.org prebuilt archive and its libc++: cmake -H. -BRelease -DCLANG_USE_BUNDLED_LIBC++=on
• Gentoo Linux: cmake -H. -BRelease -DSYSTEM_CLANG=on -DCMAKE_PREFIX_PATH=/usr/lib/llvm/6 -DLLVM_ENABLE_RTTI=on
• Mac OS X
  • Homebrew: https://github.com/twlz0ne/homebrew-ccls
  • MacPorts: cmake -H. -BRelease -DSYSTEM_CLANG=on -DCMAKE_CXX_COMPILER=clang++-mp-6.0 -DCMAKE_PREFIX_PATH=/opt/local/libexec/llvm-6.0 -DLLVM_ENABLE_RTTI=on -DUSE_SHARED_LLVM=on
• Windows. It is possible to compile with msys2 or build your own toolchain. But welcome to contribute detailed instructions https://github.com/MaskRay/ccls/issues/59

Debian: apt install zlib1g-dev ncurses-dev

• Install g++-7 on Ubuntu 16.04: https://gist.github.com/jlblancoc/99521194aba975286c80f93e47966dc5
• -DUSE_SHARED_LLVM=on (optional, if you have libLLVM.so (provided by a llvm build with -DLLVM_BUILD_LLVM_DYLIB=on)) makes linked executable smaller.
• -G Ninja to build with ninja.

Setup your editor

Find your editor from the sidebar under the section "Editor configuration". If you use other editors not listed there (LSP decouples servers and clients, so every language client should work), make sure to configure cacheDirectory in Initialization options.

Project setup

If your project has subprojects (e.g. separate repos), some setup in your editor is needed for proper root detection: https://github.com/MaskRay/ccls/wiki/FAQ#project-root-detection

compile_commands.json (Best)

Remember to copy/symlink it to the project root.

.ccls

Alternatively, create a file named .ccls located in the project root. Easy to use for simple projects.

ccls recursively finds source files and indexes them. Subdirectories can include .ccls files to affect compiler options in its subtree.

If %clang is used, it expands to clang or clang++ according to the extension name. Prefix options with %c or %cpp to make it specific to C or C++.

Example .ccls:

%clang
%c -std=gnu11
%cpp -std=gnu++14
-pthread

# Includes
-I/work/ccls/third_party
-I/work/ccls/another_third_party
# -I space_is_not_allowed

Note: .ccls does not do word splitting or command substitution for you, you cannot use space-separated arguments like %cpp -std=gnu++14 -pthread

Windows

If your project is compiled with MSVC, you may change the compiler driver (%clang above) to clang-cl, and use the initialization option clang.extraArgs to pass three options: -fms-extensions -fms-compatibility -fdelayed-template-parsing.

See https://clang.llvm.org/docs/MSVCCompatibility.html

Cases

On a laptop with one (i7-6600U CPU @ 2.60GHz, hyper-threading, nproc=4), 4 indexers.

llvm+clang+extra+lld+compiler-rt (2018-06-10)

• initial indexing: 1 hour; load: 20s
• resident set size is about 1GiB (the peak RSS during indexing is below 2GiB)
• du -sh .ccls-cache => 580M

radare2 (2017-06-10)

CC=clang CXX=clang++ LDFLAGS=-fuse-ld=lld meson . debug --buildtype=debug --prefix ~/.config/radare2/debug
ln -s debug/compile_commands.json

• initial indexing: 78s; load: 3s
• 300MiB
• du -sh .ccls-cache => 107M

Note: ccls can serve LSP requests while it is doing the initial indexing of the project.