forked from golang/vscode-go
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
README: add troubleshooting section, some cleanup
Change-Id: I92cd750dcfb393bf7cd33257f02d8d57c369f534 Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/286472 Trust: Rebecca Stambler <[email protected]> Run-TryBot: Rebecca Stambler <[email protected]> Reviewed-by: Hyang-Ah Hana Kim <[email protected]>
- Loading branch information
1 parent
cc04c37
commit 1707d4b
Showing
1 changed file
with
49 additions
and
45 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,12 +8,6 @@ | |
| provides rich language support for the | ||
| [Go programming language](https://golang.org/). | ||
|
|
||
| > 📣 We will enable the language server ([`gopls`]) by default in the end of Jan | ||
| > 2021. We recommend switching to the language server now | ||
| > (`"go.useLanguageServer": true`) to confirm it works well for you. Please | ||
| > [file a new issue](https://github.com/golang/vscode-go/issues/new/choose) if | ||
| > you notice bugs or missing features. | ||
| ## Quick Start | ||
|
|
||
| Welcome! 👋🏻<br/> | ||
|
|
@@ -23,7 +17,7 @@ extension fits your needs and enhances your development experience. | |
| * **Step 1.** If you haven't done so already, install [Go](https://golang.org) | ||
| and the [VS Code Go extension]. | ||
| * [Go installation guide]. This extension works best with Go 1.14+. | ||
| * [Manage extensions in VS Code]. | ||
| * [Managing extensions in VS Code]. | ||
| * **Step 2.** To activate the extension, open any directory or workspace | ||
| containing Go code. Once activated, the [Go status bar](docs/ui.md) will | ||
| appear in the bottom left corner of the window and show the recognized Go | ||
|
|
@@ -40,23 +34,23 @@ extension fits your needs and enhances your development experience. | |
|
|
||
| You are ready to Go :-) 🎉🎉🎉 | ||
|
|
||
| Please be sure to learn more about many [features](#features) of this extension | ||
| as well as how to [customize](#customization) them. Take a look at | ||
| Please be sure to learn more about the many [features](#features) of this | ||
| extension, as well as how to [customize](#customization) them. Take a look at | ||
| [Troubleshooting](docs/troubleshooting.md) and [Help](#ask-for-help) for further | ||
| guidance. | ||
|
|
||
| If you are new to Go, [this article](https://golang.org/doc/code.html) provides | ||
| the overview on go code organization and basic `go` commands. The recent | ||
| [Go open source live video] featured VS Code Go and demonstrated how other | ||
| Gophers use the features to enhance their Go development workflow. | ||
| the overview on Go code organization and basic `go` commands. Watch [this video | ||
| from the Go Open Source Live conference] for an explanation of how to build | ||
| your first Go application using VS Code Go. | ||
|
|
||
| ## Features | ||
|
|
||
| This extension provides many features, including [IntelliSense], | ||
| [code navigation], [code editing] support. It also shows [diagnostics] as you | ||
| work and provides enhanced support for [testing] and [debugging] your programs. | ||
| See the [full feature breakdown] for more details and to learn how to tune the | ||
| behavior. | ||
| [code navigation], and [code editing] support. It also shows [diagnostics] as | ||
| you work and provides enhanced support for [testing] and [debugging] your | ||
| programs. See the [full feature breakdown] for more details and to learn how to | ||
| tune its behavior. | ||
|
|
||
| <p align=center> | ||
| <img src="docs/images/completion-signature-help.gif" width=75%> | ||
|
|
@@ -68,68 +62,75 @@ In addition to integrated editing features, the extension provides several | |
| commands for working with Go files. You can access any of these by opening the | ||
| Command Palette (`Ctrl+Shift+P` on Linux/Windows and `Cmd+Shift+P` on Mac), and | ||
| then typing in the command name. See the | ||
| [full list of commands](docs/commands.md#detailed-list) provided by the | ||
| [full list of commands](docs/commands.md#detailed-list) provided by this | ||
| extension. | ||
|
|
||
| <p align=center> | ||
| <img src="docs/images/toggletestfile.gif" width=75%> | ||
| <br/><em>(Toggle Test File)</em></p> | ||
|
|
||
| **⚠️ Note**: the default syntax highlighting for Go files is provided by the | ||
| **⚠️ Note**: the default syntax highlighting for Go files is provided by a | ||
| [TextMate rule](https://github.com/jeff-hykin/better-go-syntax) embedded in VS | ||
| Code, not by this extension. | ||
|
|
||
| ## Tools | ||
|
|
||
| The extension uses a few command-line tools developed by the Go community. In | ||
| particular, `go`, `gopls`, and `dlv` are used to implement build/test, language | ||
| features, and debugging functionalities of this extension. See the | ||
| [tools documentation](docs/tools.md) for a complete list of tools the extension | ||
| depends on. | ||
|
|
||
| In order to locate the command-line tools, the extension searches `$GOPATH/bin` | ||
| and directories specified in the `PATH` environment variable (or `Path` in | ||
| Windows) with which the VS Code process has started. If the tools are not found, | ||
| the extension will prompt you to install the missing tools and show the "⚠️ | ||
| Analysis Tools Missing" warning in the bottom right corner. Please install them | ||
| by responding to the warning notification, or by manually running the `Go: | ||
| Install/Update Go Tools` command. The extension will run the | ||
| [`go get`](https://golang.org/cmd/go) command to install them. | ||
| particular, `go`, `gopls`, and `dlv` **must** be installed for this extension | ||
| to work correctly. See the [tools documentation](docs/tools.md) for a complete | ||
| list of tools the extension depends on. | ||
|
|
||
| In order to locate these command-line tools, the extension searches | ||
| `GOPATH/bin` and directories specified in the `PATH` environment variable (or | ||
| `Path` on Windows) with which the VS Code process has started. If the tools are | ||
| not found, the extension will prompt you to install the missing tools and show | ||
| the "⚠️ Analysis Tools Missing" warning in the bottom right corner. Please | ||
| install them by responding to the warning notification, or by manually running | ||
| the [`Go: Install/Update Go Tools` command]. | ||
|
|
||
| ## Setting up your workspace | ||
|
|
||
| [Go modules](https://golang.org/ref/mod) are how Go manages dependencies in | ||
| recent versions of Go. Modules replace the `GOPATH`-based approach to specifying | ||
| which source files are used in a given build, and they are the default build | ||
| mode in go1.16+. While this extension continues to support both Go modules and | ||
| `GOPATH` mode, we highly recommend Go development in module mode. If you are | ||
| `GOPATH` modes, we highly recommend Go development in module mode. If you are | ||
| working on existing projects, please consider migrating to modules. | ||
|
|
||
| Unlike the traditional `GOPATH` mode, module mode does not require the workspace | ||
| to be located under `GOPATH` nor to use a specific structure. A module is | ||
| defined by a directory tree of Go source files with a `go.mod` file in the | ||
| tree's root directory. Your project may involve one or more modules. If you are | ||
| working with multiple modules or uncommon project layouts, you will need to | ||
| configure your workspace so that the extension knows which code to load, so that | ||
| features like references can work across modules. Please see the | ||
| for information on supported workspace layouts. | ||
| tree's root directory. | ||
|
|
||
| Your project may involve one or more modules. If you are working with multiple | ||
| modules or uncommon project layouts, you will need to configure your workspace | ||
| by using [Workspace Folders]. Please see this [documentation about supported | ||
| workspace layouts]. | ||
|
|
||
| ## Customization | ||
|
|
||
| The extension needs no configuration and should work out of the box. However, | ||
| you may wish to adjust settings to customize its behavior. Below are a few | ||
| commonly used settings. Please see the | ||
| you may wish to adjust settings to customize its behavior. Please see the | ||
| [settings documentation](docs/settings.md) for a comprehensive list of settings. | ||
| See [advanced topics](docs/advanced.md) for further customizations and unique | ||
| use cases. | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| If the extension isn't working as you expect, you can take a look at our | ||
| troubleshooting guides. There is one for [general | ||
| troubleshooting](docs/troubleshooting.md), and another specifically for | ||
| [troubleshooting the debugging feature](docs/debugging.md#troubleshooting). | ||
|
|
||
| ## Ask for help | ||
|
|
||
| If you're having issues with this extension, please reach out to us by | ||
| [filing an issue](https://github.com/golang/vscode-go/issues/new/choose) or | ||
| asking a question on the [Gophers Slack]. We hang out in the `#vscode` channel! | ||
| If the troubleshooting guides did not resolve the issue, please reach out to us | ||
| by [filing an issue](https://github.com/golang/vscode-go/issues/new/choose), | ||
| [starting a GitHub discussion](https://github.com/golang/vscode-go/discussions), | ||
| or by asking a question in the [Gophers Slack]. We hang out in the `#vscode` | ||
| channel! | ||
|
|
||
| Take a look at [learn.go.dev](https://learn.go.dev) and | ||
| Also, you can take a look at [learn.go.dev](https://learn.go.dev) and | ||
| [golang.org/help](https://golang.org/help) for more general guidance on using | ||
| Go. | ||
|
|
||
|
|
@@ -160,10 +161,10 @@ conduct-related issue, please mail [email protected]. | |
| [Gophers Slack]: https://gophers.slack.com/ | ||
| [`gopls`]: https://golang.org/s/gopls | ||
| [`go`]: https://golang.org/cmd/go | ||
| [Manage extensions in VS Code]: https://code.visualstudio.com/docs/editor/extension-gallery | ||
| [Managing extensions in VS Code]: https://code.visualstudio.com/docs/editor/extension-gallery | ||
| [VS Code Go extension]: https://marketplace.visualstudio.com/items?itemName=golang.go | ||
| [Go installation guide]: https://golang.org/doc/install | ||
| [Go open source live video]: https://opensourcelive.withgoogle.com/events/go/watch?talk=session3 | ||
| [this video from the Go Open Source Live conference]: https://opensourcelive.withgoogle.com/events/go/watch?talk=session3 | ||
| [IntelliSense]: docs/features.md#intellisense | ||
| [code navigation]: docs/features.md#code-navigation | ||
| [code editing]: docs/features.md#code-editing | ||
|
|
@@ -172,3 +173,6 @@ conduct-related issue, please mail [email protected]. | |
| [debugging]: #debugging | ||
| [full feature breakdown]: docs/features.md | ||
| [workspace documentation]: https://github.com/golang/tools/blob/master/gopls/doc/workspace.md | ||
| [`Go: Install/Update Go Tools` command]: docs/commands.md#go-installupdate-tools | ||
| [documentation about supported workspace layouts]: https://github.com/golang/tools/blob/master/gopls/doc/workspace.md | ||
| [Workspace Folders]: https://code.visualstudio.com/docs/editor/multi-root-workspaces | ||