forked from OSchip/llvm-project
380 lines
12 KiB
ReStructuredText
380 lines
12 KiB
ReStructuredText
===========================
|
|
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.*
|