From: Sam McCall Date: Thu, 12 Mar 2020 09:55:31 +0000 (+0100) Subject: [clangd] Redirect documentation to clangd.llvm.org. X-Git-Tag: llvmorg-12-init~12320 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=57e81a2f649099229e1d50b36aeee5eb1b9e3d49;p=platform%2Fupstream%2Fllvm.git [clangd] Redirect documentation to clangd.llvm.org. Reviewers: hokein Subscribers: ilya-biryukov, MaskRay, jkorous, arphaman, kadircet, usaxena95, cfe-commits Tags: #clang Differential Revision: https://reviews.llvm.org/D76053 --- diff --git a/clang-tools-extra/docs/_templates/clangd_redirect.html b/clang-tools-extra/docs/_templates/clangd_redirect.html new file mode 100644 index 0000000..c4f6927 --- /dev/null +++ b/clang-tools-extra/docs/_templates/clangd_redirect.html @@ -0,0 +1,14 @@ + +{% set target = meta.redirect_target %} + + + The clangd documentation has moved to clangd.llvm.org + + + + +

The clangd documentation has moved to clangd.llvm.org

+ The new site + + + diff --git a/clang-tools-extra/docs/_templates/layout.html b/clang-tools-extra/docs/_templates/layout.html index b4f5b4e..dd20b6f 100644 --- a/clang-tools-extra/docs/_templates/layout.html +++ b/clang-tools-extra/docs/_templates/layout.html @@ -1,3 +1,3 @@ -{% extends "!layout.html" %} +{% extends (meta|default({})).template|default("!layout.html") %} {% set css_files = css_files + ['_static/clang-tools-extra-styles.css'] %} diff --git a/clang-tools-extra/docs/clangd.rst b/clang-tools-extra/docs/clangd.rst index 7910fac..70bab83 100644 --- a/clang-tools-extra/docs/clangd.rst +++ b/clang-tools-extra/docs/clangd.rst @@ -1,6 +1,3 @@ :orphan: - -.. meta:: - :http-equiv=refresh: 0;URL='clangd/' - -All :program:`clangd` documentation was moved to the :doc:`clangd/index` pages. +:template: clangd_redirect.html +:redirect_target: https://clangd.llvm.org/ diff --git a/clang-tools-extra/docs/clangd/ApplyClangTidyFixInVSCode.gif b/clang-tools-extra/docs/clangd/ApplyClangTidyFixInVSCode.gif deleted file mode 100644 index b07bdeb..0000000 Binary files a/clang-tools-extra/docs/clangd/ApplyClangTidyFixInVSCode.gif and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/ApplyFixInVSCode.gif b/clang-tools-extra/docs/clangd/ApplyFixInVSCode.gif deleted file mode 100644 index 929a98c..0000000 Binary files a/clang-tools-extra/docs/clangd/ApplyFixInVSCode.gif and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/CodeCompletionInEmacsCompanyMode.png b/clang-tools-extra/docs/clangd/CodeCompletionInEmacsCompanyMode.png deleted file mode 100644 index 1accc5a..0000000 Binary files a/clang-tools-extra/docs/clangd/CodeCompletionInEmacsCompanyMode.png and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/CodeCompletionInSublimeText.png b/clang-tools-extra/docs/clangd/CodeCompletionInSublimeText.png deleted file mode 100644 index b09fed3..0000000 Binary files a/clang-tools-extra/docs/clangd/CodeCompletionInSublimeText.png and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/CodeCompletionInVSCode.png b/clang-tools-extra/docs/clangd/CodeCompletionInVSCode.png deleted file mode 100644 index bc42e9d..0000000 Binary files a/clang-tools-extra/docs/clangd/CodeCompletionInVSCode.png and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/CodeCompletionInYCM.png b/clang-tools-extra/docs/clangd/CodeCompletionInYCM.png deleted file mode 100644 index b74508d..0000000 Binary files a/clang-tools-extra/docs/clangd/CodeCompletionInYCM.png and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/CodeCompletionInsertsNamespaceQualifiersInVSCode.gif b/clang-tools-extra/docs/clangd/CodeCompletionInsertsNamespaceQualifiersInVSCode.gif deleted file mode 100644 index f0d49d6..0000000 Binary files a/clang-tools-extra/docs/clangd/CodeCompletionInsertsNamespaceQualifiersInVSCode.gif and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/Configuration.rst b/clang-tools-extra/docs/clangd/Configuration.rst index ff5d38a..c7629dc 100644 --- a/clang-tools-extra/docs/clangd/Configuration.rst +++ b/clang-tools-extra/docs/clangd/Configuration.rst @@ -1,40 +1,3 @@ -============= -Configuration -============= - -.. 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 `__. - ---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`. +:orphan: +:template: clangd_redirect.html +:redirect_target: https://clangd.llvm.org/installation.html diff --git a/clang-tools-extra/docs/clangd/DeveloperDocumentation.rst b/clang-tools-extra/docs/clangd/DeveloperDocumentation.rst index 7584327..aacf367 100644 --- a/clang-tools-extra/docs/clangd/DeveloperDocumentation.rst +++ b/clang-tools-extra/docs/clangd/DeveloperDocumentation.rst @@ -1,29 +1,3 @@ -================================== -Developer documentation for clangd -================================== - -.. toctree:: - :maxdepth: 1 - - Extensions - -Compiling clangd -================ - -To build clangd from source, please follow the instructions for `building Clang -`_ 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 -`_. For discussions with -the broader community on topics not only related to Clangd, use `Clang -developer mailing list `_. If -you're also interested in contributing patches to clangd, take a look at the -`LLVM Developer Policy `_ and `Code -Reviews `_ page. Contributions of new -features to the `Language Server Protocol -`_ itself would also be -very useful, so that clangd can eventually implement them in a conforming way. +:orphan: +:template: clangd_redirect.html +:redirect_target: https://clangd.llvm.org/design.html diff --git a/clang-tools-extra/docs/clangd/DiagnosticsInEmacsEglot.png b/clang-tools-extra/docs/clangd/DiagnosticsInEmacsEglot.png deleted file mode 100644 index f5be84b..0000000 Binary files a/clang-tools-extra/docs/clangd/DiagnosticsInEmacsEglot.png and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/ErrorsInVSCode.png b/clang-tools-extra/docs/clangd/ErrorsInVSCode.png deleted file mode 100644 index 52de402..0000000 Binary files a/clang-tools-extra/docs/clangd/ErrorsInVSCode.png and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/Extensions.rst b/clang-tools-extra/docs/clangd/Extensions.rst index 6c972eb..53f874c 100644 --- a/clang-tools-extra/docs/clangd/Extensions.rst +++ b/clang-tools-extra/docs/clangd/Extensions.rst @@ -1,175 +1,3 @@ -=================== -Protocol extensions -=================== - -.. contents:: - -clangd supports some features that are not in the official -`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 +:orphan: +:template: clangd_redirect.html +:redirect_target: https://clangd.llvm.org/extensions.html diff --git a/clang-tools-extra/docs/clangd/Features.rst b/clang-tools-extra/docs/clangd/Features.rst index 12522cb..05b8efd 100644 --- a/clang-tools-extra/docs/clangd/Features.rst +++ b/clang-tools-extra/docs/clangd/Features.rst @@ -1,271 +1,4 @@ -======== -Features -======== +:orphan: +: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 -`__; 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:`

