Project Setup

ccls typically indexes an entire project. In order for this to work properly, ccls needs to be able to obtain the source file list and their compilation command lines.

There are two main ways this happens:

Provide compile_commands.json at the project root
Provide a .ccls file. It is a line-based text file describing compiler flags. Recursively listed source files (headers excluded) will be indexed.

If neither exists, then when ccls starts it will not index anything: instead it will wait for LSP clients to open files and index only those files.

`compile_commands.json`

Guillaume Papin(@Sarcasm) has a thorough article about compilation databases.

Generally this file is not checked into source control, but rather is generated by the build system. This means it's best to generate it in a new project before starting the ccls server in that project.

Because this file is auto-generated it's not easy to customize. As a result it's possible to provide both compile_commands.json and .ccls in the same project and have the .ccls configuration enhance the options from compile_commands.json.

If your compile_commands.json is not kept in the project root, set the initialization option compilationDatabaseDirectory to an alternative directory containing compile_commands.json.

CMake

% cmake -H. -BDebug -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=YES
% ln -s Debug/compile_commands.json

Caveat on Windows: CMake dumps Windows shell command line directly into command, depends on how ccls was built, it may confuse this field as command line from a POSIX shell, in which Windows path separator '\' is a escape character. You can use jq to convert such entries to use arguments which does not have this issue:

jq '[.[] | {directory: .directory, file: .file, arguments: .command | split(" ") | map(select(length > 0)) | map(sub("\\\\\""; "\""; "g"))}]' < compile_commands.json

Build EAR

Bear is a tool that generates a compilation database for clang tooling. It can be used for any project based on Makefile.

bear make
# generates compile_commands.json

compiledb

scan-build

scan-build is a python package that can generate a compilation database for clang tooling (uses Bear as a backend). This too can be used for any project based on a Makefile.

intercept-build make all # generates compile_commands.json from the `make all` ruleset

Ninja

# Format: ninja -t compdb rule_names... > compile_commands.json
ninja -C out/Release -t compdb cxx cc > compile_commands.json

Waf

Load the clang_compilation_database tool in your wscript:

def configure(conf):
    conf.load('clang_compilation_database')

./waf configure build
ln -s build/compile_commands.json

buck

