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-...@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-...@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-...@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 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