` - -.. image:: ErrorsInVSCode.png - :align: center - :alt: Demonstration of errors - -:raw-html:`

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

` - -.. image:: ApplyFixInVSCode.gif - :align: center - :alt: Applying a fix suggested by the compiler - -:raw-html:`

` - -**(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 `__ -which provides extra hints about code problems: bug-prone patterns, -performance traps, and style issues. - -:raw-html:`

` - -.. image:: ApplyClangTidyFixInVSCode.gif - :align: center - :alt: Applying a fix suggested by the compiler - -:raw-html:`

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

` - -.. image:: CodeCompletionInVSCode.png - :align: center - :alt: Code completion demonstration - -:raw-html:`

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

` - -.. image:: CodeCompletionInsertsNamespaceQualifiersInVSCode.gif - :align: center - :alt: Code completion inserts namespace qualifiers - -:raw-html:`

` - -Signature help --------------- - -Some editors will show you the parameters of the function you're calling, as -you fill them in. - -:raw-html:`

` - -.. image:: SignatureHelpInVSCode.gif - :align: center - :alt: Demonstration of the signature help feature - -:raw-html:`

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

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

` - -**(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:`

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

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

` - -.. image:: OutlineInVSCode.png - :align: center - :alt: Outline of a file - -:raw-html:`

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

` - -.. image:: NavigationWithBreadcrumbsInVSCode.gif - :align: center - :alt: Navigation with breadcrumbs - -:raw-html:`

` - -Formatting -========== - -clangd embeds `clang-format `__, -which can reformat your code: fixing indentation, breaking lines, and reflowing -comments. - -:raw-html:`

