[clang-tools-extra] r371390 - [clangd] Update clangd-vscode docs to be more user-focused.
Sam McCall via cfe-commits
cfe-commits at lists.llvm.org
Mon Sep 9 04:34:02 PDT 2019
Author: sammccall
Date: Mon Sep 9 04:34:01 2019
New Revision: 371390
URL: http://llvm.org/viewvc/llvm-project?rev=371390&view=rev
Log:
[clangd] Update clangd-vscode docs to be more user-focused.
Summary: Relegate "updating the extension" docs to a separate file.
Reviewers: hokein, kadircet
Subscribers: ilya-biryukov, MaskRay, jkorous, arphaman, cfe-commits
Tags: #clang
Differential Revision: https://reviews.llvm.org/D67092
Added:
clang-tools-extra/trunk/clangd/clients/clangd-vscode/DEVELOPING.md
clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/
clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/complete.png (with props)
clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/diagnostics.png (with props)
clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/extract.png (with props)
clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/format.png (with props)
clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/include.png (with props)
clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/symbolsearch.png (with props)
clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/xrefs.png (with props)
Modified:
clang-tools-extra/trunk/clangd/clients/clangd-vscode/README.md
Added: clang-tools-extra/trunk/clangd/clients/clangd-vscode/DEVELOPING.md
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/clangd/clients/clangd-vscode/DEVELOPING.md?rev=371390&view=auto
==============================================================================
--- clang-tools-extra/trunk/clangd/clients/clangd-vscode/DEVELOPING.md (added)
+++ clang-tools-extra/trunk/clangd/clients/clangd-vscode/DEVELOPING.md Mon Sep 9 04:34:01 2019
@@ -0,0 +1,53 @@
+# Development
+
+A guide of developing `vscode-clangd` extension.
+
+## Requirements
+
+* VS Code
+* node.js and npm
+
+## Steps
+
+1. Make sure you disable the installed `vscode-clangd` extension in VS Code.
+2. Make sure you have clangd in /usr/bin/clangd or edit src/extension.ts to
+point to the binary.
+3. In order to start a development instance of VS code extended with this, run:
+
+```bash
+ $ cd /path/to/clang-tools-extra/clangd/clients/clangd-vscode/
+ $ npm install
+ $ code .
+ # When VS Code starts, press <F5>.
+```
+
+# Contributing
+
+Please follow the exsiting code style when contributing to the extension, we
+recommend to run `npm run format` before sending a patch.
+
+# Publish to VS Code Marketplace
+
+New changes to `clangd-vscode` are not released until a new version is published
+to the marketplace.
+
+## Requirements
+
+* Make sure install the `vsce` command (`npm install -g vsce`)
+* `llvm-vs-code-extensions` account
+* Bump the version in `package.json`, and commit the change to upstream
+
+The extension is published under `llvm-vs-code-extensions` account, which is
+currently maintained by clangd developers. If you want to make a new release,
+please contact clangd-dev at lists.llvm.org.
+
+## Steps
+
+```bash
+ $ cd /path/to/clang-tools-extra/clangd/clients/clangd-vscode/
+ # For the first time, you need to login in the account. vsce will ask you for
+ the Personal Access Token, and remember it for future commands.
+ $ vsce login llvm-vs-code-extensions
+ $ vsce publish
+```
+
Modified: clang-tools-extra/trunk/clangd/clients/clangd-vscode/README.md
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/clangd/clients/clangd-vscode/README.md?rev=371390&r1=371389&r2=371390&view=diff
==============================================================================
--- clang-tools-extra/trunk/clangd/clients/clangd-vscode/README.md (original)
+++ clang-tools-extra/trunk/clangd/clients/clangd-vscode/README.md Mon Sep 9 04:34:01 2019
@@ -1,81 +1,103 @@
# vscode-clangd
-Provides C/C++ language IDE features for VS Code using [clangd](https://clang.llvm.org/extra/clangd.html).
+Provides C/C++ language IDE features for VS Code using [clangd](https://clang.llvm.org/extra/clangd.html):
-## Usage
+ - code completion
+ - compile errors and warnings
+ - go-to-definition and cross references
+ - include management
+ - code formatting
+ - simple refactorings
-`vscode-clangd` provides the features designated by the [Language Server
-Protocol](https://github.com/Microsoft/language-server-protocol), such as
-code completion, code formatting and goto definition.
+## Setup
-**Note**: `clangd` is under heavy development, not all LSP features are
-implemented. See [Current Status](https://clang.llvm.org/extra/clangd/Features.html#complete-list-of-features)
-for details.
+### `clangd` server
-To use `vscode-clangd` extension in VS Code, you need to install `vscode-clangd`
-from VS Code extension marketplace.
+`clangd` is a language server that must be installed separately, see
+[https://clangd.github.io/installation.html](getting started).
+The vscode-clangd plugin will look for `clangd` on your PATH (you can change
+this in the settings).
-`vscode-clangd` will attempt to find the `clangd` binary on your `PATH`.
-Alternatively, the `clangd` executable can be specified in your VS Code
-`settings.json` file:
+### Project setup
-```json
-{
- "clangd.path": "/absolute/path/to/clangd"
-}
-```
+clangd is based on the clang C++ compiler, and understands even complex C++
+code. However, you must tell clangd how your project is built (compile flags).
+[A `compile_commands.json` file](http://clang.llvm.org/docs/JSONCompilationDatabase.html)
+can usually be generated by your build system
+(e.g. by setting `-DCMAKE_EXPORT_COMPILE_COMMANDS=1` when building with CMake,
+or with
+[many other tools](https://sarcasm.github.io/notes/dev/compilation-database.html)).
-To obtain `clangd` binary, please see the [installing Clangd](https://clang.llvm.org/extra/clangd/Installation.html#installing-clangd).
+It should live at the top of your source tree: symlink or copy it there.
-## Development
+## Features
-A guide of developing `vscode-clangd` extension.
+### Code completion
-### Requirements
+Suggestions will appear as you type names, or after `.` or `->`.
+Because clangd uses a full C++ parser, code completion has access to precise
+type information.
-* VS Code
-* node.js and npm
+
-### Steps
+### Errors, warnings, and clang-tidy
-1. Make sure you disable the installed `vscode-clangd` extension in VS Code.
-2. Make sure you have clangd in /usr/bin/clangd or edit src/extension.ts to
-point to the binary.
-3. In order to start a development instance of VS code extended with this, run:
+Code errors are shown as you type (both as red squiggle underlines, and in the
+"Problems" panel). These are the same as produced by the clang compiler, and
+suggested fixes can automatically be applied.
-```bash
- $ cd /path/to/clang-tools-extra/clangd/clients/clangd-vscode/
- $ npm install
- $ code .
- # When VS Code starts, press <F5>.
-```
+
-## Contributing
+Most clang-tidy checks are supported (these can be enabled using a [.clang-tidy
+file](https://clang.llvm.org/extra/clang-tidy/)).
-Please follow the exsiting code style when contributing to the extension, we
-recommend to run `npm run format` before sending a patch.
+### Cross-references
-## Publish to VS Code Marketplace
+Go-to-definition and find-references work across your code, using a project-wide
+index.
-New changes to `clangd-vscode` are not released until a new version is published
-to the marketplace.
+
-### Requirements
+Press `Ctrl-P #` to quickly navigate to a symbol by name.
-* Make sure install the `vsce` command (`npm install -g vsce`)
-* `llvm-vs-code-extensions` account
-* Bump the version in `package.json`, and commit the change to upstream
+### Include management
-The extension is published under `llvm-vs-code-extensions` account, which is
-currently maintained by clangd developers. If you want to make a new release,
-please contact clangd-dev at lists.llvm.org.
+Code completion works across your codebase and adds `#include` directives where
+needed. The `•` shows includes that will be inserted.
-### Steps
+clangd can also suggest inserting missing #includes, where they cause errors.
-```bash
- $ cd /path/to/clang-tools-extra/clangd/clients/clangd-vscode/
- # For the first time, you need to login in the account. vsce will ask you for
- the Personal Access Token, and remember it for future commands.
- $ vsce login llvm-vs-code-extensions
- $ vsce publish
-```
+
+
+### Formatting
+
+clangd uses the `clang-format` engine. You can format a file or the selection.
+When "Format on Type" is enabled in the settings, pressing enter will cause
+clangd to format the old line and semantically reindent.
+
+
+
+The style used for formatting (and certain other operations) is controlled by
+the .clang-format file is controlled by the project's
+[.clang-format file](https://clang.llvm.org/docs/ClangFormatStyleOptions.html).
+
+### Refactoring
+
+clangd supports some local refactorings. When you select an expression or
+declaration, the lightbulb menu appears and you can choose a code action.
+
+
+
+Current refactorings include:
+ - extract variable/function
+ - expand `auto` types and macros
+ - use raw strings
+ - rename (bound to `<F2>`, rather than a contextual code action)
+
+## Bugs/contributing
+
+clangd and vscode-clangd are part of the [LLVM project](https://llvm.org).
+
+If you'd like to help out, reach out to clangd-dev at lists.llvm.org.
+
+If you've found a bug, please file at https://github.com/clangd/clangd/issues.
Added: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/complete.png
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/complete.png?rev=371390&view=auto
==============================================================================
Binary file - no diff available.
Propchange: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/complete.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/diagnostics.png
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/diagnostics.png?rev=371390&view=auto
==============================================================================
Binary file - no diff available.
Propchange: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/diagnostics.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/extract.png
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/extract.png?rev=371390&view=auto
==============================================================================
Binary file - no diff available.
Propchange: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/extract.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/format.png
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/format.png?rev=371390&view=auto
==============================================================================
Binary file - no diff available.
Propchange: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/format.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/include.png
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/include.png?rev=371390&view=auto
==============================================================================
Binary file - no diff available.
Propchange: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/include.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/symbolsearch.png
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/symbolsearch.png?rev=371390&view=auto
==============================================================================
Binary file - no diff available.
Propchange: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/symbolsearch.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/xrefs.png
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/xrefs.png?rev=371390&view=auto
==============================================================================
Binary file - no diff available.
Propchange: clang-tools-extra/trunk/clangd/clients/clangd-vscode/doc-assets/xrefs.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
More information about the cfe-commits
mailing list