buck build :helloworld#compilation-database
ln -s $(buck targets --show-output :helloworld#compilation-database | cut -d ' ' -f 2)

xcodebuild

xcpretty is a 3rd party tool that can parse the output of xcodebuild and generate a compile_commands.

xcodebuild | xcpretty -r json-compilation-database --output compile_commands.json

stdout of an external command

If the initialization option "compilationDatabaseCommand" is set, the command will be executed by ccls to provide the JSON compilation database. ccls will read its stdout rather than read compile_commands.json. This may be useful when ccls cannot parse the compile_commands.json correctly (e.g. MSVC cl.exe, Intel C++ Compiler options)

ccls shell script wrapper:

#!/bin/zsh
/path/to/Release/ccls --init='{"compilationDatabaseCommand":"/tmp/c/x"}' "$@"

/tmp/c/x:

#!/bin/zsh
# cat >> /tmp/initialization-options # stdin is initialization options
print '[{"arguments":["c++","-c","a.cc"],"directory":"/tmp/c","file":"a.cc"}]'

Suppose the project is at /tmp/c, /tmp/c/x /tmp/c will be executed with stdin=initializationOptions and the stdout should be a JSON compilation database.

An example to scrub Intel C++ Compiler options (or, even easier, check out clang.excludeArgs in the Initialization options):

#!/usr/bin/env python3
import json
import os
import sys
with open(os.path.join(sys.argv[1], 'compile_commands.json')) as f:
    db = json.load(f)
    for entry in db:
        args = entry['arguments']
        try:
            # Intel C++ Compiler option that is unknown to clang
            args.remove('-xHost')
        except ValueError:
            pass
    json.dump(db, sys.stdout)

`.ccls` File

.ccls is a line-based text file at the project root. Its main function is to specify compiler flags needed to properly index your code: -I -D etc. Each line consists of one argument to be added to the compiler command line. No whitespace splitting is performed on the argument, thus -I foo cannot be used (use -Ifoo or -I\nfoo for example).

Subdirectories of the project can also contain .ccls files, if needed, to specify compiler flags specific to those directories.

A line may optionally start with one or more % directives, which specialize the argument on that line.

Available directives include:

`%compile_commands.json`

By default .ccls compiler flags are applied only to files not listed in compile_commands.json. If this directive appears first in .ccls then after compile_commands.json is parsed, the rest of the .ccls arguments will be appended to the compiler flags for files found in compile_commands.json.

`%c` / `%cpp` / `%objective-c` / `%objective-cpp`

This argument should be added only when parsing C (%c), C++ (%cpp), Objective-C (%objective-c), or Objective-C++ (%objective-c++) files.

`%cu

This argument should be added only when parsing CUDA files. If you want an option to be added to both CUDA and regular C++ files, write %cpp %cu -DA.

`%h` / `%hpp`

This argument should be added only when indexing C header files (%h: *.h) or C++ header files (%hpp: *.hh *.hpp). Note, *.h files are considered as C, not C++.

You may add these lines to make every *.h parsed as C++:

%h -x
%h c++-header

Note, if your project has both C and C++ files, a.h's flags may be inferred from a C file and thus parsed as C. You may run into parsing errors like unknown type name 'class'.

Compiler driver

The compiler driver (the first line unless %compile_commands.json is used) can usually just be clang. clang++ is usually unnecessary, and incorrect if some files are C.

Note that clang a.cc and clang++ a.cc are different, but the difference is only related to linking (what default runtime libraries are passed) and is not relevant for the frontend actions ccls performs.

`.ccls` examples

Example A

clang
%c -std=c11
%cpp -std=c++2a
%h %hpp --include=Global.h
-Iinc
-DMACRO

*.h *.hh *.hpp files will be parsed with extra --include=Global.h

Example B

%compile_commands.json
%c -std=c11
%cpp -std=c++14
%c %cpp -pthread
%h %hpp --include=Global.h
-Iinc

It appends flags so clang should not be used.

Example: `-march=armv7a`

See https://github.com/MaskRay/ccls/issues/107. If the compiler driver is a GCC cross-compiler, --target= may be required. Suppose arm-linux-gnueabi-gcc -march=armv7a is used, add a --target=:

%compile_commands.json
--target=armv7a-linux-gnueabi

Otherwise clang will error: unknown target CPU 'armv7a'.

`compile_commands.json` examples

Linux kernel

wget 'https://git.archlinux.org/svntogit/packages.git/plain/trunk/config?h=packages/linux' -O .config
yes '' | make config
bear make -j bzImage modules

ccls -index ~/Dev/Linux -init='{"clang":{"excludeArgs":[
"-falign-jumps=1","-falign-loops=1","-fconserve-stack","-fmerge-constants","-fno-code-hoisting","-fno-schedule-insns","-fno-sched-pressure","-fno-var-tracking-assignments","-fsched-pressure",
"-mhard-float","-mindirect-branch-register","-mindirect-branch=thunk-inline","-mpreferred-stack-boundary=2","-mpreferred-stack-boundary=3","-mpreferred-stack-boundary=4","-mrecord-mcount","-mindirect-branch=thunk-extern","-mno-fp-ret-in-387","-mskip-rax-setup",
"--param=allow-store-data-races=0","-Wa,arch/x86/kernel/macros.s","-Wa,-"
], "extraArgs":["--gcc-toolchain=/usr"]}}'

LLVM multirepo

git clone https://git.llvm.org/git/llvm.git
cd llvm
git clone https://git.llvm.org/git/clang.git tools/clang
git clone https://git.llvm.org/git/lldb.git tools/lldb
git clone https://git.llvm.org/git/lld.git projects/lld
git clone https://git.llvm.org/git/compiler-rt.git projects/compiler-rt
git clone https://git.llvm.org/git/libcxx.git projects/libcxx
git clone https://git.llvm.org/git/libcxxabi.git projects/libcxxabi

# cmake -H. -BDebug -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=On <other options>
ln -s Debug/compile_commands.json

# Let clients know llvm/ is the project root, llvm/tools/clang etc are not.
# emacs-ccls knows this file but other clients may require manual configuration.
touch .ccls-root

LLVM monorepo

git clone [email protected]:llvm/llvm-project.git

# cmake -Hllvm -BDebug -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=On -DLLVM_ENABLE_PROJECTS='llvm;clang' <other options>
ln -s llvm/compile_commands.json

musl

mkdir Debug; cd Debug
../configure --enable-optimize=no --enable-debug --prefix=~/.local/stow/musl
bear make -j
cd ..; ln -s Debug/compile_commands.json

Home

Build
Install
Editor Configuration
- Atom
- Emacs
  - lsp-mode (+ emacs-ccls)
  - eglot
- Kakoune
- Sublime
- Vim/Neovim
- Visual Studio Code
- Monaco Editor
Project Setup
- Example Projects
Customization
Debugging
FAQ
LSP Extensions
LSP

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Project Setup

`compile_commands.json`

CMake

Build EAR

compiledb

scan-build

Ninja

Waf

buck

xcodebuild

stdout of an external command

`.ccls` File

`%compile_commands.json`

`%c` / `%cpp` / `%objective-c` / `%objective-cpp`

`%cu

`%h` / `%hpp`

Compiler driver

`.ccls` examples

Example A

Example B

Example: `-march=armv7a`

`compile_commands.json` examples

Linux kernel

LLVM multirepo

LLVM monorepo

musl

Clone this wiki locally

Project Setup

compile_commands.json

stdout of an external command

.ccls File

%compile_commands.json

%c / %cpp / %objective-c / %objective-cpp

`%cu

%h / %hpp

Compiler driver

.ccls examples

Example A

Example B

Example: -march=armv7a

compile_commands.json examples

Linux kernel

LLVM multirepo

LLVM monorepo

musl

Clone this wiki locally

`compile_commands.json`

`.ccls` File

`%compile_commands.json`

`%c` / `%cpp` / `%objective-c` / `%objective-cpp`

`%h` / `%hpp`

`.ccls` examples

Example: `-march=armv7a`

`compile_commands.json` examples