` - -.. image:: FormatSelectionInVSCode.gif - :align: center - :alt: Formatting selected code - -:raw-html:`

` - -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 diff --git a/clang-tools-extra/docs/clangd/FindAllReferencesInVSCode.gif b/clang-tools-extra/docs/clangd/FindAllReferencesInVSCode.gif deleted file mode 100644 index b9eecf3..0000000 Binary files a/clang-tools-extra/docs/clangd/FindAllReferencesInVSCode.gif and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/FormatSelectionInVSCode.gif b/clang-tools-extra/docs/clangd/FormatSelectionInVSCode.gif deleted file mode 100644 index 1d4be41..0000000 Binary files a/clang-tools-extra/docs/clangd/FormatSelectionInVSCode.gif and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/GoToDefinitionInVSCode.gif b/clang-tools-extra/docs/clangd/GoToDefinitionInVSCode.gif deleted file mode 100644 index 396966f..0000000 Binary files a/clang-tools-extra/docs/clangd/GoToDefinitionInVSCode.gif and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/Installation.rst b/clang-tools-extra/docs/clangd/Installation.rst index f12551d..c7629dc 100644 --- a/clang-tools-extra/docs/clangd/Installation.rst +++ b/clang-tools-extra/docs/clangd/Installation.rst @@ -1,379 +1,3 @@ -=========================== -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:`

` - -`Homebrew `__ 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 `__. -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:`

` - -:raw-html:`

` - -Download and run the LLVM installer from `releases.llvm.org -`__. - -:raw-html:`

` - -:raw-html:`

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

` - -:raw-html:`

` - -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 -`__. - -:raw-html:`

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

YouCompleteMe for Vim

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

` - -:raw-html:`

LanguageClient for Vim and Neovim

` - -`LanguageClient-neovim `__ -has `instructions for using clangd -`__, and **may** -be easier to install than YouCompleteMe. - -:raw-html:`

` - -:raw-html:`

Eglot for Emacs

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

` - -:raw-html:`

Visual Studio Code

` - -The official extension is `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:`

` - -:raw-html:`

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

` - -:raw-html:`

` - -There is a directory of LSP clients at `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 `__, it has excellent language server -support and most faithfully demonstrates what clangd can do. - -:raw-html:`

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

CMake-based projects

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

` - -:raw-html:`

Other build systems, using Bear

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

` - -Other tools can also generate this file. See `the compile_commands.json -specification `__. - -``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=` 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 `__ -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.* +:orphan: +:template: clangd_redirect.html +:redirect_target: https://clangd.llvm.org/installation.html diff --git a/clang-tools-extra/docs/clangd/NavigationWithBreadcrumbsInVSCode.gif b/clang-tools-extra/docs/clangd/NavigationWithBreadcrumbsInVSCode.gif deleted file mode 100644 index 499f5c1..0000000 Binary files a/clang-tools-extra/docs/clangd/NavigationWithBreadcrumbsInVSCode.gif and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/OutlineInVSCode.png b/clang-tools-extra/docs/clangd/OutlineInVSCode.png deleted file mode 100644 index 570a80d..0000000 Binary files a/clang-tools-extra/docs/clangd/OutlineInVSCode.png and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/SignatureHelpInVSCode.gif b/clang-tools-extra/docs/clangd/SignatureHelpInVSCode.gif deleted file mode 100644 index e5700f2..0000000 Binary files a/clang-tools-extra/docs/clangd/SignatureHelpInVSCode.gif and /dev/null differ diff --git a/clang-tools-extra/docs/clangd/index.rst b/clang-tools-extra/docs/clangd/index.rst index 1ae0976..70bab83 100644 --- a/clang-tools-extra/docs/clangd/index.rst +++ b/clang-tools-extra/docs/clangd/index.rst @@ -1,28 +1,3 @@ -====== -clangd -====== - -.. 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 -`__; 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 `__ C++ compiler, and is -part of the `LLVM `__ project. +:orphan: +:template: clangd_redirect.html +:redirect_target: https://clangd.llvm.org/ diff --git a/clang-tools-extra/docs/index.rst b/clang-tools-extra/docs/index.rst index 0fe9895..d5c00b8 100644 --- a/clang-tools-extra/docs/index.rst +++ b/clang-tools-extra/docs/index.rst @@ -20,8 +20,7 @@ Contents modularize pp-trace clang-rename - clangd/index - clangd/DeveloperDocumentation + clangd clang-doc