1# vscode-clangd
2
3Provides C/C++ language IDE features for VS Code using [clangd](https://clang.llvm.org/extra/clangd.html):
4
5 - code completion
6 - compile errors and warnings
7 - go-to-definition and cross references
8 - include management
9 - code formatting
10 - simple refactorings
11
12## Setup
13
14### `clangd` server
15
16`clangd` is a language server that must be installed separately, see
17[getting started](https://clang.llvm.org/extra/clangd/Installation.html#installing-clangd).
18The vscode-clangd extension will look for `clangd` on your PATH (you can change
19this in the settings).
20
21### Project setup
22
23clangd is based on the clang C++ compiler, and understands even complex C++
24code.  However, you must tell clangd how your project is built (compile flags).
25[A `compile_commands.json` file](http://clang.llvm.org/docs/JSONCompilationDatabase.html)
26can usually be generated by your build system
27(e.g. by setting `-DCMAKE_EXPORT_COMPILE_COMMANDS=1` when building with CMake,
28or with
29[many other tools](https://sarcasm.github.io/notes/dev/compilation-database.html)).
30
31It should live at the top of your source tree: symlink or copy it there.
32
33## Features
34
35### Code completion
36
37Suggestions will appear as you type names, or after `.` or `->`.
38Because clangd uses a full C++ parser, code completion has access to precise
39type information.
40
41![Code completion](doc-assets/complete.png)
42
43### Errors, warnings, and clang-tidy
44
45Code errors are shown as you type (both as red squiggle underlines, and in the
46"Problems" panel). These are the same as produced by the clang compiler, and
47suggested fixes can automatically be applied.
48
49![Error with fix](doc-assets/diagnostics.png)
50
51Most clang-tidy checks are supported (these can be enabled using a [.clang-tidy
52file](https://clang.llvm.org/extra/clang-tidy/)).
53
54### Cross-references
55
56Go-to-definition and find-references work across your code, using a project-wide
57index.
58
59![Cross-reference list](doc-assets/xrefs.png)
60
61Press `Ctrl-P #` to quickly navigate to a symbol by name.
62
63### Include management
64
65Code completion works across your codebase and adds `#include` directives where
66needed. The `•` shows includes that will be inserted.
67
68clangd can also suggest inserting missing #includes, where they cause errors.
69
70![Fix inserts include](doc-assets/include.png)
71
72### Formatting
73
74clangd uses the `clang-format` engine. You can format a file or the selection.
75When "Format on Type" is enabled in the settings, pressing enter will cause
76clangd to format the old line and semantically reindent.
77
78![Format-on-type](doc-assets/format.png)
79
80The style used for formatting (and certain other operations) is controlled by
81the .clang-format file is controlled by the project's
82[.clang-format file](https://clang.llvm.org/docs/ClangFormatStyleOptions.html).
83
84### Refactoring
85
86clangd supports some local refactorings. When you select an expression or
87declaration, the lightbulb menu appears and you can choose a code action.
88
89![Extract variable code action](doc-assets/extract.png)
90
91Current refactorings include:
92 - extract variable/function
93 - expand `auto` types and macros
94 - use raw strings
95 - rename (bound to `<F2>`, rather than a contextual code action)
96
97## Bugs/contributing
98
99clangd and vscode-clangd are part of the [LLVM project](https://llvm.org).
100
101If you'd like to help out, reach out to clangd-dev@lists.llvm.org.
102
103If you've found a bug, please file at https://github.com/clangd/clangd/issues.
104