Index: clang-tools-extra/trunk/docs/_static/clang-tools-extra-styles.css =================================================================== --- clang-tools-extra/trunk/docs/_static/clang-tools-extra-styles.css +++ clang-tools-extra/trunk/docs/_static/clang-tools-extra-styles.css @@ -0,0 +1,23 @@ +details { + background-color: rgba(50, 150, 220, 0.08); + margin-bottom: 0.5em; + padding: 0 1em; + overflow-y: hidden; /* Suppress margin-collapsing */ +} +details[open] { + border-bottom: 1px solid rgba(0, 0, 128, 0.2); + margin-bottom: 1em; +} +details summary { + font-weight: bold; + background-color: rgba(50, 150, 220, 0.1); + border-color: rgba(0, 0, 128, 0.2); + border-width: 1px; + border-style: solid none; + padding: 0.2em; + margin: 0 -1em; +} +details summary:hover { + background-color: rgba(50, 150, 220, 0.2); + cursor: pointer; +} Index: clang-tools-extra/trunk/docs/_templates/layout.html =================================================================== --- clang-tools-extra/trunk/docs/_templates/layout.html +++ clang-tools-extra/trunk/docs/_templates/layout.html @@ -0,0 +1,3 @@ +{% extends "!layout.html" %} + +{% set css_files = css_files + ['_static/clang-tools-extra-styles.css'] %} Index: clang-tools-extra/trunk/docs/clangd/DeveloperDocumentation.rst =================================================================== --- clang-tools-extra/trunk/docs/clangd/DeveloperDocumentation.rst +++ clang-tools-extra/trunk/docs/clangd/DeveloperDocumentation.rst @@ -0,0 +1,29 @@ +================================== +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. Index: clang-tools-extra/trunk/docs/clangd/Extensions.rst =================================================================== --- clang-tools-extra/trunk/docs/clangd/Extensions.rst +++ clang-tools-extra/trunk/docs/clangd/Extensions.rst @@ -0,0 +1,173 @@ +=================== +Protocol extensions +=================== + +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 Index: clang-tools-extra/trunk/docs/clangd/Features.rst =================================================================== --- clang-tools-extra/trunk/docs/clangd/Features.rst +++ clang-tools-extra/trunk/docs/clangd/Features.rst @@ -0,0 +1,231 @@ +======== +Features +======== + +.. 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:`
Screenshot` + +.. 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:`
Animated demo` + +.. image:: ApplyFixInVSCode.gif + :align: center + :alt: Applying a fix suggested by the compiler + +:raw-html:`
` + +Code completion +=============== + +You'll see suggestions as you type based on what methods, variables, etc are +available in this context. + +:raw-html:`
Screenshot` + +.. 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:`
Animated demo` + +.. 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:`
Animated demo` + +.. 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. + +Find definition/declaration +--------------------------- + +Jump to the definition or declaration of a symbol under the cursor. + +:raw-html:`
Animated demo` + +.. image:: GoToDefinitionInVSCode.gif + :align: center + :alt: Demonstration of the "Go to definition" feature + +:raw-html:`
` + +Find references +--------------- + +Show all references to a symbol under the cursor. + +:raw-html:`
Animated demo` + +.. 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:`
Screenshot` + +.. 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:`
Animated demo` + +.. 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:`
Animated demo` + +.. 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 | No | No | ++-------------------------------------+------------+----------+ +| Call hierarchy | No | No | ++-------------------------------------+------------+----------+ +| Type hierarchy | No | No | ++-------------------------------------+------------+----------+ +| Organize Includes | No | No | ++-------------------------------------+------------+----------+ Index: clang-tools-extra/trunk/docs/clangd/Installation.rst =================================================================== --- clang-tools-extra/trunk/docs/clangd/Installation.rst +++ clang-tools-extra/trunk/docs/clangd/Installation.rst @@ -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:`
macOS` + +`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:`
Windows` + +Download and run the LLVM installer from `releases.llvm.org +`__. + +:raw-html:`
` + +:raw-html:`
Debian/Ubuntu` + +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:`
Other systems` + +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 +`__. + +: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:`
Sublime Text` + +`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:`
Other editors` + +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/compile_commands.json ~/myproject-build/ + +: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. + +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 + `__ + 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.* Index: clang-tools-extra/trunk/docs/clangd/index.rst =================================================================== --- clang-tools-extra/trunk/docs/clangd/index.rst +++ clang-tools-extra/trunk/docs/clangd/index.rst @@ -1,180 +1,27 @@ -============ -Clangd -============ - -.. contents:: +====== +clangd +====== .. toctree:: :maxdepth: 1 -:program:`Clangd` is an implementation of the `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 `_ 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 `_. :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 -`_ 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 -`_ 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 -`_ plugin. Please see the -`Clangd Wiki page -`_ for -instructions. - -VSCode Integration ------------------- - -:program:`VSCode` provides `vscode-clangd -`_ -which is published in Visual Studio Marketplace and can be installed direcetly -from :program:`VSCode`. - -Emacs Integration ------------------ - -:program:`Emacs` provides `lsp-mode `_ and -`Eglot `_ plugins for LSP integration. - -Project-wide Index -================== - -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`. - -There are two ways you can generate a project-wide index for clangd: - -- 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 - `_ - 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* - -Getting Involved -================== - -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 :program:`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 :program:`Clangd` can eventually implement them in a -conforming way. + Installation + Features + +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. Index: clang-tools-extra/trunk/docs/conf.py =================================================================== --- clang-tools-extra/trunk/docs/conf.py +++ clang-tools-extra/trunk/docs/conf.py @@ -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. Index: clang-tools-extra/trunk/docs/index.rst =================================================================== --- clang-tools-extra/trunk/docs/index.rst +++ clang-tools-extra/trunk/docs/index.rst @@ -21,6 +21,7 @@ pp-trace clang-rename clangd/index + clangd/DeveloperDocumentation clang-doc