Skip to content

Build

Jump to bottom Edit New page
Fangrui Song edited this page Aug 15, 2025 · 97 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 "LLVM-20.1.8-Linux-X64.tar.xz" assets from https://github.com/llvm/llvm-project/releases/
# ("Pre-Built Binaries" from https://releases.llvm.org/download.html)
# 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 -S. -BRelease -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/path/to/clang+llvm-xxx
cmake --build Release

As of 2020-06-23 no pre-built binaries exist for Ubuntu 20.04. sudo apt-get install clang libclang-10-dev and all the other dependencies listed here excluding rapidjson-dev (it is vendored in this repo), then run

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

Ignore fatal: No names found, cannot describe anything message Proceed with cmake --build Release and, if successful, cd Release && sudo make install

Note You will need sudo apt-get install libclang-10-dev as well for Ubuntu 20.04 build.

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 lib/cmake/clang/ClangConfig.cmake, lib/cmake/llvm/LLVMConfig.cmake, 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 -S. -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 -S. -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

Alpine Linux

apk add alpine-sdk cmake make clang clang-static clang-dev llvm-dev llvm-static \
	&& git clone --depth=1 --recursive https://github.com/MaskRay/ccls \
	&& cd ccls \
	&& cmake -S. -BRelease -DCMAKE_BUILD_TYPE=Release \
	&& cmake --build Release --target install

Arch Linux

Arch User Repository: aur/ccls-git.

To build with extra/clang: -DCLANG_LINK_CLANG_DYLIB=on -DLLVM_LINK_LLVM_DYLIB=on

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 from the Community repo using pacman.

sudo pacman -S ccls

Debian

# bullseye/11 and later
sudo apt install ccls
# build from source
sudo apt install clang cmake libclang-dev llvm-dev rapidjson-dev
cmake -S. -BRelease
cmake --build Release

openSUSE Tumbleweed

Available in openSUSE Tumbleweed

sudo zypper install ccls

Gentoo

Available in Gentoo

sudo emerge dev-util/ccls

To build with sys-devel/clang: -DCLANG_LINK_CLANG_DYLIB=1

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 -S. -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

Homebrew clang is a bit different from /usr/bin/clang. Invoke clang++ -xc++ -fsyntax-only -v /dev/null to get a list of C/C++ search paths. Add them as -isystem into the shell script wrapper. For example:

#!/bin/sh
exec /opt/homebrew/bin/ccls --init='{"clang":{"extraArgs":[
  "-isystem/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1",
  "-isystem/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/12.0.5/include",
  "-isystem/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include",
  "-isystem/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include",
  "-isystem/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks"
]}}' "$@"

To build from source:

brew info llvm
cmake -S. -BRelease -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="$(brew --prefix llvm)/lib/cmake"
cmake --build Release

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 -S. -BRelease -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/home/$USER/.guix-profile/bin/clang
cmake --build Release

Windows

Note: run git submodule update --init before building to avoid using system rapidjson.

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

Note: You may need to execute these commands in the "Developer Command Prompt for VS"
git clone https://github.com/llvm/llvm-project.git
cd llvm-project

cmake -Sllvm -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 -S. -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang-cl -DCMAKE_C_COMPILER=clang-c -DCMAKE_PREFIX_PATH="D:/llvm-project/Release"
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 mingw-w64-x86_64-rapidjson mingw-w64-x86_64-clang-analyzer mingw-w64-x86_64-mlir
#Below packages were required for me but i am stuck on later
pacman -S cmake ninja clang
# Download ccls
cd ccls
cmake -S. -BRelease -G Ninja -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0'
ninja -C Release

Try running ccls.exe once the above command finishes.

If you encounter Entry Point Not Found errors, it's most likely due to missing clang/stdc++ lib files.

Get a copy of libclang.dll and libstdc++-6.dll from your mingw64/bin/ and place them in your ccls.exe directory.

cp /mingw64/bin/libclang.dll /mingw64/bin/libstdc++-6.dll ~/ccls/Release/

Build Clang+LLVM from the git monorepo

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

cmake -Sllvm -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD=X86 -DLLVM_ENABLE_PROJECTS=clang
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 -S. -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=lld -DCMAKE_PREFIX_PATH="$LLVM/Release"
ninja -C Release

-DCMAKE_PREFIX_PATH= is a ;-separated list. The cmake build system is expected to find these files:

# generated clang+llvm header files
include/llvm/Config/config.h
tools/clang/include/clang/Config/config.h
# libclangIndex.so
lib/libclangIndex.so or libclangIndex.a
# -resource-dir
lib/clang/7.0.0
# clang+llvm libraries
lib/libclangDriver.so
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 -S. -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD=X86 -DLLVM_ENABLE_PROJECTS=clang
ninja -C Release clangFormat clangFrontendTool clangIndex clangTooling clang
# built Release/bin/clang
Add a custom footer

Home

Clone this wiki locally