231 changes: 231 additions & 0 deletions clang-tools-extra/docs/clangd/Features.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,231 @@
========
Features
========

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

Here is what clangd can do for you. Screenshots below show `VSCode
<https://code.visualstudio.com/>`__; the available features and UI depend on
the editor.

Errors and warnings
===================

clangd runs the clang compiler on your code as you type, and shows errors and
warnings in-place. Some errors are suppressed: diagnostics that require
expanding templates in headers are disabled for performance reasons.

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

.. image:: ErrorsInVSCode.png
:align: center
:alt: Demonstration of errors

:raw-html:`</details>`

Fixes in errors and warnings
----------------------------

The compiler can suggest fixes for many common problems automatically, and
clangd can update the code for you.

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

.. image:: ApplyFixInVSCode.gif
:align: center
:alt: Applying a fix suggested by the compiler

:raw-html:`</details>`

Code completion
===============

You'll see suggestions as you type based on what methods, variables, etc are
available in this context.

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

.. image:: CodeCompletionInVSCode.png
:align: center
:alt: Code completion demonstration

:raw-html:`</details>`

Abbreviating words may help you find the right result faster. If you type in
``camelCase`` but the function you're looking for is ``snake_case``, that's OK.

Insertion of namespace qualifiers and includes
----------------------------------------------

**(New in v8)**
clangd will sometimes suggest results from other files and namespaces. In this
case the correct qualifier and ``#include`` directive will be inserted.

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

.. image:: CodeCompletionInsertsNamespaceQualifiersInVSCode.gif
:align: center
:alt: Code completion inserts namespace qualifiers

:raw-html:`</details>`

Signature help
--------------

Some editors will show you the parameters of the function you're calling, as
you fill them in.

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

.. image:: SignatureHelpInVSCode.gif
:align: center
:alt: Demonstration of the signature help feature

:raw-html:`</details>`

Cross-references
================

The following features let you navigate your codebase.

If there is no project-wide index, cross-references work across the files
you have opened.

Find definition/declaration
---------------------------

Jump to the definition or declaration of a symbol under the cursor.

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

.. image:: GoToDefinitionInVSCode.gif
:align: center
:alt: Demonstration of the "Go to definition" feature

:raw-html:`</details>`

Find references
---------------

Show all references to a symbol under the cursor.

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

.. image:: FindAllReferencesInVSCode.gif
:align: center
:alt: Demonstration of the "Find all references" feature

:raw-html:`</details>`

Some editors will automatically highlight local references to the selected
symbol as you move around a file.

Navigation
==========

clangd informs the editor of the code structure in the current file.
Some editors use this to present an outline view:

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

.. image:: OutlineInVSCode.png
:align: center
:alt: Outline of a file

:raw-html:`</details>`

In VSCode, the outline is also presented as breadcrumbs that allow jumping to a
symbol within the current file. Searching for symbols within the scope of the
whole project is also possible.

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

.. image:: NavigationWithBreadcrumbsInVSCode.gif
:align: center
:alt: Navigation with breadcrumbs

:raw-html:`</details>`

Formatting
==========

clangd embeds `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`__,
which can reformat your code: fixing indentation, breaking lines, and reflowing
comments.

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

.. image:: FormatSelectionInVSCode.gif
:align: center
:alt: Formatting selected code

:raw-html:`</details>`

clangd respects your project's ``.clang-format`` file which controls styling
options.

Format-as-you-type is experimental and doesn't work well yet.

Complete list of features
=========================

Here is a list of features that could be useful for editors, together with the
implementation status in clangd, and specification in the Language Server
Protocol.

It is not clear whether or not some of the features mentioned below should be a
part of the Language Server Protocol; those features might be eventually
developed outside clangd or become clangd extensions to LSP.

