docs/clangd/Installation.rst

===========================
Getting started with clangd
===========================

.. contents::

.. role:: raw-html(raw)
   :format: html

To use clangd, you need to:

- install clangd,
- install a plugin for your editor,
- tell clangd how your project is built.

Installing clangd
=================

You need a **recent** version of clangd: 7.0 was the first usable release, and
8.0 is much better.

After installing, ``clangd --version`` should print ``clangd version 7.0.0`` or
later.

:raw-html:`<details><summary markdown="span">macOS</summary>`

`Homebrew <https://brew.sh>`__ can install clangd along with LLVM:

.. code-block:: console

  $ brew install llvm

If you don't want to use Homebrew, you can download the a binary release of
LLVM from `releases.llvm.org <http://releases.llvm.org/download.html>`__.
Alongside ``bin/clangd`` you will need at least ``lib/clang/*/include``:

.. code-block:: console

  $ cp clang+llvm-7.0.0/bin/clangd /usr/local/bin/clangd
  $ cp -r clang+llvm-7.0.0/lib/clang/ /usr/local/lib/

:raw-html:`</details>`

:raw-html:`<details><summary markdown="span">Windows</summary>`

Download and run the LLVM installer from `releases.llvm.org
<http://releases.llvm.org/download.html>`__.

:raw-html:`</details>`

:raw-html:`<details><summary markdown="span">Debian/Ubuntu</summary>`

The ``clang-tools`` package usually contains an old version of clangd.

Try to install the latest release (8.0):

.. code-block:: console

  $ sudo apt-get install clang-tools-8

If that is not found, at least ``clang-tools-7`` should be available.

The ``clangd`` executable will be installed as ``/usr/bin/clangd-8``. Make it
the default ``clangd``:

.. code-block:: console

  $ sudo update-alternatives --install /usr/bin/clangd clangd /usr/bin/clangd-8 100

:raw-html:`</details>`

:raw-html:`<details><summary markdown="span">Other systems</summary>`

Most distributions include clangd in a ``clang-tools`` package, or in the full
``llvm`` distribution.

For some platforms, binaries are also avaliable at `releases.llvm.org
<http://releases.llvm.org/download.html>`__.

:raw-html:`</details>`

Editor plugins
==============

Language Server plugins are available for many editors. In principle, clangd
should work with any of them, though the feature set and UI may vary.

Here are some plugins we know work well with clangd.

:raw-html:`<details><summary markdown="span">YouCompleteMe for Vim</summary>`

`YouCompleteMe <https://valloric.github.io/YouCompleteMe/>`__ supports clangd.
However, clangd support is not turned on by default, so you must install
YouCompleteMe with ``install.py --clangd-completer``.

We recommend changing a couple of YCM's default settings. In ``.vimrc`` add:

::

  " Let clangd fully control code completion
  let g:ycm_clangd_uses_ycmd_caching = 0
  " Use installed clangd, not YCM-bundled clangd which doesn't get updates.
  let g:ycm_clangd_binary_path = exepath("clangd")

You should see errors highlighted and code completions as you type.

.. image:: CodeCompletionInYCM.png
   :align: center
   :alt: Code completion in YouCompleteMe

YouCompleteMe supports many of clangd's features:

- code completion,
- diagnostics and fixes (``:YcmCompleter FixIt``),
- find declarations, references, and definitions (``:YcmCompleter GoTo`` etc),
- rename symbol (``:YcmCompleter RefactorRename``).

**Under the hood**

- **Debug logs**: run ``:YcmDebugInfo`` to see clangd status, and ``:YcmToggleLogs``
  to view clangd's debug logs.
- **Command-line flags**: Set ``g:ycm_clangd_args`` in ``.vimrc``, e.g.:

  ::

    let g:ycm_clangd_args = ['-log=verbose', '-pretty']

- **Alternate clangd binary**: set ``g:ycm_clangd_binary_path`` in ``.vimrc``.

:raw-html:`</details>`

:raw-html:`<details><summary markdown="span">LanguageClient for Vim and Neovim</summary>`

`LanguageClient-neovim <https://github.com/autozimu/LanguageClient-neovim>`__
has `instructions for using clangd
<https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`__, and **may**
be easier to install than YouCompleteMe.

:raw-html:`</details>`

:raw-html:`<details><summary markdown="span">Eglot for Emacs</summary>`

`eglot <https://github.com/joaotavora/eglot>`__ can be configured to work with
clangd.

Install eglot with ``M-x package-install RET eglot RET``.

Add the following to ``~/.emacs`` to enable clangd:

::

  (require 'eglot)
  (add-to-list 'eglot-server-programs '((c++-mode c-mode) "clangd"))
  (add-hook 'c-mode-hook 'eglot-ensure)
  (add-hook 'c++-mode-hook 'eglot-ensure)

After restarting you should see diagnostics for errors in your code, and ``M-x
completion-at-point`` should work.

.. image:: DiagnosticsInEmacsEglot.png
   :align: center
   :alt: Diagnostics in Emacs

eglot supports many of clangd's features, with caveats:

- code completion, though the interaction is quite poor (even with
  ``company-mode``, see below),
- diagnostics and fixes,
- find definitions and references (``M-x xref-find-definitions`` etc),
- hover and highlights,
- code actions (``M-x eglot-code-actions``).

**company-mode**

eglot does have basic integration with company-mode, which provides a more
fluent completion UI.

You can install it with ``M-x package-install RET company RET``, and enable it
with ``M-x company-mode``.

**company-clang is enabled by default**, and will interfere with clangd.
Disable it in ``M-x customize-variable RET company-backends RET``.

Completion still has some major limitations:

- completions are alphabetically sorted, not ranked.
- only pure-prefix completions are shown - no fuzzy matches.
- completion triggering seems to be a bit hit-and-miss.

.. image:: CodeCompletionInEmacsCompanyMode.png
   :align: center
   :alt: Completion in company-mode

**Under the hood**

- **Debug logs**: available in the ``EGLOT stderr`` buffer.
- **Command-line flags and alternate binary**: instead of adding ``"clangd"``
  to ``eglot-server-programs``, add ``("/path/to/clangd" "-log=verbose")`` etc.

:raw-html:`</details>`

:raw-html:`<details><summary markdown="span">Visual Studio Code</summary>`

The official extension is `vscode-clangd
<https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`__
and can be installed from within VSCode.

Choose **View** --> **Extensions**, then search for "clangd". (Make sure the
Microsoft C/C++ extension is **not** installed).

After restarting, you should see red underlines underneath errors, and you
should get rich code completions including e.g. function parameters.

.. image:: CodeCompletionInVSCode.png
   :align: center
   :alt: Code completion in VSCode

vscode-clangd has excellent support for all clangd features, including:

- code completion
- diagnostics and fixes
- find declarations, references, and definitions
- find symbol in file (``Ctrl-P @foo``) or workspace (``Ctrl-P #foo``)
- hover and highlights
- code actions

**Under the hood**

- **Debug logs**: when clangd is running, you should see "Clang Language
  Server" in the dropdown of the Output panel (**View** -> **Output**).

- **Command-line flags**: these can be passed in the ``clangd.arguments`` array
  in your ``settings.json``. (**File** -> **Preferences** -> **Settings**).

- **Alternate clangd binary**: set the ``clangd.path`` string in
  ``settings.json``.

:raw-html:`</details>`

:raw-html:`<details><summary markdown="span">Sublime Text</summary>`

`tomv564/LSP <https://github.com/tomv564/LSP>`__ works with clangd out of the box.

Select **Tools** --> **Install Package Control** (if you haven't installed it
yet).

Press ``Ctrl-Shift-P`` and select **Package Control: Install Package**. Select
**LSP**.

Press ``Ctrl-Shift-P`` and select **LSP: Enable Language Server Globally**.
Select **clangd**.

Open a C++ file, and you should see diagnostics and completion:

.. image:: CodeCompletionInSublimeText.png
   :align: center
   :alt: Code completion in Sublime Text


The LSP package has excellent support for all most clangd features, including:

- code completion (a bit noisy due to how snippets are presented)
- diagnostics and fixes
- find definition and references
- hover and highlights
- code actions

**Under the hood**

Settings can be tweaked under **Preferences** --> **Package Settings** -->
**LSP**.

- **Debug logs**: add ``"log_stderr": true``
- **Command-line flags and alternate clangd binary**: inside the ``"clients":
  {"clangd": { ... } }`` section, add ``"command": ["/path/to/clangd",
  "-log=verbose"]`` etc.

:raw-html:`</details>`

:raw-html:`<details><summary markdown="span">Other editors</summary>`

There is a directory of LSP clients at `langserver.org
<http://langserver.org>`__.

A generic client should be configured to run the command ``clangd``, and
communicate via the language server protocol on standard input/output.

If you don't have strong feelings about an editor, we suggest you try out
`VSCode <https://code.visualstudio.com/>`__, it has excellent language server
support and most faithfully demonstrates what clangd can do.

:raw-html:`</details>`

Project setup
=============

To understand source code in your project, clangd needs to know the build
flags.  (This is just a fact of life in C++, source files are not
self-contained.)

By default, clangd will assume that source code is built as ``clang
some_file.cc``, and you'll probably get spurious errors about missing
``#include``\ d files, etc.  There are a couple of ways to fix this.

``compile_commands.json``
-------------------------

``compile_commands.json`` file provides compile commands for all source files
in the project.  This file is usually generated by the build system, or tools
integrated with the build system.  Clangd will look for this file in the parent
directories of the files you edit.

:raw-html:`<details><summary markdown="span">CMake-based projects</summary>`

If your project builds with CMake, it can generate ``compile_commands.json``.
You should enable it with:

::

  $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1

``compile_commands.json`` will be written to your build directory.  You should
symlink it (or copy it) to the root of your source tree, if they are different.

::

  $ ln -s ~/myproject-build/compile_commands.json ~/myproject/

:raw-html:`</details>`

:raw-html:`<details><summary markdown="span">Other build systems, using Bear</summary>`

`Bear <https://github.com/rizsotto/Bear>`__ is a tool that generates a
``compile_commands.json`` file by recording a complete build.

For a ``make``-based build, you can run ``make clean; bear make`` to generate the
file (and run a clean build!)

:raw-html:`</details>`

Other tools can also generate this file. See `the compile_commands.json
specification <https://clang.llvm.org/docs/JSONCompilationDatabase.html>`__.

``compile_flags.txt``
---------------------

If all files in a project use the same build flags, you can put those flags,
one flag per line, in ``compile_flags.txt`` in your source root.

Clangd will assume the compile command is ``clang $FLAGS some_file.cc``.

Creating this file by hand is a reasonable place to start if your project is
quite simple.

Background Indexing
===================

clangd builds an incremental index of your project (all files listed in the
compilation database). The index improves code navigation features (go-to-definition,
find-references) and code completion.

- clangd only uses idle cores to build the index, you can limit the total
  amount of cores by passing the `-j=<number>` flag;
- the index is saved to the ``.clangd/index`` in the project root; index shards
  for common headers e.g. STL will be stored in `$HOME/.clangd/index`;
- background indexing can be disabled by the ``--background-index=false`` flag;
  Note that, disabling background-index will limit clangd's knowledge about your
  codebase to files you are currently editing.

Build Index Manually
====================

**DISCLAIMER: This is mainly for clangd developers.**

There is a `clangd-indexer <https://github.com/llvm/llvm-project/blob/master/clang-tools-extra/clangd/indexer/IndexerMain.cpp>`__
which generates an index file for your project. To use the index, pass the flag
`-index=file=/path/to/index_file` to clangd. *Note that clangd-indexer isn't
included alongside clangd in the Debian clang-tools package. You will likely
have to build it from source to use this option.*