Build

Some distributions package a pre-built version of ccls. See the system-specific sections below. If you build ccls from source, you will need:

• CMake 3.8 or higher.
• A C++ compiler with C++17 support:
  • Clang 5 or higher.
  • GNU GCC 7.2 or higher (optional,string_view require libstdc++7 or higher)
  • MSVC 2017 or higher (included with VS2017 Build Tools)
• On POSIX systems, either GNU Make or Ninja (optional on other systems)
• Clang+LLVM headers and libraries, version >= 7 (0.20181225.8 is the last release that supports clang 6)

The simplest/quickest build with all defaults (only for POSIX systems) is:

git clone --depth=1 --recursive https://github.com/MaskRay/ccls
cd ccls

# Download "Pre-Built Binaries" from https://releases.llvm.org/download.html
# and unpack to /path/to/clang+llvm-xxx.
# Do not unpack to a temporary directory, as the clang resource directory is hard-coded
# into ccls at compile time!
# See https://github.com/MaskRay/ccls/wiki/FAQ#verify-the-clang-resource-directory-is-correct
cmake -H. -BRelease -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/path/to/clang+llvm-xxx
cmake --build Release

Ubuntu 18.04 prebuilt binaries are actually suitable for many non-Ubuntu distributions. You may replace the last two cmake commands with:

wget -c http://releases.llvm.org/8.0.0/clang+llvm-8.0.0-x86_64-linux-gnu-ubuntu-18.04.tar.xz
tar xf clang+llvm-8.0.0-x86_64-linux-gnu-ubuntu-18.04.tar.xz
cmake -H. -BRelease -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$PWD/clang+llvm-8.0.0-x86_64-linux-gnu-ubuntu-18.04
cmake --build Release

The resulting executable will be Release/ccls. If you forgot to pass --recursive when cloning the repo, git submodule update --init to clone the rapidjson repository.

If you compile ccls with GCC 8.2.1, append -DCMAKE_CXX_FLAGS=-fno-gnu-unique. See https://github.com/MaskRay/ccls/issues/363#issuecomment-482625854 for details.

See below for other CMake options available for customizing the build, hints for your system, as well as methods of obtaining and locating Clang+LLVM.

CMake Options

• -G ('Unix Makefiles'|Ninja|Xcode|'Visual Studio 2017 x64')

  Choose a specific CMake generator (build tool). Use cmake --help to see your choices (not all options are available on all systems). If not specified CMake will choose an appropriate option for your system.

• -DCMAKE_BUILD_TYPE=(Debug|MinSizeRel|Release|RelWithDebInfo)

  Default: Release

  Set the build type. The most important ones are Debug and Release.

• -DCMAKE_CXX_COMPILER=<compiler>

  Build ccls with the C++ compiler <compiler>. If not specified CMake will search for an appropriate C++ compiler.

• -DCMAKE_CXX_FLAGS=<flags>

  Use extra compiler flags <flags> when compiling ccls. See the system-specific sections below for some suggestions.

• -DCMAKE_INSTALL_PREFIX=<dir>

  Default: /usr/local

  Set the install location. See Install for more details.

• -DCMAKE_PREFIX_PATH=<path>

  Specify paths where CMake can locate Clang/LLVM headers and libraries. CMake searches the paths in CMAKE_PREFIX_PATH for include and lib.

• -DUSE_SYSTEM_RAPIDJSON=(ON|OFF)

  Default: ON

  Use system rapidjson (usually available at /usr/include/rapidjson). If OFF or not found, third_party/rapidjson will be used instead.

Choosing Clang+LLVM

System Clang+LLVM

If your system Clang+LLVM is sufficiently new, consider using them. If they are installed into the standard locations for our system, CMAKE_PREFIX_PATH is not required.