+-------------------------------------+------------+----------+
| C/C++ Editor feature | LSP | Clangd |
+=====================================+============+==========+
| Formatting | Yes | Yes |
+-------------------------------------+------------+----------+
| Completion | Yes | Yes |
+-------------------------------------+------------+----------+
| Diagnostics | Yes | Yes |
+-------------------------------------+------------+----------+
| Fix-its | Yes | Yes |
+-------------------------------------+------------+----------+
| Go to Definition | Yes | Yes |
+-------------------------------------+------------+----------+
| Signature Help | Yes | Yes |
+-------------------------------------+------------+----------+
| Document Highlights | Yes | Yes |
+-------------------------------------+------------+----------+
| Rename | Yes | Yes |
+-------------------------------------+------------+----------+
| Source hover | Yes | Yes |
+-------------------------------------+------------+----------+
| Find References | Yes | Yes |
+-------------------------------------+------------+----------+
| Document Symbols | Yes | Yes |
+-------------------------------------+------------+----------+
| Workspace Symbols | Yes | Yes |
+-------------------------------------+------------+----------+
| Code Lens | Yes | No |
+-------------------------------------+------------+----------+
| Code folding | Yes | No |
+-------------------------------------+------------+----------+
| Extract Local Variable | Yes | No |
+-------------------------------------+------------+----------+
| Extract Function/Method | Yes | No |
+-------------------------------------+------------+----------+
| Quick Assist | Yes | No |
+-------------------------------------+------------+----------+
| Hide Method | Yes | No |
+-------------------------------------+------------+----------+
| Implement Method | Yes | No |
+-------------------------------------+------------+----------+
| Gen. Getters/Setters | Yes | No |
+-------------------------------------+------------+----------+
| Syntax and Semantic Coloring | No | No |
+-------------------------------------+------------+----------+
| Call hierarchy | No | No |
+-------------------------------------+------------+----------+
| Type hierarchy | No | No |
+-------------------------------------+------------+----------+
| Organize Includes | No | No |
+-------------------------------------+------------+----------+
Binary file added clang-tools-extra/docs/clangd/FindAllReferencesInVSCode.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added clang-tools-extra/docs/clangd/FormatSelectionInVSCode.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added clang-tools-extra/docs/clangd/GoToDefinitionInVSCode.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
369 changes: 369 additions & 0 deletions clang-tools-extra/docs/clangd/Installation.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,369 @@
===========================
Getting started with clangd
===========================

.. 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/compile_commands.json ~/myproject-build/

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

Project-wide Index
==================

By default clangd only has a view on symbols coming from files you are
currently editing. You can extend this view to whole project by providing a
project-wide index to clangd. There are two ways to do this.

- Pass an experimental `-background-index` command line argument. With
this feature enabled, clangd incrementally builds an index of projects
that you work on and uses the just-built index automatically.

- Generate an index file using `clangd-indexer
<https://github.com/llvm/llvm-project/blob/master/clang-tools-extra/clangd/indexer/IndexerMain.cpp>`__
Then you can pass generated index file to clangd using
`-index-file=/path/to/index_file`. *Note that clangd-indexer isn't
included alongside clangd in the Debian clang-tools package. You will
likely have to build clangd from source to use this option.*
Binary file added clang-tools-extra/docs/clangd/NavigationWithBreadcrumbsInVSCode.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added clang-tools-extra/docs/clangd/OutlineInVSCode.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added clang-tools-extra/docs/clangd/SignatureHelpInVSCode.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
189 changes: 18 additions & 171 deletions clang-tools-extra/docs/clangd/index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,180 +1,27 @@
============
Clangd
============

.. contents::
======
clangd
======

.. toctree::
:maxdepth: 1

:program:`Clangd` is an implementation of the `Language Server Protocol
<https://github.com/Microsoft/language-server-protocol>`_ leveraging Clang.
Clangd's goal is to provide language "smartness" features like code completion,
find references, etc. for clients such as C/C++ Editors.

Using Clangd
==================

:program:`Clangd` is not meant to be used by C/C++ developers directly but
rather from a client implementing the protocol. A client would be typically
implemented in an IDE or an editor.

At the moment, `Visual Studio Code <https://code.visualstudio.com/>`_ is mainly
used in order to test :program:`Clangd` but more clients are likely to make
use of :program:`Clangd` in the future as it matures and becomes a production
quality tool. If you are interested in trying :program:`Clangd` in combination
with Visual Studio Code, you can start by `installing Clangd`_ or
`building Clangd`_, then open Visual Studio Code in the clangd-vscode folder and
launch the extension.

Installing Clangd
==================

Packages are available for debian-based distributions, see the `LLVM packages
page <https://apt.llvm.org/>`_. :program:`Clangd` is included in the
`clang-tools` package.
However, it is a good idea to check your distribution's packaging system first
as it might already be available.

Otherwise, you can install :program:`Clangd` by `building Clangd`_ first.

Building Clangd
==================

You can follow the instructions for `building Clang
<https://clang.llvm.org/get_started.html>`_ but "extra Clang tools" is **not**
optional.

Current Status
==================

Many features could be implemented in :program:`Clangd`.
Here is a list of features that could be useful with the status of whether or
not they are already implemented in :program:`Clangd` and specified in the
Language Server Protocol. Note that for some of the features, it is not clear
whether or not they should be part of the Language Server Protocol, so those
features might be eventually developed outside :program:`Clangd` or as an
extension to the protocol.

