Skip to content
zhsj edited this page Aug 20, 2019 · 65 revisions

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
# You might see "fatal: No names found, cannot describe anything". Ignore it.
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.

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

With clang < 8, to make header completion work, use a shell script wrapper:

#!/bin/sh
exec /path/to/ccls/Release/ccls -init='{"clang":{"extraArgs":["-isystem", "/Library/Developer/CommandLineTools/usr/include/c++/v1"]}}' "$@"

See https://github.com/MaskRay/ccls/issues/191#issuecomment-453809905 for details.

FreeBSD

  • devel/ccls
  • With devel/llvm80 add CMake flags -DCMAKE_PREFIX_PATH=/usr/local/llvm80
  • 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.

Build clang+llvm by yourself

git clone https://git.llvm.org/git/llvm.git
git clone https://git.llvm.org/git/clang.git llvm/tools/clang

cd llvm
cmake -H. -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=cl -DCMAKE_CXX_COMPILER=cl -DLLVM_TARGETS_TO_BUILD=X86
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.

Compiling Clang+LLVM from source

MaskRay's config (building trunk LLVM at ~/llvm/Release/):

git clone https://git.llvm.org/git/llvm.git
git clone https://git.llvm.org/git/clang.git llvm/tools/clang
cd llvm
cmake -H. -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON -DLLVM_ENABLE_LLD=ON -DLLVM_TARGETS_TO_BUILD=X86
ninja -C Release clang clangFormat clangFrontendTool clangIndex clangTooling cxx
  • Remove LLVM_ENABLE_LLD if you don't have lld (a much faster linker than bfd/gold) installed
  • Remove BUILD_SHARED_LIBS if you want to build static libraries (libclangIndex.a) instead

Then build ccls with -DCMAKE_PREFIX_PATH:

cd ~/ccls
cmake -H. -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=lld -DCMAKE_PREFIX_PATH="$HOME/llvm/Release;$HOME/llvm/Release/tools/clang;$HOME/llvm;$HOME/llvm/tools/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
...
You can’t perform that action at this time.