A simple cmake -GNinja -H. -BRelease (remove -GNinja if you don't use Ninja) works for many distributions. The required system packages are:

• Arch Linux: clang llvm
• Fedora Linux: clang clang-devel llvm-devel
• Gentoo Linux: clang
• Void Linux

Prebuilt Clang+LLVM binaries

Pick the one on https://releases.llvm.org/download.html that suits your system. Note, the Ubuntu 16.04 prebuit binaries are actually suitable for many non-Ubuntu distributions.

After unpacking, cmake -GNinja -H. -BRelease -DCMAKE_PREFIX_PATH=/path/to/clang+llvm-7.0.1-x86_64-linux-gnu-ubuntu-16.04

The Windows prebuilt binaries lack C++ header files, thus they cannot be used.

System specific notes

On GNU/Linux distributions with older versions of glibc (older than 2013-04-25), such as Red Hat EL 6.x, append -DCMAKE_CXX_FLAGS=-D__STDC_FORMAT_MACROS

Arch Linux

Arch User Repository: aur/ccls-git.

extra/clang and extra/llvm provide /usr/lib/{libclangAST.so,libLLVM*.a,libLLVM.so}. libclangAST.so needs libLLVM.so and there would be a conflict if libLLVM*.a (instead of libLLVM.so) are linked. See https://bugs.archlinux.org/task/60512

Also you can install ccls-git from the archlinuxcn repo using pacman.

sudo pacman -S ccls-git

Debian

# bullseye/11 and later
sudo apt install ccls

# build from source
sudo apt install clang cmake libclang-dev llvm-dev rapidjson-dev
cmake -H. -BRelease
cmake --build Release

Fedora

Available for Fedora 29 and later.

sudo dnf install ccls

openSUSE Tumbleweed

Available in openSUSE Tumbleweed

sudo zypper install ccls

Ubuntu

To build from source you'll need sudo apt install zlib1g-dev libncurses-dev. To use system rapidjson, install rapidjson-dev.

On Ubuntu 16.04 install g++-7 via these directions

To build with system Clang+LLVM: sudo apt install clang libclang-dev

cmake -H. -BRelease -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH=/usr/lib/llvm-7 \
    -DLLVM_INCLUDE_DIR=/usr/lib/llvm-7/include \
    -DLLVM_BUILD_INCLUDE_DIR=/usr/include/llvm-7/

Notice that LLVM_INCLUDE_DIR points to /usr/lib, and LLVM_BUILD_INCLUDE points to /usr/include.

Build as normal. You'll have a ccls library that will be compiled against the sytem-installed LLVM, and use the system clang resource directory as well.

If you see the error:

error while loading shared libraries: libtinfo.so.5: cannot open shared object file: No such file or directory

Then installing libncurses5 with sudo apt install libncurses5 can fix the problem.

Red Hat / CentOS

Older versions (6.x) use an older GNU libc which requires -DCMAKE_CXX_FLAGS=-D__STDC_FORMAT_MACROS

MacOS

To install ccls with Homebrew:

brew update
brew install ccls

To build from source you need MacOS 10.12 (Sierra) or higher to get a version of Xcode with a sufficiently-new Clang.

To build using MacPorts Clang add CMake flags

-DCMAKE_CXX_COMPILER=clang++-mp-6.0
-DCMAKE_PREFIX_PATH=/opt/local/libexec/llvm-6.0

See https://github.com/MaskRay/ccls/issues/512 , use a shell script wrapper:

#!/bin/sh
exec /path/to/ccls/Release/ccls -init='{"clang":{"extraArgs":["-isystem", "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include"]}}' "$@"

With clang < 8, "-isystem", "/Library/Developer/CommandLineTools/usr/include/c++/v1" is also needed (https://github.com/MaskRay/ccls/issues/191#issuecomment-453809905)

With most recent MacOSs(e.g. Catalina 10.15.2), one more clang.extraArgs is needed to make ccls work properly (https://github.com/MaskRay/ccls/issues/512#issuecomment-545575369)

FreeBSD

• devel/ccls
• With devel/llvm90 add CMake flags -DCMAKE_PREFIX_PATH=/usr/local/llvm90
• Use the releases.llvm.org prebuilt archive.

GuixSD (0.16)

guix package -i cmake clang gcc-toolchain
cmake -H. -BRelease -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/home/$USER/.guix-profile/bin/clang
cmake --build Release

Windows

The Windows archive on releases.llvm.org does not contain library headers. Since ccls uses Clang C++ APIs, it is not possible to build ccls with these releases. You must either:

1. Build clang+llvm by yourself
2. Get prebuilt LLVM+Clang from other sources, e.g. MSYS2, Chocolatey.

Build clang+llvm by yourself

git clone https://github.com/llvm/llvm-project.git
cd llvm-project

cmake -Hllvm -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=cl -DCMAKE_CXX_COMPILER=cl -DLLVM_TARGETS_TO_BUILD=X86 -DLLVM_ENABLE_PROJECTS=clang
ninja -C Release clangFormat clangFrontendTool clangIndex clangTooling clang

# Download ccls
cd ccls
cmake -H. -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang-cl -DCMAKE_PREFIX_PATH="D:/llvm/Release;D:/llvm/Release/tools/clang;D:/llvm;D:/llvm/tools/clang"
ninja -C Release

MSYS2

For 2, one possible way is use MSYS2, in MSYS2 MinGW 64-bit shell:

pacman -S mingw-w64-x86_64-clang mingw-w64-x86_64-clang-tools-extra mingw64/mingw-w64-x86_64-polly mingw-w64-x86_64-cmake mingw-w64-x86_64-jq mingw-w64-x86_64-ninja mingw-w64-x86_64-ncurses
cmake -H. -BRelease -G Ninja -DCMAKE_CXX_FLAGS=-D__STDC_FORMAT_MACROS
ninja -C Release

-D__STDC_FORMAT_MACROS is because otherwise mingw-w64-headers/crt/inttypes.h does not define PRIu64.

Build Clang+LLVM from the git monorepo

git clone https://github.com/llvm/llvm-project.git
cd llvm-project

cmake -Hllvm -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD=X86
ninja -C Release clangFormat clangFrontendTool clangIndex clangTooling clang
# built Release/bin/clang

• LLVM_TARGETS_TO_BUILD defaults to ALL. We just use the frontend, don't generate code, so X86 should be sufficient. clang -target powerpc64le-linux -fsyntax-only still works.
• Add -DLLVM_ENABLE_LLD=on if you have lld (a much faster linker than bfd/gold) installed
• Add -DBUILD_SHARED_LIBS=on if you want to build shared libraries (libclangIndex.so)

Then build ccls with -DCMAKE_PREFIX_PATH:

cd ~/ccls
LLVM=$HOME/llvm-project
cmake -H. -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=lld -DCMAKE_PREFIX_PATH="$LLVM/Release;$LLVM/llvm;$LLVM/clang"
ninja -C Release

-DCMAKE_PREFIX_PATH= is a ;-separated list where you can find:

• llvm: llvm source
• llvm/tools/clang: clang source
• llvm/Release: build directory. include/ contains generated llvm header files, e.g. include/llvm/Config/config.h
• llvm/Release/tools/clang: build directory. include/ contains generated clang header files, e.g. include/clang/Config/config.h

The cmake build system is expected to find these files:

# generated clang+llvm header files
~/llvm/Release/include/llvm/Config/config.h
~/llvm/Release/tools/clang/include/clang/Config/config.h
# libclangIndex.so
~/llvm/Release/lib/libclangIndex.so or libclangIndex.a
# -resource-dir
~/llvm/Release/lib/clang/7.0.0
# clang+llvm libraries
~/llvm/Release/lib/libclangDriver.so
~/llvm/Release/lib/libLLVMSupport.so or libLLVMSupport.a
...

Build Clang+LLVM from releases.llvm.org or prereleases.llvm.org

Similar to the instructions to build Clang+LLVM from the git monorepo:

# Download "LLVM source code" and rename the extracted directory to llvm
# Download "Clang source code" and rename the extracted directory to llvm/tools/clang
cd llvm
cmake -H. -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD=X86
ninja -C Release clangFormat clangFrontendTool clangIndex clangTooling clang
# built Release/bin/clang