+-------------------------------------+------------+----------+
| C/C++ Editor feature | LSP | Clangd |
+=====================================+============+==========+
| Formatting | Yes | Yes |
+-------------------------------------+------------+----------+
| Completion | Yes | Yes |
+-------------------------------------+------------+----------+
| Diagnostics | Yes | Yes |
+-------------------------------------+------------+----------+
| Fix-its | Yes | Yes |
+-------------------------------------+------------+----------+
| Go to Definition | Yes | Yes |
+-------------------------------------+------------+----------+
| Signature Help | Yes | Yes |
+-------------------------------------+------------+----------+
| Document Highlights | Yes | Yes |
+-------------------------------------+------------+----------+
| Rename | Yes | Yes |
+-------------------------------------+------------+----------+
| Source hover | Yes | Yes |
+-------------------------------------+------------+----------+
| Find References | Yes | Yes |
+-------------------------------------+------------+----------+
| Document Symbols | Yes | Yes |
+-------------------------------------+------------+----------+
| Workspace Symbols | Yes | Yes |
+-------------------------------------+------------+----------+
| Code Lens | Yes | No |
+-------------------------------------+------------+----------+
| Code folding | Yes | No |
+-------------------------------------+------------+----------+
| Extract Local Variable | Yes | No |
+-------------------------------------+------------+----------+
| Extract Function/Method | Yes | No |
+-------------------------------------+------------+----------+
| Quick Assist | Yes | No |
+-------------------------------------+------------+----------+
| Hide Method | Yes | No |
+-------------------------------------+------------+----------+
| Implement Method | Yes | No |
+-------------------------------------+------------+----------+
| Gen. Getters/Setters | Yes | No |
+-------------------------------------+------------+----------+
| Syntax and Semantic Coloring | No | No |
+-------------------------------------+------------+----------+
| Call hierarchy | No | No |
+-------------------------------------+------------+----------+
| Type hierarchy | No | No |
+-------------------------------------+------------+----------+
| Organize Includes | No | No |
+-------------------------------------+------------+----------+

Editor Integration
==================

Any full-featured Language Server Protocol Client implementation should work
with :program:`Clangd`. This `list
<https://langserver.org/#implementations-client>`_ contains information about
extensions and plugins that are known to work for different editors.

Vim Integration
---------------

LanguageClient-neovim
~~~~~~~~~~~~~~~~~~~~~

One of the options of using :program:`Clangd` in :program:`vim` (or
:program:`nvim`) is to utilize `LanguageClient-neovim
<https://github.com/autozimu/LanguageClient-neovim>`_ plugin. Please see the
`Clangd Wiki page
<https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`_ for
instructions.

VSCode Integration
------------------

:program:`VSCode` provides `vscode-clangd
<https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`_
which is published in Visual Studio Marketplace and can be installed direcetly
from :program:`VSCode`.

Emacs Integration
-----------------

:program:`Emacs` provides `lsp-mode <github.com/emacs-lsp/lsp-mode>`_ and
`Eglot <https://github.com/joaotavora/eglot>`_ plugins for LSP integration.

Project-wide Index
==================
Installation
Features

By default :program:`Clangd` only has a view on symbols coming from files you
are currently editing. You can extend this view to whole project by providing a
project-wide index to :program:`Clangd`.
What is clangd?
===============

There are two ways you can generate a project-wide index for clangd:
clangd understands your C++ code and adds smart features to your editor: code
completion, compile errors, go-to-definition and more.

- Passing experimental `-background-index` commandline argument, which will
incrementally build an index of projects that you work on and make use of that
in clangd automatically.
- Generate an index file using `clangd-indexer
<https://github.com/llvm-mirror/clang-tools-extra/blob/master/clangd/indexer/IndexerMain.cpp>`_
Afterwards you can pass generated index file to clangd using
`-index-file=/path/to/index_file`. *Note that clangd-indexer isn't included
alongside clangd in the standard clang-tools package. You will likely have to
build from source to use this option*
clangd is a language server that implements the `Language Server Protocol
<https://github.com/Microsoft/language-server-protocol>`__; it can work with
many editors through a plugin. Here's Visual Studio Code with the clangd
plugin, demonstrating code completion:

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

A good place for interested contributors is the `Clangd developer mailing list
<https://lists.llvm.org/mailman/listinfo/clangd-dev>`_. For discussions with the
broader community on topics not only related to Clangd, use
`Clang developer mailing list
<https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
If you're also interested in contributing patches to :program:`Clangd`, take a
look at the `LLVM Developer Policy
<https://llvm.org/docs/DeveloperPolicy.html>`_ and `Code Reviews
<https://llvm.org/docs/Phabricator.html>`_ page. Contributions of new features
to the `Language Server Protocol
<https://github.com/Microsoft/language-server-protocol>`_ itself would also be
very useful, so that :program:`Clangd` can eventually implement them in a
conforming way.
clangd is based on the `Clang <https://clang.llvm.org>`__ C++ compiler, and is
part of the `LLVM <https://llvm.org>`__ project.
2 changes: 1 addition & 1 deletion clang-tools-extra/docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = []
html_static_path = ['_static']

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
Expand Down
1 change: 1 addition & 0 deletions clang-tools-extra/docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ Contents
pp-trace
clang-rename
clangd/index
clangd/DeveloperDocumentation
clang-doc


Expand Down