This is an archive of the discontinued LLVM Phabricator instance.

				<!DOCTYPE html>
				{% set target = meta.redirect_target %}
				<html>
				<head>
				<title>The clangd documentation has moved to clangd.llvm.org</title>
				<link rel="canonical" href="{{ target }}"/>
				<meta http-equiv="refresh" content="0;url={{ target }}" />
				</head>
				<body>
				<h1>The clangd documentation has moved to clangd.llvm.org</h1>
				<a href="{{ target }}">The new site<a>
				<script>window.location='{{ target }}'</script>
				</body>
				</html>

clang-tools-extra/docs/_templates/layout.html

	{% extends "!layout.html" %}			{% extends (meta\|default({})).template\|default("!layout.html") %}

	{% set css_files = css_files + ['_static/clang-tools-extra-styles.css'] %}			{% set css_files = css_files + ['_static/clang-tools-extra-styles.css'] %}

clang-tools-extra/docs/clangd.rst

	:orphan:			:orphan:
				:template: clangd_redirect.html
	.. meta::			:redirect_target: https://clangd.llvm.org/
	:http-equiv=refresh: 0;URL='clangd/'

	All :program:`clangd` documentation was moved to the :doc:`clangd/index` pages.

clang-tools-extra/docs/clangd/ApplyClangTidyFixInVSCode.gif

This binary file was deleted.

clang-tools-extra/docs/clangd/ApplyFixInVSCode.gif

This binary file was deleted.

clang-tools-extra/docs/clangd/CodeCompletionInEmacsCompanyMode.png

This binary file was deleted.

clang-tools-extra/docs/clangd/CodeCompletionInSublimeText.png

This binary file was deleted.

clang-tools-extra/docs/clangd/CodeCompletionInVSCode.png

This binary file was deleted.

clang-tools-extra/docs/clangd/CodeCompletionInYCM.png

This binary file was deleted.

clang-tools-extra/docs/clangd/CodeCompletionInsertsNamespaceQualifiersInVSCode.gif

This binary file was deleted.

