Initialization options

You need to configure your language client plugin to send initialization options to the ccls process (the language server).

Each language client has its own way to specify initialization options. ccls (server-side) supports the command line option --init to override client-side initialization options:

• zsh: --init='{"index": {"comments": 2}}'

cacheDirectory

Default: ".ccls-cache"

If your project is /a/b, cache directories will be created at /a/b/.ccls-cache/@a@b/ (files under the project root) /a/b/.ccls-cache/@@a@b/ (files outside the project root, e.g. /usr/include/stdio.h).

This can also be an absolute path. Because the project path is encoded with @, cache directories of different projects will not conflict. When ccls is started, it will try loading cache files if they are not stale (compile command line matches and timestamps of main source and its #include (direct and transitive) dependencies do not change).

If empty, cache will be stored in memory. Every time a file is re-indexed, the cache will be written to the disk. Use this if you don't want to write cache files.

cacheFormat: serialization format of cache files

Default: "binary", a compact binary serialization format.

Use

{ "cacheFormat": "json" }

if you want to inspect the cache file (IndexFile), e.g. jq . < /tmp/ccls/@tmp@c/a.cc.json

clang.extraArgs clang.excludeArgs

Additional arguments or excluded arguments for compile_commands.json entries. You may use clang.excludeArgs to exclude GCC specific options that are unknown to clang.

clang.pathMappings

If cache files were built with project root /tmp/container, and you want to reuse them with a different project root /host:

{ "clang": { "pathMappings": ["/container:/host"] }

Copy cache files:

rsync -a /tmp/ccls/@tmp@container/ /tmp/ccls/@tmp@host/ # files under project root
rsync -a /tmp/ccls/@@tmp@container/ /tmp/ccls/@@tmp@host/ # files outside of project root

Open /tmp/host/a.cc, the cache file /tmp/ccls/@tmp@host/a.cc.blob will be reused. When a.cc is saved (re-indexed), the newly generated a.cc.blob will not contain /tmp/container paths any more.

diagnostics.onOpen: 0 diagnostics.onChange: 1000 diagnostics.onSave: 0

Time to wait before computing diagnostics for textDocument/{didOpen,didChange,didSave}.

By default:

• diagnostics.onOpen: 0: diagnostics are emitted immediately when a document is opened.
• diagnostics.onChange: 1000: after receiving a textDocument/didChange, wait up to 1000ms (1s). Changes in this period of time only lead to one computation.
• diagnostics.onSave: 0: diagnostics are emitted immediately when a document is save.

Diagnostics require parsing the document. If diagnostics.onChange: 1000 makes you feel slow, consider:

{ "diagnostics": { "onChange": -1, } }

index.threads: number of indexer threads

If index.threads is 0, use std::thread::hardware_concurrency(). If you want to control peak memory usage, set it to a small integer.

index.comments: index comments

• 0, don't index comments
• 1, index Doxygen comment markers
• 2, default, use -fparse-all-comments and recognize plain // /* */ besides Doxygen comment markers

With the value larger than 0, ccls will index comments associated with functions/types/variables (macros are not handled).

This feature requires UI support as multi-line textDocument/hover results pose a problem to editors:

• Emacs
  • lsp-ui-doc https://github.com/emacs-lsp/lsp-ui
  • lsp-mode eldoc See https://github.com/emacs-lsp/lsp-mode/pull/224
• Vim
  • LanguageClient-neovim: preview window

index.multiVersion: index a file in each translation unit that includes it

It is 0 by default which is sensible for common usage: it reduces memory footprint. If both a.cc and b.cc include a.h, there is only one indexed version of a.h.

But for dependent name lookup, or references in headers that may change depending on other macros, etc, you may want to index a file multiple times to get every possible cross reference. Set the option to 1 but be cautious that it may increase index file sizes a lot. You usually want to use index.multiVersionBlacklist to exclude system headers.

{
  "index": {
    "multiVersion": 1,
    "multiVersionBlacklist": ["^/usr/include"]
  }
}

index.initialBlacklist

Files that should not be loaded on initialization, but will still be indexed after you open them.

index.onChange: re-index for every change

Default: false

A document is re-indexed when saved, updating the global index incrementally. If set to true, a document is re-indexed for every (unsaved) change. The performance may suffer, but probably convenient for playground projects.

This is best used in conjunction with empty cacheDirectory to avoid writing cache files to disk:

{
  "cacheDirectory": "",
  "index": {"onChange": true}
}

index.trackDependency

Default: 2

This options controls whether a file should be re-indexed when any of its dependencies changes timestamp.

If a.h has been changed, when you open a.cc which includes a.h, an index request will be sent.

• 0: no re-indexing unless a.cc itself changes timestamp.
• 2: the index of a.cc is considered stale and it should be re-indexed.
• 1: before the initial load, the behavior of 2 is used, otherwise the behavior of 0 is used.

completion.filterAndSort: completion filtering and sorting

ccls filters and sorts completions to try to be nicer to clients that can't handle big numbers of completion candidates. This behaviour can be disabled by specifying false for the option.

This option is the most useful for LSP clients that implement their own filtering and sorting logic.