Google Git
Sign in
chromium / chromium / src / lkgr / . / docs / clangd.md
blob: d92c1c2801e91ce6bd37490b49699e00529d9f21 [file] [log] [blame] [view]
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]1# Clangd
2
3## Introduction
4
Andrew Williamsbbc1a1e2021-07-21 01:51:22[diff] [blame]5[clangd](https://clangd.llvm.org/) is a clang-based [language server](https://langserver.org/).
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]6It brings IDE features (e.g. diagnostics, code completion, code navigations) to
7your editor.
8
Ivan Šandrkde3cc762020-12-02 16:55:28[diff] [blame]9## Quick Start
10
K. Moon5ecc4b12022-08-29 17:28:44[diff] [blame]11* [Get clangd](#getting-clangd)
Ivan Šandrkde3cc762020-12-02 16:55:28[diff] [blame]12* Make sure generated ninja files are up-to-date
13* Optional: build chrome normally to get generated headers
14* Generate compilation database (note: it's not regenerated automatically):
15```
Orr Bernstein197b492a2023-05-31 19:26:33[diff] [blame]16tools/clang/scripts/generate_compdb.py -p out/Default > compile_commands.json
Ivan Šandrkde3cc762020-12-02 16:55:28[diff] [blame]17```
Orr Bernstein197b492a2023-05-31 19:26:33[diff] [blame]18
19*** note
20Note: If you're using a different build directory, you'll need to replace `out/Default`
21in this and other commands with your build directory.
22***
23
Kadir Cetinkaya235b7142021-09-21 07:24:38[diff] [blame]24* Indexing is enabled by default (since clangd 9), note that this might consume
25 lots of CPU and RAM. There's also a
26 [remote-index service](https://github.com/clangd/chrome-remote-index/blob/main/docs/index.md)
27 to have an instant project-wide index without consuming local resources
Delan Azabanid431ca72022-01-26 09:03:46[diff] [blame]28 (requires clangd 12+ built with remote index support).
Ivan Šandrkde3cc762020-12-02 16:55:28[diff] [blame]29* Use clangd in your favourite editor
30
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]31## Getting clangd
32
K. Moon5ecc4b12022-08-29 17:28:44[diff] [blame]33For the best results, you should use a clangd that exactly matches the version
34of Clang used by Chromium. This avoids problems like mismatched versions of
35compiler diagnostics.
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]36
K. Moon5ecc4b12022-08-29 17:28:44[diff] [blame]37The easiest way to do this is to set the `checkout_clangd` var in `.gclient`:
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]38
K. Moon5ecc4b12022-08-29 17:28:44[diff] [blame]39```
40solutions = [
41 {
42 "url": "https://chromium.googlesource.com/chromium/src.git",
43 "managed": False,
44 "name": "src",
45 "custom_deps": {},
46 "custom_vars": {
47 "checkout_clangd": True,
48 },
49 },
50]
51```
Jesse McKennaf454c392020-06-05 01:10:16[diff] [blame]52
K. Moon5ecc4b12022-08-29 17:28:44[diff] [blame]53After this, `gclient` will keep the binary at
54`third_party/llvm-build/Release+Asserts/bin/clangd` in sync with the version of
55Clang used by Chromium.
Jesse McKennaf454c392020-06-05 01:10:16[diff] [blame]56
K. Moon5ecc4b12022-08-29 17:28:44[diff] [blame]57Alternatively, you may use the `build_clang_tools_extra.py` script to build
58clangd from source:
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]59
60```
Kadir Cetinkaya235b7142021-09-21 07:24:38[diff] [blame]61tools/clang/scripts/build_clang_tools_extra.py --fetch out/Default clangd
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]62```
63
K. Moon5ecc4b12022-08-29 17:28:44[diff] [blame]64The resulting binary will be at
65`out/Default/tools/clang/third_party/llvm/build/bin/clangd`.
66
67Once you have an appropriate clangd binary, you must configure your editor to
68use it, either by placing it first on your `PATH`, or through editor-specific
69configuration.
70
K. Moone7c45982022-08-31 18:49:19[diff] [blame]71*** note
72Note: The clangd provided by Chromium does not support optional features like
Delan Azabani9e7f4ce2024-05-02 11:55:18[diff] [blame]73remote indexing (see https://crbug.com/1358258), such that `clangd --version`
74will not mention `grpc`, and you will see “Unknown Index key External” warnings
75in the clangd log.
76
77If you want those features, you'll need to use a different build of clangd,
78such as the [clangd/clangd releases on
79GitHub](https://github.com/clangd/clangd/releases).
K. Moone7c45982022-08-31 18:49:19[diff] [blame]80***
81
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]82## Setting Up
83
David Benjaminf676adb12019-05-07 07:19:10[diff] [blame]841. Make sure generated ninja files are up-to-date.
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]85
86```
Kadir Cetinkaya235b7142021-09-21 07:24:38[diff] [blame]87gn gen out/Default
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]88```
89
902. Generate the compilation database, clangd needs it to know how to build a
91source file.
92
93```
Kadir Cetinkaya235b7142021-09-21 07:24:38[diff] [blame]94tools/clang/scripts/generate_compdb.py -p out/Default > compile_commands.json
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]95```
96
Jesse McKennaf454c392020-06-05 01:10:16[diff] [blame]97Note: the compilation database is not regenerated automatically. You need to
98regenerate it manually whenever build rules change, e.g., when you have new files
Fergal Daly6e028572020-06-02 09:43:05[diff] [blame]99checked in or when you sync to head.
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]100
Jesse McKenna454b946f2020-05-08 18:23:10[diff] [blame]101If using Windows PowerShell, use the following command instead to set the
102output's encoding to UTF-8 (otherwise Clangd will hit "YAML:1:4: error: Got
103empty plain scalar" while parsing it).
104
105```
Kadir Cetinkaya235b7142021-09-21 07:24:38[diff] [blame]106tools/clang/scripts/generate_compdb.py -p out/Default | out-file -encoding utf8 compile_commands.json
Jesse McKenna454b946f2020-05-08 18:23:10[diff] [blame]107```
108
David Benjaminf676adb12019-05-07 07:19:10[diff] [blame]1093. Optional: build chrome normally. This ensures generated headers exist and are
110up-to-date. clangd will still work without this step, but it may give errors or
111inaccurate results for files which depend on generated headers.
112
113```
Kadir Cetinkaya235b7142021-09-21 07:24:38[diff] [blame]114ninja -C out/Default chrome
David Benjaminf676adb12019-05-07 07:19:10[diff] [blame]115```
116
Kadir Cetinkaya235b7142021-09-21 07:24:38[diff] [blame]1174. Optional: configure clangd to use remote-index service for an instant
118 project-wide index and reduced local CPU and RAM usage. See
119 [instructions](https://github.com/clangd/chrome-remote-index/blob/main/docs/index.md).
120
1215. Use clangd in your favourite editor, see detailed [instructions](
Andrew Williamsbbc1a1e2021-07-21 01:51:22[diff] [blame]122https://clangd.llvm.org/installation.html#editor-plugins).
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]123
Victor Vianna418575882023-02-20 16:19:44[diff] [blame]124 * Optional: You may want to add `--header-insertion=never` to the clangd
Avi Drissmand4459db2023-01-18 02:45:14[diff] [blame]125 flags, so that your editor doesn't automatically add incorrect #include
126 lines. The feature doesn't correctly handle some common Chromium headers
Lei Zhangc5f765d52023-11-08 00:53:33[diff] [blame]127 like `base/functional/callback_forward.h`.
Joe Masonee336f82022-01-19 22:39:09[diff] [blame]128
Ivan Šandrkde3cc762020-12-02 16:55:28[diff] [blame]129## Background Indexing
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]130
Ivan Šandrkde3cc762020-12-02 16:55:28[diff] [blame]131clangd builds an incremental index of your project (all files listed in the
132compilation database). The index improves code navigation features
133(go-to-definition, find-references) and code completion.
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]134
Ivan Šandrkde3cc762020-12-02 16:55:28[diff] [blame]135* clangd only uses idle cores to build the index, you can limit the total amount
136 of cores by passing the *-j=\<number\>* flag;
Henrique Ferreirocb655422023-12-02 09:52:23[diff] [blame]137* the index is saved to the `.cache/clangd/index` in the project root; index
138 shards for common headers e.g. STL will be stored in
139 *$HOME/.cache/clangd/index*;
Ivan Šandrkde3cc762020-12-02 16:55:28[diff] [blame]140* background indexing can be disabled by the `--background-index=false` flag;
141 Note that, disabling background-index will limit clangd’s knowledge about your
142 codebase to files you are currently editing.
143
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]144Note: the first index time may take hours (for reference, it took 2~3 hours on
Ivan Šandrkde3cc762020-12-02 16:55:28[diff] [blame]145a 48-core, 64GB machine). A full index of Chromium (including v8, blink) takes
146~550 MB disk space and ~2.7 GB memory in clangd.
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]147
Kadir Cetinkaya235b7142021-09-21 07:24:38[diff] [blame]148Note: [Remote-index service](https://github.com/clangd/chrome-remote-index/blob/main/docs/index.md)
149replaces background-index with some downsides like being ~a day old (Clangd will
150still know about your changes in the current editing session) and not covering
151all configurations (not available for mac&windows specific code or non-main
152branches).
153
Haojian Wuaa891f172019-04-05 14:56:52[diff] [blame]154## Questions
155
Kadir Cetinkaya235b7142021-09-21 07:24:38[diff] [blame]156If you have any questions, reach out to
157[clangd/clangd](https://github.com/clangd/clangd) or [email protected].