clang-tools-extra/docs/clangd/Configuration.rst

	=============			:orphan:
	Configuration			:template: clangd_redirect.html
	=============			:redirect_target: https://clangd.llvm.org/installation.html

	.. contents::

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

	Clangd has a bunch of command-line options that can change its behaviour in
	certain situations. This page aims to define those configuration knobs.

	Those command line arguments needs to be specified in an editor-specific way.
	You can find some editor specific instructions in `here <https://clang.llvm.org/extra/clangd/Installation.html#id3>`__.

	--query-driver
	==============

	Clangd makes use of clang behind the scenes, so it might fail to detect your
	standard library or built-in headers if your project is making use of a custom
	toolchain. That is quite common in hardware-related projects, especially for the
	ones making use of gcc (e.g. ARM's `arm-none-eabi-gcc`).

	You can specify your driver as a list of globs or full paths, then clangd will
	execute drivers and fetch necessary include paths to compile your code.

	For example if you have your compilers at:
	- `/path/to/my-custom/toolchain1/arm-none-eabi-gcc`,
	- `/path/to/my-custom/toolchain2/arm-none-eabi-g++`,
	- `/path/to/my-custom2/toolchain/arm-none-eabi-g++`,

	you can provide clangd with
	`--query-driver=/path/to/my-custom/*/arm-none-eabi` to enable execution of
	any binary that has a name starting with `arm-none-eabi` and under
	`/path/to/my-custom/`. This won't allow execution of the last compiler.

	Full list of flags
	==================

	You can find out about the rest of the flags using `clangd --help`.

clang-tools-extra/docs/clangd/DeveloperDocumentation.rst

	==================================			:orphan:
	Developer documentation for clangd			:template: clangd_redirect.html
	==================================			:redirect_target: https://clangd.llvm.org/design.html

	.. toctree::
	:maxdepth: 1

	Extensions

	Compiling clangd
	================

	To build clangd from source, please follow the instructions for `building Clang
	<https://clang.llvm.org/get_started.html>`_ and include LLVM, Clang, and the
	"extra Clang tools" in your build.

	Contributing to clangd
	======================

	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 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 clangd can eventually implement them in a conforming way.

clang-tools-extra/docs/clangd/DiagnosticsInEmacsEglot.png

This binary file was deleted.

clang-tools-extra/docs/clangd/ErrorsInVSCode.png

This binary file was deleted.

clang-tools-extra/docs/clangd/Extensions.rst

	===================			:orphan:
	Protocol extensions			:template: clangd_redirect.html
	===================			:redirect_target: https://clangd.llvm.org/extensions.html

	.. contents::

	clangd supports some features that are not in the official
	`Language Server Protocol specification
	<https://microsoft.github.io/language-server-protocol/specification>`__.

	We cautious about adding extensions. The most important considerations are:

	- Editor support: How many users will the feature be available to?
	- Standardization: Is the feature stable? Is it likely to be adopted by more
	editors over time?
	- Utility: Does the feature provide a lot of value?
	- Complexity: Is this hard to implement in clangd, or constrain future work?
	Is the protocol complicated?

	These extensions may evolve or disappear over time. If you use them, try to
	recover gracefully if the structures aren't what's expected.

	Switch between the implementation file and the header
	=====================================================

	This extension is supported in clangd 6 and newer.

	Switching between the implementation file and the header is an important
	feature for C++. A language server that understands C++ can do a better job
	than the editor.

	New client->server request: ``textDocument/switchSourceHeader``.

	Lets editors switch between the main source file (``.cpp``) and header (``.h``).

	Parameter: ``TextDocumentIdentifier``: an open file.

	Result: ``string``: the URI of the corresponding header (if a source file was
	provided) or source file (if a header was provided).

	If the corresponding file can't be determined, ``""`` is returned.

	File status
	===========

	This extension is supported in clangd 8 and newer.

	It is important to provide feedback to the user when the UI is not responsive.

	This extension provides information about activity on clangd's per-file worker
	thread. This information can be displayed to users to let them know that the
	language server is busy with something. For example, in clangd, building the
	AST blocks many other operations.

	New server->client notification: ``textDocument/clangd.fileStatus``

	Sent when the current activity for a file changes. Replaces previous activity
	for that file.

	Parameter: ``FileStatus`` object with properties:

	- ``uri : string``: the document whose status is being updated.
	- ``state : string``: human-readable information about current activity.

	New initialization option: ``initializationOptions.clangdFileStatus : bool``

	Enables receiving ``textDocument/clangd.fileStatus`` notifications.

	Compilation commands
	====================

	This extension is supported in clangd 8 and newer.

	clangd relies on knowing accurate compilation options to correctly interpret a
	file. Typically they are found in a ``compile_commands.json`` file in a
	directory that contains the file, or an ancestor directory. The following
	extensions allow editors to supply the commands over LSP instead.

	New initialization option: ``initializationOptions.compilationDatabasePath : string``

	Specifies the directory containing the compilation database (e.g.,
	``compile_commands.json``). This path will be used for all files, instead of
	searching their ancestor directories.

	New initialization option: ``initializationOptions.fallbackFlags : string[]``

	Controls the flags used when no specific compile command is found. The compile
	command will be approximately ``clang $FILE $fallbackFlags`` in this case.

	New configuration setting: ``settings.compilationDatabaseChanges : {string: CompileCommand}``

	Provides compile commands for files. This can also be provided on startup as
	``initializationOptions.compilationDatabaseChanges``.

	Keys are file paths (Not URIs!)

	Values are ``{workingDirectory: string, compilationCommand: string[]}``.

	Force diagnostics generation
	============================

	This extension is supported in clangd 7 and newer.

	Clangd does not regenerate diagnostics for every version of a file (e.g., after
	every keystroke), as that would be too slow. Its heuristics ensure:

	- diagnostics do not get too stale,
	- if you stop editing, diagnostics will catch up.

	This extension allows editors to force diagnostics to be generated or not
	generated at a particular revision.

	New property of ``textDocument/didChange`` request: ``wantDiagnostics : bool``

	- if true, diagnostics will be produced for exactly this version.
	- if false, diagnostics will not be produced for this version, even if there
	are no further edits.
	- if unset, diagnostics will be produced for this version or some subsequent
	one in a bounded amount of time.

	Diagnostic categories
	=====================

	This extension is supported in clangd 8 and newer.

	Clang compiler groups diagnostics into categories (e.g., "Inline Assembly
	Issue"). Clangd can emit these categories for interested editors.

	New property of ``Diagnostic`` object: ``category : string``:

	A human-readable name for a group of related diagnostics. Diagnostics with the
	same code will always have the same category.

	New client capability: ``textDocument.publishDiagnostics.categorySupport``:

	Requests that clangd send ``Diagnostic.category``.

	Inline fixes for diagnostics
	============================

	This extension is supported in clangd 8 and newer.

	LSP specifies that code actions for diagnostics (fixes) are retrieved
	asynchronously using ``textDocument/codeAction``. clangd always computes fixes
	eagerly. Providing them alongside diagnostics can improve the UX in editors.

	New property of ``Diagnostic`` object: ``codeActions : CodeAction[]``:

	All the code actions that address this diagnostic.

	New client capability: ``textDocument.publishDiagnostics.codeActionsInline : bool``

	Requests clangd to send ``Diagnostic.codeActions``.

	Symbol info request
	===================

	This extension is supported in clangd 8 and newer.

	New client->server request: ``textDocument/symbolInfo``:

	This request attempts to resolve the symbol under the cursor, without
	retrieving further information (like definition location, which may require
	consulting an index). This request was added to support integration with
	indexes outside clangd.

	Parameter: ``TextDocumentPositionParams``

	Response: ``SymbolDetails``, an object with properties:

	- ``name : string`` the unqualified name of the symbol
	- ``containerName : string`` the enclosing namespace, class etc (without
	trailing ``::``)
	- ``usr : string``: the clang-specific "unified symbol resolution" identifier
	- ``id : string?``: the clangd-specific opaque symbol ID

clang-tools-extra/docs/clangd/Features.rst

	========			:orphan:
	Features			:template: clangd_redirect.html
	========			:redirect_target: https://clangd.llvm.org/features.html

	.. contents::

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

	(New in v9)
	If a missing symbol was seen in a file you've edited recently, clangd will
	suggest inserting it.

	clang-tidy checks
	-----------------

	(New in v9)
	clangd embeds `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`__
	which provides extra hints about code problems: bug-prone patterns,
	performance traps, and style issues.

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

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

	:raw-html:`</details>`

	clangd respects your project's ``.clang-tidy`` file which controls the checks
	to run. Not all checks work within clangd. You must pass the ``-clang-tidy``
	flag to enable this feature.

	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.

	(New in v9)
	clangd will also automatically index your whole project.

	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>`

	(New in v9)
	Some editors only expose "find definition"; use "find definition" on the
	definition to jump to the declaration.

	"Find definition" also works on ``#include`` lines, to jump to the included
	file.

	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 \|Proposed [1]_\| Yes \|
	+-------------------------------------+-------------+----------+
	\| Call hierarchy \|Proposed [2]_\| No \|
	+-------------------------------------+-------------+----------+
	\| Type hierarchy \|Proposed [3]_\| Yes \|
	+-------------------------------------+-------------+----------+
	\| Organize Includes \| Yes \| No \|
	+-------------------------------------+-------------+----------+

	.. [1] https://github.com/microsoft/language-server-protocol/issues/18
	.. [2] https://github.com/microsoft/language-server-protocol/issues/468
	.. [3] https://github.com/microsoft/language-server-protocol/issues/136

clang-tools-extra/docs/clangd/FindAllReferencesInVSCode.gif

This binary file was deleted.

clang-tools-extra/docs/clangd/FormatSelectionInVSCode.gif

This binary file was deleted.

clang-tools-extra/docs/clangd/GoToDefinitionInVSCode.gif

This binary file was deleted.

clang-tools-extra/docs/clangd/Installation.rst

	===========================			:orphan:
	Getting started with clangd			:template: clangd_redirect.html
	===========================			:redirect_target: https://clangd.llvm.org/installation.html

	.. 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 available 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.*

clang-tools-extra/docs/clangd/NavigationWithBreadcrumbsInVSCode.gif

This binary file was deleted.

clang-tools-extra/docs/clangd/OutlineInVSCode.png

This binary file was deleted.

clang-tools-extra/docs/clangd/SignatureHelpInVSCode.gif

This binary file was deleted.

clang-tools-extra/docs/clangd/index.rst

	======			:orphan:
	clangd			:template: clangd_redirect.html
	======			:redirect_target: https://clangd.llvm.org/

	.. toctree::
	:maxdepth: 1

	Installation
	Features
	Configuration

	What is clangd?
	===============

	clangd understands your C++ code and adds smart features to your editor: code
	completion, compile errors, go-to-definition and more.

	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:

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

	clangd is based on the `Clang <https://clang.llvm.org>`__ C++ compiler, and is
	part of the `LLVM <https://llvm.org>`__ project.

clang-tools-extra/docs/index.rst

	Show All 14 Lines
	.. toctree::			.. toctree::
	:maxdepth: 2			:maxdepth: 2

	clang-tidy/index			clang-tidy/index
	clang-include-fixer			clang-include-fixer
	modularize			modularize
	pp-trace			pp-trace
	clang-rename			clang-rename
	clangd/index			clangd <https://clangd.llvm.org/>
	clangd/DeveloperDocumentation
	clang-doc			clang-doc


	Doxygen Documentation			Doxygen Documentation
	=====================			=====================
	The Doxygen documentation describes the internal software that makes up the			The Doxygen documentation describes the internal software that makes up the
	tools of clang-tools-extra, not the external use of these tools. The Doxygen			tools of clang-tools-extra, not the external use of these tools. The Doxygen
	documentation contains no instructions about how to use the tools, only the APIs			documentation contains no instructions about how to use the tools, only the APIs
	Show All 18 Lines

This is an archive of the discontinued LLVM Phabricator instance.

[clangd] Redirect documentation to clangd.llvm.org.ClosedPublic

Details

Diff Detail

Event Timeline

Revision Contents

Diff 249887

clang-tools-extra/docs/_templates/clangd_redirect.html

clang-tools-extra/docs/_templates/layout.html

clang-tools-extra/docs/clangd.rst

clang-tools-extra/docs/clangd/ApplyClangTidyFixInVSCode.gif

clang-tools-extra/docs/clangd/ApplyFixInVSCode.gif

clang-tools-extra/docs/clangd/CodeCompletionInEmacsCompanyMode.png

clang-tools-extra/docs/clangd/CodeCompletionInSublimeText.png

clang-tools-extra/docs/clangd/CodeCompletionInVSCode.png

clang-tools-extra/docs/clangd/CodeCompletionInYCM.png

clang-tools-extra/docs/clangd/CodeCompletionInsertsNamespaceQualifiersInVSCode.gif

clang-tools-extra/docs/clangd/Configuration.rst

clang-tools-extra/docs/clangd/DeveloperDocumentation.rst

clang-tools-extra/docs/clangd/DiagnosticsInEmacsEglot.png

clang-tools-extra/docs/clangd/ErrorsInVSCode.png

clang-tools-extra/docs/clangd/Extensions.rst

clang-tools-extra/docs/clangd/Features.rst

clang-tools-extra/docs/clangd/FindAllReferencesInVSCode.gif

clang-tools-extra/docs/clangd/FormatSelectionInVSCode.gif

clang-tools-extra/docs/clangd/GoToDefinitionInVSCode.gif

clang-tools-extra/docs/clangd/Installation.rst

clang-tools-extra/docs/clangd/NavigationWithBreadcrumbsInVSCode.gif

clang-tools-extra/docs/clangd/OutlineInVSCode.png

clang-tools-extra/docs/clangd/SignatureHelpInVSCode.gif

clang-tools-extra/docs/clangd/index.rst

clang-tools-extra/docs/index.rst

[clangd] Redirect documentation to clangd.llvm.org.
ClosedPublic