[release] docs: proofread docs, fixing broken links and typos
Also, remove all TODOs as I have filed them all as issues.
Some of the settings and commands links may be broken, but they should
work fine after CL 236963.
Change-Id: I6363dd649be1bddbef54ff948e24072fe773e4ca
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236978
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
(cherry picked from commit 05e1f73483eadb6749f3f1f70f9d71dc8f4d1b4c)
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/237158
diff --git a/README.md b/README.md
index ec5887b..4faea7f 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
Take a look at the [Changelog](CHANGELOG.md) to learn about new features.
-> This is the future home for the VS Code Go extension. We are currently migrating from the [original repository](https://github.com/Microsoft/vscode-go). Read [the announcement](https://github.com/microsoft/vscode-go/blob/master/README.md#we-are-moving---) to learn about the transition and subscribe to [Microsoft/vscode-go#3247](https://github.com/microsoft/vscode-go/issues/3247) for updates.
+> This is the **new** home for the VS Code Go extension. We just migrated from [Microsoft/vscode-go](https://github.com/Microsoft/vscode-go). Learn more our move on the [Go blog](https://golang.blog/the-vs-code-go-extension-joins-the-go-project).
## Overview
@@ -31,7 +31,9 @@
### Install Go
-Before you start coding, make sure that you have already installed Go, as explained on the [Go installation guide](https://golang.org/doc/install). If you are unsure, open the Command Palette in VS Code (Ctrl+Shift+P) and run the `Go: Locate Configured Go Tools` command. If the `GOROOT` output is empty, you are missing a Go installation. For help installing Go, ask a question on the `#newbies` [Gophers Slack] channel.
+Before you start coding, make sure that you have already installed Go, as explained in the [Go installation guide](https://golang.org/doc/install).
+
+If you are unsure whether you have installed Go, open the Command Palette in VS Code (Ctrl+Shift+P) and run the [`Go: Locate Configured Go Tools`](docs/commands.md#go-locate-configured-go-tools) command. If the `GOROOT` output is empty, you are missing a Go installation. For help installing Go, ask a question on the `#newbies` [Gophers Slack] channel.
### Set up your environment
@@ -45,17 +47,17 @@
**NOTE: If you are using modules, we recommend using the Go [language server](#language-server), which is explained below.**
-More advanced users may be interested in using different `GOPATH`s or Go versions per-project. You can learn about the different `GOPATH` manipulation options in the [`GOPATH` documentation](gopath.md). Take a look at the other [customization](#customization) options as well.
+More advanced users may be interested in using different `GOPATH`s or Go versions per-project. You can learn about the different `GOPATH` manipulation options in the [`GOPATH` documentation](docs/gopath.md). Take a look at the other [customization](#customization) options as well.
### Install the extension
-If you haven't already done so, install and open [Visual Studio Code](https://code.visualstudio.com). Navigate to the Extensions pane (Ctrl+Shift+X). Search for "Go" and install this extension (the publisher ID is "golang.Go").
+If you haven't already done so, install and open [Visual Studio Code](https://code.visualstudio.com). Navigate to the Extensions pane (Ctrl+Shift+X). Search for "Go" and install this extension (the publisher ID is `golang.Go`).
### Activate the Go extension
To activate the extension, open any directory or workspace containing Go code.
-You should immediately see a prompt in the bottom-right corner of your screen titled `Analysis Tools Missing`. This extension relies on a suite of [command-line tools](docs/tools.md), which must be installed separately from the extension. Accept the prompt, or use the `Go: Install/Update Tools` command to pick which tools you would like to install. Note that you must have [`git`](https://git-scm.com/) installed.
+You should immediately see a prompt in the bottom-right corner of your screen titled `Analysis Tools Missing`. This extension relies on a suite of [command-line tools](docs/tools.md), which must be installed separately. Accept the prompt, or use the [`Go: Install/Update Tools`](docs/commands.md#go-installupdate-tools) command to pick which tools you would like to install.
If you see an error that looks like `command Go: Install/Update Tools not found`, it means that the extension has failed to activate and register its commands. Please uninstall and then reinstall the extension.
@@ -63,39 +65,37 @@
You're ready to Go!
-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 [Resources](#resources) for further guidance.
+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.
## Support for Go modules
-[Go modules](https://blog.golang.org/using-go-modules) have added a lot of complexity to the way most tools and features are built for Go. This has also added a lot of latency to most of the features. Some, but not all, [features](features.md) of this extension have been updated to work with Go modules. Some features may be slower in module mode. The [features documentation](features.md) contains more specific details.
+[Go modules](https://blog.golang.org/using-go-modules) have added a lot of complexity to the way that most tools and features are built for Go. Some, but not all, [features](docs/features.md) of this extension have been updated to work with Go modules. Some features may also be slower in module mode. The [features documentation](docs/features.md) contains more specific details.
-**In general, we recommend using [gopls, the official Go language server](#language-server), if you are using modules.** Read more [below](#language-server) and in the [gopls](gopls.md) documentation.
+**In general, we recommend using [`gopls`, the official Go language server](https://golang.org/s/gopls), if you are using modules.** Read more [below](#language-server) and in the [`gopls` documentation](docs/gopls.md).
## [Features](docs/features.md)
-This extension has a wide range of features, including [Intellisense](docs/features.md#intellisense), [code navigation](docs/features.md#code-navigation), and [code editing](docs/features.md#code-editing) support, as well as build, vet, and lint [diagnostics](docs/features.md#diagnostics) as you work. The VS Code Go extension also provides enhanced support for [testing](docs/features.md#testing) and [debugging](#debugging) your programs. For more detail, see the [full feature breakdown](docs/features.md).
+This extension has a wide range of features, including [Intellisense](docs/features.md#intellisense), [code navigation](docs/features.md#code-navigation), and [code editing](docs/features.md#code-editing) support. It also shows build, vet, and lint [diagnostics](docs/features.md#diagnostics) as you work and provides enhanced support for [testing](docs/features.md##run-and-test-in-the-editor) and [debugging](#debugging) your programs. For more detail, see the [full feature breakdown](docs/features.md).
-In addition to integrated editing features, the extension also provides several commands for working with Go files. You can access any of these by opening the Command Palette (Ctrl+Shift+P) and typing in the name of the command. See the [full list of commands](docs/commands.md) provided by the extension.
+In addition to integrated editing features, the extension also provides several commands for working with Go files. You can access any of these by opening the Command Palette (Ctrl+Shift+P) and typing in the name of the command. See the [full list of commands](docs/commands.md#detailed-list) provided by the extension.
-The majority of the extension's features are provided by command-line tools written in Go. If you're having an issue with a specific feature, you may want to investigate the underlying tool. You can do this by taking a look at the [full list of the tools this extension depends on](docs/tools.md).
+The majority of the extension's functionality comes from command-line tools. If you're experiencing an issue with a specific feature, you may want to investigate the underlying tool. You can do this by taking a look at the [full list of tools used by this extension](docs/tools.md).
### [Debugging](docs/debugging.md)
-Debugging is a major feature offered by this extension. For information on how to debug your Go program, please see the [Debugging Guide](docs/debugging.md). It includes information about debugging on Windows Subsystem for Linux (WSL) and remote debugging.
+Debugging is a major feature offered by this extension. For a comprehensive overview of how to debug your Go programs, please see the [debugging guide](docs/debugging.md).
## Customization
-This extension needs no configuration; it works out of the box. However, you may wish to modify your experience.
+This extension needs no configuration; it works out of the box. However, you may wish to modify settings to adjust your experience.
-Many of the features are configurable to your preference. The list of settings can be found in [Settings and Commands documentation](docs/commands.md).
+Many of the features are configurable to your preference. A few common modifications are mentioned below, but take a look at the [full list of settings](docs/settings.md) for an overview.
-### [Linter](tools.md#diagnostics)
+### [Linter](docs/tools.md#diagnostics)
A commonly customized feature is the linter, which is a tool used to provide coding style feedback and suggestions. By default, this extension uses the official [`golint`].
-<!--TODO(rstambler): Deprecate the golint setting.-->
-
-However, you are welcome to use more advanced options like [`staticcheck`](https://pkg.go.dev/honnef.co/go/tools/staticcheck?tab=overview), [`golangci-lint`](https://golangci-lint.run/), or [`revive`](https://golangci-lint.run/). This can be configured via the [`"go.lintTool"`](docs/commands.md#lintTool) setting, and the different options are explained more thoroughly in the [list of diagnostic tools](docs/tools.md#diagnostics).
+However, you are welcome to use more advanced options like [`staticcheck`](https://pkg.go.dev/honnef.co/go/tools/staticcheck?tab=overview), [`golangci-lint`](https://golangci-lint.run/), or [`revive`](https://pkg.go.dev/github.com/mgechev/revive?tab=overview). This can be configured via the [`"go.lintTool"`](docs/settings.md#go.lintTool) setting, and the different options are explained more thoroughly in the [list of diagnostic tools](docs/tools.md#diagnostics).
### [GOPATH](docs/gopath.md)
@@ -103,13 +103,13 @@
## [Language Server](docs/gopls.md)
-The Go extension uses a suite of [command-line tools](docs/tools.md) to provide language features. A new alternative is to use a [single language server](https://langserver.org/), which provides the same features using the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/).
+In the default mode, the Go extension relies upon a suite of [command-line tools](docs/tools.md). A new alternative is to use a [single language server](https://langserver.org/), which provides language features through the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/).
The Go team at Google has developed [`gopls`](docs/gopls.md), which is the official Go language server. It is currently in an alpha state and under active development.
-[`gopls`] is recommended for projects that use Go modules, as it provides much better support.
+[`gopls`] is recommended for projects that use Go modules.
-To opt-in to the language server, set [`"go.useLanguageServer"`](docs/commands.md#useLanguageServer) to `true` in your settings. You should then be prompted to install [`gopls`]. If you are not prompted, you can install `gopls` manually by running the `Go: Install/Update Tools` command and selecting `gopls`.
+To opt-in to the language server, set [`"go.useLanguageServer"`](docs/settings.md#go.useLanguageServer) to `true` in your settings. You should then be prompted to install [`gopls`]. If you are not prompted, you can install `gopls` manually by running the [`Go: Install/Update Tools`](docs/commands.md#go-installupdate-tools) command and selecting `gopls`.
For more information, see the [`gopls` documentation](docs/gopls.md).
@@ -119,13 +119,13 @@
Take a look at [learn.go.dev](https://learn.go.dev) and [golang.org/help](https://golang.org/help) for additional guidance.
-## [Preview version](nightly.md)
+## [Preview version](docs/nightly.md)
-If you'd like to get early access to new features and bug fixes, you can use the nightly build of this extension. Learn how to install it in by reading the [Go Nightly documentation](nightly.md).
+If you'd like to get early access to new features and bug fixes, you can use the nightly build of this extension. Learn how to install it in by reading the [Go Nightly documentation](docs/nightly.md).
## [Contributing](docs/contributing.md)
-We welcome your contributions and thank you for working to improve the Go development experience in VS Code. If you would like to help work on the VS Code Go extension, please see our [Contribution guide](docs/contributing.md). It explains how to build and run the extension locally, as well as the process of sending a contribution.
+We welcome your contributions and thank you for working to improve the Go development experience in VS Code. If you would like to help work on the VS Code Go extension, please see our [contribution cuide](docs/contributing.md). It explains how to build and run the extension locally, and it describes the process of sending a contribution.
## [Code of Conduct](CODE_OF_CONDUCT.md)
diff --git a/docs/commands.md b/docs/commands.md
index c778e0b..932ac5c 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -1,10 +1,10 @@
# Commands
-In addition to the integrated editing features, this extension offers a number of commands, which can be executed manually through the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) (Ctrl+Shift+P).
+In addition to integrated editing features, this extension offers a number of commands, which can be executed manually through the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) (Ctrl+Shift+P).
-Some of these commands are also available in the VS Code context menu (right click). To control which of these commands show up in the editor context menu, update the [`"go.editorContextMenuCommands"`](settings.md#editorContextMenuCommands) setting.
+Some of these commands are also available in the VS Code context menu (right-click). To control which of these commands show up in the editor context menu, update the [`"go.editorContextMenuCommands"`](settings.md#go.editorContextMenuCommands) setting.
-All commands provided by this extension have the prefix "`Go:` ".
+All commands provided by this extension have the prefix `Go:`.
## Latest changes
diff --git a/docs/contributing.md b/docs/contributing.md
index 1e93e7a..f318b81 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -12,18 +12,17 @@
* [Run](#run)
* [Test](#test)
* [Sideload](#sideload)
-
* [Mail your change for review](#mail-your-change-for-review)
## Before you start coding
If you are interested in fixing a bug or contributing a feature, please [file an issue](https://github.com/golang/vscode-go/issues/new/choose) first. Wait for a project maintainer to respond before you spend time coding.
-If you wish to work on an existing issue, please add a comment saying so, as someone may already be working on it. A project maintainer may respond with advice on how to get started. If you're not sure which issues are available, search from issues with the [help wanted label](https://github.com/golang/vscode-go/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
+If you wish to work on an existing issue, please add a comment saying so, as someone may already be working on it. A project maintainer may respond with advice on how to get started. If you're not sure which issues are available, search for issues with the [help wanted label](https://github.com/golang/vscode-go/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
### Ask for help
-The VS Code Go maintainers are reachable via the issue tracker and the [#vscode-dev] channel on the [Gophers Slack]. Please reach out on Slack with questions, suggestions, or ideas. If you have trouble getting started on an issue, we'd be happy to give pointers and advice.
+The VS Code Go maintainers are reachable via the issue tracker and the [#vscode-dev] channel in the [Gophers Slack]. Please reach out on Slack with questions, suggestions, or ideas. If you have trouble getting started on an issue, we'd be happy to give pointers and advice.
### Debug Adapter
@@ -44,7 +43,6 @@
```
3) Make sure the `window.openFoldersInNewWindow` setting is not `"on"`.
-<!--TODO(rstambler): Confirm that this is still required.-->
### Run
@@ -52,13 +50,13 @@
This will open a new VS Code window with the title `[Extension Development Host]`. You can then open a folder that contains Go code and try out your changes.
-You can also set breakpoints, which will work as you run the extension.
+You can also set breakpoints to debug your change.
-If you make further edits in the codebase, you can reload (`Ctrl+R`) the `[Extension Development Host]` instance of VS Code, which will load the new code. The debugging instance will automatically reattach.
+If you make subsequent edits in the codebase, you can reload (`Ctrl+R`) the `[Extension Development Host]` instance of VS Code, which will load the new code. The debugger will automatically reattach.
## Test
-There are currently three test launch configurations: (1) Launch Extension Tests, (2) Launch Extension Tests with Gopls, and (3) Launch Unit Tests. To run the tests locally, open the Run view (`Ctrl+Shift+D`), select the relevant launch configuration, and hit the Play button (`F5`).
+There are currently three test launch configurations: (1) `Launch Extension Tests`, (2) `Launch Extension Tests with Gopls`, and (3) `Launch Unit Tests`. To run the tests locally, open the Run view (`Ctrl+Shift+D`), select the relevant launch configuration, and hit the Play button (`F5`).
## Sideload
@@ -67,7 +65,7 @@
1. Install the [vsce](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#vsce) tool for packaging extensions (`npm install -g vsce`).
2. `cd` into your `vscode-go` directory.
3. Install all dependencies by running `npm install`.
-4. Run `vsce package` to build the package. This will generate a file with a `.vsix` extension in your current directory.
+4. Run `vsce package`. This will generate a file with a `.vsix` extension in your current directory.
```bash
npm install -g vsce
@@ -78,27 +76,27 @@
5. Open a VS Code window, navigate to the Extensions view, and disable or uninstall the default Go extension.
6. Click on the "..." in the top-right corner, select "Install
-from VSIX...", and choose the generated VSIX file. Alternatively, you can run `code --install-extension path/to/go.vsix` or open the Command Palette and run the "Extensions: Install from VSIX..." command.
+from VSIX...", and choose the generated VSIX file. Alternatively, you can run `code --install-extension path/to/go.vsix` or open the Command Palette and run the `Extensions: Install from VSIX...` command.
## Mail your change for review
-Once you have coded, built, and tested your change, it's ready for review! There are two ways to contribute your change: (1) [a GitHub pull request (PR)](https://golang.org/doc/contribute.html#sending_a_change_github), or (2) a [Gerrit code review](https://golang.org/doc/contribute.html#sending_a_change_gerrit).
-
-<!--TODO(rstambler): The content on https://golang.org/doc/contribute.html needs to be generalized to all x/ repos.-->
+Once you have coded, built, and tested your change, it's ready for review! There are two ways to mail your change: (1) through [a GitHub pull request (PR)](https://golang.org/doc/contribute.html#sending_a_change_github), or (2) through a [Gerrit code review](https://golang.org/doc/contribute.html#sending_a_change_gerrit).
In either case, code review will happen in [Gerrit](https://www.gerritcodereview.com/), which is used for all repositories in the Go project. GitHub pull requests will be mirrored into Gerrit, so you can follow a more traditional GitHub workflow, but you will still have to look at Gerrit to read comments.
The easiest way to start is by reading this [detailed guide for contributing to the Go project](https://golang.org/doc/contribute.html). Important things to note are:
* You will need to sign the [Google CLA](https://golang.org/doc/contribute.html#cla).
-* Your commit message should follow the standards described on the [Commit Message Wiki page](https://github.com/golang/go/wiki/CommitMessage).<!--TODO(rstambler): What should the prefix be for vscode-go CLs? I feel like we still haven't figured this out.-->
+* Your commit message should follow the standards described on the [Commit Message Wiki](https://github.com/golang/go/wiki/CommitMessage).
* Your change should include tests (if possible).
-Once you've sent out your change, a maintainer will take a look at your contribution within a few weeks. If you don't hear back in that time, feel free to ping the issue or send a message to the [#vscode-dev] channel of the [Gophers Slack].
+Once you've sent out your change, a maintainer will take a look at your contribution within a few weeks. If you don't hear back, feel free to ping the issue or send a message to the [#vscode-dev] channel of the [Gophers Slack].
## [Continuous Integration](testing.md)
-The extension's test suite will run on your change once it has been mailed. If you have contributed via a GitHub pull request (PR), the test results will be provided via a [GitHub Action](testing.md#testing-via-github-actions) result on the PR. If you have mailed a Gerrit changelist (CL) directly, tests will run in [Google Cloud Build](testing.md#testing-via-gcb), and the results will be posted back on the CL. As of June 2020, the GCB and Gerrit integration is not yet ready, so the results of the CI run **will not** appear on the Gerrit changelist. Instead, if your change fails on GCB, your reviewer will notify you and provide you with the relevant logs.
+The extension's test suite will run on your change once it has been mailed. If you have contributed via a GitHub PR, the test results will be provided via a [GitHub Action](testing.md#testing-via-github-actions) result on the PR. If you have mailed a Gerrit CL directly, tests will run in [Google Cloud Build](testing.md#testing-via-gcb), and the results will be posted back on the CL.
+
+Note that, as of June 2020, the GCB and Gerrit integration is not yet ready, so the results of the CI run **will not** appear on the Gerrit changelist. Instead, if your change fails on GCB, we will notify you and provide you with the relevant logs.
[#vscode-dev]: https://gophers.slack.com/archives/CUWGEKH5Z
[Gophers Slack]: https://invite.slack.golangbridge.org/
diff --git a/docs/debug-adapter.md b/docs/debug-adapter.md
index 26cd49c..ef492db 100644
--- a/docs/debug-adapter.md
+++ b/docs/debug-adapter.md
@@ -4,7 +4,7 @@
Please see the [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/) to understand how the Debug Adapter acts as an intermediary between VS Code and the debugger ([Delve](https://github.com/go-delve/delve)).
-This codebase is currently in flux: We are working on using's [`Delve`'s native DAP implementation](https://github.com/go-delve/delve/tree/master/service/dap) instead of this one. Follow along with [golang/vscode-go#23](https://github.com/golang/vscode-go/issues/23) for updates on that work.
+This codebase is currently in flux: We are working on using [`Delve`'s native DAP implementation](https://github.com/go-delve/delve/tree/master/service/dap) instead of this one. Follow along with [golang/vscode-go#23](https://github.com/golang/vscode-go/issues/23) for updates on that work.
## Overview
@@ -15,11 +15,11 @@
## Before you begin
-Before you start working on your change, please read the [Contribution guidelines](contributing.md). This document assumes that you are already familiar with the process of [building](contributing.md#build), [running](contributing.md#run), and [sideloading](contributing.md#sideload) the VS Code Go extension.
+Before you start working on your change, please read the [contribution guidelines](contributing.md). This document assumes that you are already familiar with the process of [building](contributing.md#setup), [running](contributing.md#run), and [sideloading](contributing.md#sideload) the VS Code Go extension.
## Debug only the Debug Adapter
-As a next step, you may want to debug the Debug Adapter, in order to understand how your change work with [`Delve`](tools.md#delve).
+As a next step, you may want to debug the Debug Adapter, in order to understand how your change work with [Delve](tools.md#delve).
**NOTE: Since the Debug Adapter runs in a separate process from the rest of the extension, the steps below only enable you to debug the Debug Adapter code, not the entire extension. To debug the entire extension, as well as the debug adapter, see the instructions [below](#debug-the-entire-extension).**
@@ -28,7 +28,7 @@
3. Add breakpoints as needed to the [`vscode-go/src/debugAdapter/goDebug.ts`](../src/debugAdapter/goDebug.ts) file.
4. Open another instance of VS Code and open the Go project to debug.
5. Create a debug configuration for the Go project if it doesn't exist. Set `"debugServer": 4711` in the root of the configuration.
-6. Start debugging your Go program using this configuration. This will trigger the breakpoints in `goDebug.ts` file.
+6. Start debugging your Go program using this configuration. This will trigger the breakpoints in [`goDebug.ts`](../src/debugAdapter/goDebug.ts) file.
## Debug the entire extension, including the Debug Adapter
@@ -37,24 +37,22 @@
1. Open the root [`vscode-go`](../) folder in one instance of VS Code.
2. Choose the `Launch Extension` debug target and run it (F5). This will launch the second instance of VS Code.
3. In this second instance, open the Go application you'd like to debug. Here, as above, create a debug configuration pointing to the program you want to debug. Add `"debugServer": 4711` to the root of the configuration.
-4. Open a third instance of VS Code an the [`vscode-go/src/debugAdapter`](../src/debugAdapter) folder. In this instance, select the `Launch as server` configuration and run it (F5).
-5. Return to the second VS Code instance with the Go program. Run the debug configuration (F5). Debuggers from the other two VS Code windows are attached to the Go debug adapter and the Go language integration respectively, so you can set breakpoints, step through code and inspect state as needed.
-
-<!--TODO(rstambler): Do we need to delete the src/debugAdapter/.vscode/launch.json file?-->
+4. Open the [`vscode-go/src/debugAdapter`](../src/debugAdapter) folder in a third VS Code instance. Select the `Launch as server` configuration and run it (`F5`).
+5. Return to the second VS Code instance with the Go program. Run the debug configuration (`F5`). Debuggers from the other two VS Code windows are attached to the Debug Adapter and the Go extension, so you can set breakpoints, step through code, and inspect state as needed.
## Debug VS Code and the Debug Adapter
-In some very rare cases, you may find it helpful to debug VS Code itself. Examples of such cases include veryfing workbench behavior and state before executing debug adapter API calls.
+In some very rare cases, you may find it helpful to debug VS Code itself. An example of such a case might be veryfing workbench behavior and state before executing debug adapter API calls.
First, ensure that you can [build and run VS Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#build-and-run) from source successfully.
Next, follow these steps:
-1. Open an instance of VS Code, which you have built from source.
-2. [Sideload](contributing.md#sideload) your local `vscode-go` extension to the local instance of VS. This can be done by copying the contents of the vscode-go folder into `$HOME/.vscode-oss-dev/extensions/ms-vscode.go` (the exact location may vary by OS).
+1. Open an instance of VS Code that you have built from source.
+2. [Sideload](contributing.md#sideload) your local `vscode-go` extension to the local instance of VS Code. This can be done by copying the contents of the `vscode-go` directory into `$HOME/.vscode-oss-dev/extensions/ms-vscode.go` (the exact location may vary by OS).
3. Open the `vscode` folder in Visual Studio Code.
-4. Launch the VS Code debug instance (OSS - Code) by choosing the `Launch VS Code` debug configuraion from the drop-down in the Run view. Add a breakpoints as needed.
-5. In another instance of VS Code, open the [`vscode-go`](../) folder. Choose the `Launch as server` debug configuration in the Run view. Add breakpoints as desired in the [`vscode-go/src/debugAdapter/goDebug.ts`](../src/debugAdapter/goDebug.ts) file.
+4. Launch the VS Code debug instance (OSS - Code) by choosing the `Launch VS Code` debug configuraion from the drop-down in the Run view. Add breakpoints as needed.
+5. In another instance of VS Code, open the `vscode-go` folder. Choose the `Launch as server` debug configuration in the Run view. Add breakpoints as desired in the [`vscode-go/src/debugAdapter/goDebug.ts`](../src/debugAdapter/goDebug.ts) file.
6. Open the Go application that you want to debug in the OSS Code instance initiated in step 4.
-7. Create a debug configuration with the setting `"debugServer": 4711` in the root.
+7. Create a debug configuration with the setting `"debugServer": 4711`.
8. Start debugging your Go application. Observe that any breakpoints you set in the VS Code and debug adapter codebases will be triggered.
diff --git a/docs/debugging.md b/docs/debugging.md
index e50bbf6..e71bfe5 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -1,10 +1,9 @@
# Debugging
-The Go debugger is [Delve]. The [Delve] repository has detailed instructions, so we recommend taking a look at the [Delve documentation](https://github.com/go-delve/delve/tree/master/Documentation).
+This document explains how to debug your Go programs in VS Code. The Go debugger is [Delve]. You can read more about it in the [Delve documentation](https://github.com/go-delve/delve/tree/master/Documentation).
## Overview
-* [Features](#features)
* [Set up](#set-up)
* [Installation](#installation)
* [Configuration](#configuration)
@@ -33,7 +32,7 @@
You can also install it manually in one of two ways:
-1. Open the Command Palette (Ctrl+Shift+P), select `Go: Install/Update Tools`, and select `dlv`.
+1. Open the Command Palette (Ctrl+Shift+P), select [`Go: Install/Update Tools`](settings.md#go-installupdate-tools), and select [`dlv`](tools.md#dlv).
2. Follow the [Delve installation instructions](https://github.com/go-delve/delve/tree/master/Documentation/installation).
### Configuration
@@ -41,10 +40,10 @@
You may not need to configure any settings to start debugging your programs, but you should be aware that the debugger looks at the following settings.
* Related to [`GOPATH`](gopath.md):
- * [`go.gopath`](settings.md#gopath)
- * [`go.inferGopath`](settings.md#inferGopath)
-* `go.delveConfig`
- * `apiVersion`: Controls the version of the Delve API used when launching the Delve headless server (default: `2`).
+ * [`go.gopath`](settings.md#go.gopath)
+ * [`go.inferGopath`](settings.md#go.inferGopath)
+* [`go.delveConfig`](settings.md#go.delveConfig)
+ * `apiVersion`: Controls the version of the Delve API used (default: `2`).
* `dlvLoadConfig`: The configuration passed to Delve, which controls how variables are shown in the Debug pane. Not applicable when `apiVersion` is 1.
* `maxStringLen`: Maximum number of bytes read from a string (default: `64`).
* `maxArrayValues`: Maximum number of elements read from an array, slice, or map (default: `64`).
@@ -56,7 +55,7 @@
There are some common cases when you might want to tweak the Delve configurations.
* To change the default cap of 64 on string and array length when inspecting variables in the Debug view, set `maxStringLen`. (See a related known issue: [golang/vscode-go#126](https://github.com/golang/vscode-go/issues/126)).
-* To evaluate nested variables in the Debug viewlet, set `maxVariableRecurse`.
+* To evaluate nested variables in the Run view, set `maxVariableRecurse`.
## Launch Configurations
@@ -79,23 +78,23 @@
}
```
-There are some more properties that you can adjust in the debug configuration. See the table below:
+There are some more properties that you can adjust in the debug configuration:
Property | Description
-------- | -----------
-name | The name for your configuration as it appears in the drop-down in the Debug view.
-type | Always leave this set to `"go"`. VS Code uses this setting to determine which extension should be used for debugging your code.
-request | One of `launch` or `attach`. Use `attach` when you want to attach to an already running process.
+name | The name for your configuration as it appears in the drop-down in the Run view.
+type | Always leave this set to `"go"`. VS Code uses this setting to determine which extension should be used for debugging.
+request | One of `launch` or `attach`. Use `attach` when you want to attach to a running process.
mode | For `launch` requests, one of `auto`, `debug`, `remote`, `test`, or `exec`. For `attach` requests, use `local` or `remote`.
-program | In `test` or `debug` mode, this refers to the absolute path to the package or file to debug. In `exec` mode, this is the already built binary file to debug. Not applicable to `attach` requests.
-env | Environment variables to use when debugging. Use the format: `{ "ENVNAME": "ENVVALUE" }`.
+program | In `test` or `debug` mode, this refers to the absolute path to the package or file to debug. In `exec` mode, this is the existing binary file to debug. Not applicable to `attach` requests.
+env | Environment variables to use when debugging. Use the format: `{ "NAME": "VALUE" }`.
envFile | Absolute path to a file containing environment variable definitions. The environment variables passed in via the `env` property override the ones in this file.
-args | Array of command-line arguments that will be passed in to the program being debugged.
+args | Array of command-line arguments to pass to the program being debugged.
showLog | If `true`, Delve logs will be printed in the Debug Console panel.
logOutput | Comma-separated list of Delve components (`debugger`, `gdbwire`, `lldbout`, `debuglineerr`, `rpc`) that should produce debug output when `showLog` is `true`.
-buildFlags | Build flags to be passed to the Go compiler.
+buildFlags | Build flags to pass to the Go compiler.
remotePath | If remote debugging (`mode`: `remote`), this should be the absolute path to the file being debugged on the remote machine. See the section on [Remote Debugging](#remote-debugging) for further details. [golang/vscode-go#45](https://github.com/golang/vscode-go/issues/45) is also relevant.
-processId | This is the process ID of the executable you want to debug.Applicable only when using the `attach` request in `local` mode.
+processId | This is the process ID of the executable you want to debug. Applicable only when using the `attach` request in `local` mode.
### Specifying [build tags](https://golang.org/pkg/go/build/#hdr-Build_Constraints)
@@ -131,7 +130,7 @@
In addition to [VS Code variables], you can make use of [snippets] when editing the launch configuration in `launch.json`.
-When you type `go` in the `launch.json` file, you will see snippet suggestions for debugging a given test function or the current file or package.
+When you type `go` in the `launch.json` file, you will see snippet suggestions for debugging the current file or package or a given test function.
Below are the available sample configurations:
@@ -267,7 +266,7 @@
`program` should point to the absolute path of the file on your local machine. This should be the counterpart of the file in `remotePath`.
-When you run the `Launch remote` target, VS Code will send debugging commands to the `dlv` server you started, instead of launching it's own `dlv` instance against your app.
+When you run the `Launch remote` target, VS Code will send debugging commands to the `dlv` server you started, instead of launching it's own `dlv` instance against your program.
For further examples, see [this launch configuration for a process running in a Docker host](https://github.com/lukehoban/webapp-go/tree/debugging).
@@ -283,7 +282,7 @@
### Update Delve
-If the problem persists, it's time to start troubleshooting. A good first step is to make sure that you are working with the latest version of Delve. You can do this by running the `Go: Install/Update Tools` command and selecting `dlv`.
+If the problem persists, it's time to start troubleshooting. A good first step is to make sure that you are working with the latest version of Delve. You can do this by running the [`Go: Install/Update Tools`](settings.md#go-installupdate-tools) command and selecting [`dlv`](tools.md#dlv).
### Check your [launch configuration](#launch-configurations)
@@ -291,25 +290,23 @@
One common error is `could not launch process: stat ***/debug.test: no such file or directory`. You may see this while running in the `test` mode. This happens when the `program` attribute points to a folder with no test files, so ensure that the `program` attribute points to a directory containing the test files you wish to debug.
-Also, check the version of the Delve API used in your [launch configuration](#launch-configurations). This is handled by the `–api-version` flag, `2` is the default. If you are debugging on a remote machine, this is particularly important, as the versions on the local and remote machines much match. You can change the API version by editing the [configuration in the `launch.json` file](#launch-configurations).
+Also, check the version of the Delve API used in your [launch configuration](#launch-configurations). This is handled by the `–api-version` flag, `2` is the default. If you are debugging on a remote machine, this is particularly important, as the versions on the local and remote machines much match. You can change the API version by editing the [`launch.json` file](#launch-configurations).
### Check for multiple versions of Delve
-You might have multiple different versions of `dlv` installed, and VS Code Go could be using a wrong or old version. Run the `Go: Locate Configured Go Tools` command and see where VS Code Go has found `dlv` on your machine. You can try running `which dlv` to see which version of `dlv` you are using on the [command-line](https://github.com/go-delve/delve/tree/master/Documentation/cli).
+You might have multiple different versions of [`dlv`](tools.md#dlv) installed, and VS Code Go could be using a wrong or old version. Run the [`Go: Locate Configured Go Tools`](settings.md#go-locate-configured-go-tools) command and see where VS Code Go has found `dlv` on your machine. You can try running `which dlv` to see which version of `dlv` you are using on the [command-line](https://github.com/go-delve/delve/tree/master/Documentation/cli).
To fix the issue, simply delete the version of `dlv` used by the Go extension. Note that the extension first searches for binaries in your `$GOPATH/bin` and then looks on your `$PATH`.
-<!--TODO(rstambler): It feels like we should just prefer whatever is on the PATH and fallback to GOPATH if it's not found?-->
-
If you see the error message `Failed to continue: "Error: spawn EACCES"`, the issue is probably multiple versions of `dlv`.
### Try building your binary **without** compiler optimizations
-If you notice `Unverified breakpoints` or missing variables, ensure that your binary was built **without** compiler optimizations. Try building the binary with the `-gcflags="all=-N -l"`.
+If you notice `Unverified breakpoints` or missing variables, ensure that your binary was built **without** compiler optimizations. Try building the binary with `-gcflags="all=-N -l"`.
### Check your `GOPATH`
-Make sure that the debugger is using the right [`GOPATH`](gopath.md). This is probably the issue if you see `Cannot find package ".." in any of ... errors. Read more about configuring your [GOPATH](gopath.md) or [file an issue report](https://github.com/golang/vscode-go/issues/new/choose).
+Make sure that the debugger is using the right [`GOPATH`](gopath.md). This is probably the issue if you see `Cannot find package ".." in any of ...` errors. Read more about configuring your [GOPATH](gopath.md) or [file an issue report](https://github.com/golang/vscode-go/issues/new/choose).
**As a work-around**, add the correct `GOPATH` as an environment variable in the `env` property in the `launch.json` file.
@@ -328,7 +325,7 @@
### **Optional**: Debug the debugger
-This is not a required step, but if you want to continue digging deeper, you can, in fact, debug the debugger. The code for the debugger can be found in the [debug adapter module](../src/debugAdapter). See our [Contribution Guide](contributing.md) to learn how to [run](contributing.md#run) and [sideload](contributing.md#sideload) the Go extension.
+This is not a required step, but if you want to continue digging deeper, you can, in fact, debug the debugger. The code for the debugger can be found in the [debug adapter module](../src/debugAdapter). See our [contribution guide](contributing.md) to learn how to [run](contributing.md#run) and [sideload](contributing.md#sideload) the Go extension.
### Ask for help
diff --git a/docs/features.md b/docs/features.md
index 6057552..8c54edc 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -2,11 +2,9 @@
This document describes the features supported by this extension.
-If you are using the Go language server, `gopls`, please the [gopls documentation](gopls.md) instead. (You can check if you are using `gopls` by opening your VS Code settings and checking if `go.useLanguageServer` is set to `true`.)
+If you are using the Go language server, `gopls`, please the [gopls documentation](gopls.md) instead. (You can check if you are using `gopls` by opening your VS Code settings and checking if [`"go.useLanguageServer"`](settings.md#go.useLanguageServer) is `true`.)
-If you are using Go modules *without* the language server, some of the features listed below will not be available.
-
-Please see the [Tools documentation](tools.md) for details on how to troubleshoot and adjust your settings.
+If you are using Go modules **without** the language server, some of the features listed below will not be available.
## Table of Contents
@@ -40,45 +38,43 @@
* [Run your code](#run-your-code)
* [Test and benchmark](#test-and-benchmark)
* [Code coverage](#code-coverage)
-* [Debug your code](#debug-your-code)
+* [Debug your code](#debugging)
* [Other](#other)
* [Go Playground](#go-playground)
## [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense)
-This extension supports the following IntelliSense features:
-
### Code completion
Completion results appear for symbols as you type. You can trigger this manually with the Ctrl+Space shortcut. This feature is provided by the [`gocode`](tools.md#gocode) tool.
-Autocompletion is also supported for packages you have not imported into your program. This feature is provided by the [`gopkgs`](#tools.md#gopkgs) tool.
+Autocompletion is also supported for packages you have not yet imported into your program. This feature is provided by the [`gopkgs`](tools.md#gopkgs) tool.
### Signature help
-Information about the signature of a function pops up as you type in its parameters. This feature is provided by the [`gogetdoc`](tools.md#gogetdoc) tool, but it can also be provided by a combination of [`godef`](tools.md#godef) and [`godoc`](tools.md#godoc) (configured via the [`"go.docsTool"`](settings.md#docsTool) setting).
+Information about the signature of a function pops up as you type in its parameters. This feature is provided by the [`gogetdoc`](tools.md#documentation) tool, but it can also be provided by a combination of [`godef`](tools.md#documentation) and [`godoc`](tools.md#documentation) (configured via the [`"go.docsTool"`](settings.md#go.docsTool) setting).
### Quick info on hover
-Documentation appears when you hover over a symbol. This feature is provided by the [`gogetdoc`](tools.md#gogetdoc) tool, but it can also be provided by a combination of [`godef`](tools.md#godef) and [`godoc`](tools.md#godoc) (configured via the [`"go.docsTool"`](settings.md#docsTool) setting).
+Documentation appears when you hover over a symbol. This feature is provided by the [`gogetdoc`](tools.md#documentation) tool, but it can also be provided by a combination of [`godef`](tools.md#documentation) and [`godoc`](tools.md#documentation) (configured via the [`"go.docsTool"`](settings.md#go.docsTool) setting).
## [Code Navigation](https://code.visualstudio.com/docs/editor/editingevolved)
### Go to definition
-Jump to or peek a symbol's declaration. This feature is provided by the [`gogetdoc`](tools.md#gogetdoc) tool, but it can also be provided by a combination of [`godef`](tools.md#godef) and [`godoc`](tools.md#godoc) (configured via the [`"go.docsTool"`](settings.md#docsTool) setting).
+Jump to or peek a symbol's declaration. This feature is provided by the [`gogetdoc`](tools.md#documentation) tool, but it can also be provided by a combination of [`godef`](tools.md#documentation) and [`godoc`](tools.md#documentation) (configured via the [`"go.docsTool"`](settings.md#go.docsTool) setting).
### Find references
Find or go to the references of a symbol. This feature is provided the [`guru`](tools.md#guru) tool.
-This feature is not available if you are using Go modules without `gopls`, the Go language server.
+This feature is not available if you are using Go modules **without** [`gopls`](gopls.md), the Go language server.
### Find interface implementations
Find the concrete types that implement a given interface. This feature is provided by the [`guru`](tools.md#guru) tool.
-This feature is not available if you are using Go modules without `gopls`, the Go language server.
+This feature is not available if you are using Go modules **without** [`gopls`](gopls.md), the Go language server.
### [Go to symbol](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-symbol)
@@ -94,31 +90,23 @@
### Toggle between code and tests
-Quickly toggle between a file and its corresponding test file by using the `Go: Toggle Test File` command.
+Quickly toggle between a file and its corresponding test file by using the [`Go: Toggle Test File`](commands.md#go-toggle-test-file) command.
## Code Editing
### [Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets)
-Predefined snippets for quick coding. These snippets will pop up as completion suggestions as you type. Users can also define their own custom snippets (see [these instructions](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_create-your-own-snippets)).
+Predefined snippets for quick coding. These snippets will appear as completion suggestions when you type. Users can also define their own custom snippets (see [Snippets in Visual Studio Code](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_create-your-own-snippets)).
### Format and organize imports
-Format code and organize imports, either manually or on save. The code is formatted by the [`gofmt`](tools.md#gofmt) tool, which is the standard for Go code. Imports are added automatically to your file via the [`goimports`](tools.md#goimports) tool, which is also an industry standard. By default, this extension also uses the [`goreturns`](tools.md#goreturns) tool, which automatically fills in default return values for functions.
+Format code and organize imports, either manually or on save. The code is formatted by the [`gofmt`](tools.md#formatting) tool, which is the standard for Go code. Imports are added automatically to your file via the [`goimports`](tools.md#formatting) tool, which is also an industry standard. By default, this extension also uses the [`goreturns`](tools.md#formatting) tool, which automatically fills in default return values for functions.
-The behavior of the formatter can be configured via the [`"go.formatTool"`](#commands#format-tool) tool setting. Formatting can also be turned off by adding the following setting to your `settings.json` file:
-
-```json5
-"[go]": {
- "editor.formatOnSave": false
-}
-```
-
-If you're having issues with the formatting provided by this extension, take a look at the [Troubleshooting Formatting](troubleshooting.md#investigating-formatting) documentation.
+The behavior of the formatter can be configured via the [`"go.formatTool"`](settings.md#go.formatTool) tool setting. The [troubleshooting guide](troubleshooting.md#formatting) gives more details and explains how to [disable formatting](troubleshooting.md#disable-formatting) entirely.
#### Add import
-Manually add a new import to your file through the `Go: Add Import` command. Available packages are offered from your `GOPATH` and module cache.
+Manually add a new import to your file through the [`Go: Add Import`](commands.md#go-add-import) command. Available packages are offered from your `GOPATH` and module cache.
### [Rename symbol](https://code.visualstudio.com/docs/editor/refactoring#_rename-symbol)
@@ -126,7 +114,7 @@
**Note**: For undo after rename to work on Windows, you need to have `diff` tool on your `PATH`.
-This feature is not available if you are using Go modules without `gopls`, the Go language server.
+This feature is not available if you are using Go modules **without** [`gopls`](gopls.md), the Go language server.
### Refactor
@@ -136,19 +124,19 @@
### Add or remove struct tags
-Use the `Go: Add Tags to Struct Fields` command to automatically generate or remove [tags](https://pkg.go.dev/reflect?tab=doc#StructTag) for your struct. This feature is provided by the [`gomodifytags`](tools.md#gomodifytags) tool.
+Use the [`Go: Add Tags to Struct Fields`](commands.md#go-add-tags-to-struct-fields) command to automatically generate or remove [tags](https://pkg.go.dev/reflect?tab=doc#StructTag) for your struct. This feature is provided by the [`gomodifytags`](tools.md#gomodifytags) tool.
### Generate interface implementation
-Use the `Go: Generate Interface Stubs` command to automatically generate method stubs for a given interface. This feature is provided by the [`impl`](tools.md#impl) tool.
+Use the [`Go: Generate Interface Stubs`](commands.md#go-generate-interface-stubs) command to automatically generate method stubs for a given interface. This feature is provided by the [`impl`](tools.md#impl) tool.
### Generate unit tests
-Easily generate unit tests for your project by running one of the `Go: Generate Unit Tests for ...` commands. This can be done at a function, file, or package level. This feature is provided by the [`gotests`](tools.md#gotests) tool.
+Easily generate unit tests for your project by running one of the [`Go: Generate Unit Tests for ...`](commands.md#go-generate-unit-tests-for-file) commands. This can be done at a function, file, or package level. This feature is provided by the [`gotests`](tools.md#gotests) tool.
### Fill struct literals
-Use the `Go: Fill struct` command to automatically fill a struct literal with its default values. This command is provided by the [`fillstruct`](tools.md#fillstruct).
+Use the [`Go: Fill struct`](commands.md#fill-struct) command to automatically fill a struct literal with its default values. This command is provided by the [`fillstruct`](tools.md#fillstruct).
## Diagnostics
@@ -156,21 +144,23 @@
### Build errors
-Build errors can be shown as you type or on save. Configure this behavior through the [`"go.buildOnSave"`](settings.md#buildOnSave) setting.
+Build errors can be shown as you type or on save. Configure this behavior through the [`"go.buildOnSave"`](settings.md#go.buildOnSave) setting.
-By default, code is compiled using the `go` command (`go build`), but build errors as you type are provided by the [`gotype-live`](tools.md#gotype-live) tool.
+By default, code is compiled using the `go` command (`go build`), but build errors as you type are provided by the [`gotype-live`](tools.md#diagnostics) tool.
### Vet errors
-Vet errors can be shown on save. The vet-on-save behavior can also be configured through the [`"go.vetOnSave"`](settings.md#vetOnSave) setting.
+Vet errors can be shown on save. The vet-on-save behavior can also be configured through the [`"go.vetOnSave"`](settings.md#go.vetOnSave) setting.
-The vet tool used is the one provided by the `go` command: `go vet`.
+The vet tool used is the one provided by the `go` command: [`go vet`](https://golang.org/cmd/vet/).
### Lint errors
-Much like vet errors, lint errors can also be shown on save. This behavior is configurable through the [`"go.lintOnSave"`](settings.md#lintOnSave) setting.
+Much like vet errors, lint errors can also be shown on save. This behavior is configurable through the [`"go.lintOnSave"`](settings.md#go.lintOnSave) setting.
-The default lint tool is the one provided by the `go` command: `go lint`. However, custom lint tools can be easily used instead by configuring the [`"go.lintTool"`](settings.md#lintTool) setting. To learn more about the different options, see the [documentation for diagnostic tools](tools.md#diagnostics).
+The default lint tool is the one provided by the `go` command: `go lint`. However, custom lint tools can be easily used instead by configuring the [`"go.lintTool"`](settings.md#go.lintTool) setting. [`staticcheck`], [`golangci-lint`], and [`revive`] are supported.
+
+For a complete overview of linter options, see the [documentation for diagnostic tools](tools.md#diagnostics).
## Run and test in the editor
@@ -178,17 +168,17 @@
To run your code without debugging, use the keyboard shortcut `Ctrl+F5` or run the command `Debug: Start without Debugging`. To debug, see [Debugging](#debugging) below.
-This command requires you to have a [launch configuration](#launch-configuration) in a `launch.json` file. To open or create your `launch.json`, run the `Debug: Open launch.json` command. Use the default `Go: Launch file` configuration.
+This command requires you to have a [launch configuration](debugging.md#launch-configuration) in a `launch.json` file. To open or create your `launch.json`, run the `Debug: Open launch.json` command. Use the default `Go: Launch file` configuration.
Behind the scenes, the `Debug: Start without Debugging` command calls `go run`. `go run` usually requires the path to the file to run, so your `launch.json` should contain `"program": "${file}"`.
### Test and benchmark
-[Code lenses](https://code.visualstudio.com/blogs/2017/02/12/code-lens-roundup) allow users to easily run tests and benchmarks for a given function, file, package, or workspace. Alternatively, the same functionality is available through a set of commands: `Go: Test Function At Cursor`, `Go: Test File`, `Go: Test Package`, and `Go: Test All Packages in Workspace`.
+[Code lenses](https://code.visualstudio.com/blogs/2017/02/12/code-lens-roundup) allow users to easily run tests and benchmarks for a given function, file, package, or workspace. Alternatively, the same functionality is available through a set of commands: [`Go: Test Function At Cursor`](commands.md#go-test-function-at-cursor), [`Go: Test File`](commands.md#go-test-file), [`Go: Test Package`](commands.md#go-test-package), and [`Go: Test All Packages in Workspace`](commands.md#go-test-all-packages-in-workspace).
### Code Coverage
-Show code coverage in the editor, either after running a test or on-demand. This can be done via the commands: `Go: Apply Cover Profile` and `Go: Toggle Test Coverage in Current Package`.
+Show code coverage in the editor, either after running a test or on-demand. This can be done via the commands: [`Go: Apply Cover Profile`](commands.md#go-apply-cover-profile) and [`Go: Toggle Test Coverage in Current Package`](commands.go-toggle-test-coverage-in-current-package).
## [Debugging](debugging.md)
@@ -198,6 +188,9 @@
### Go Playground
-Export your current file to the [Go Playground](https://play.golang.org) via the `Go: Run On Go Playground` command. This is useful for quickly exporting code for an example.
+Export your current file to the [Go Playground](https://play.golang.org) via the [`Go: Run On Go Playground`](settings.md#go-run-on-go-playground) command. This is useful for quickly creating a piece of sample code.
[`gopls`]: gopls.md
+[`staticcheck`]: https://staticcheck.io/
+[`golangci-lint`]: https://golangci-lint.run/
+[`revive`]: https://github.com/mgechev/revive
diff --git a/docs/gopath.md b/docs/gopath.md
index de26575..60c6346 100644
--- a/docs/gopath.md
+++ b/docs/gopath.md
@@ -1,6 +1,6 @@
# `GOPATH`
-The `GOPATH` environment variable is a fundamental part of writing Go code before the introduction of [Go modules]. It specifies the location of your workspace, and it defaults to `$HOME/go`. A `GOPATH` directory contains `src`, `bin`, and `pkg` directories. Your code is typically located in the `$GOPATH/src` directory.
+The `GOPATH` environment variable is a fundamental part of writing Go code **without** [Go modules]. It specifies the location of your workspace, and it defaults to `$HOME/go`. A `GOPATH` directory contains `src`, `bin`, and `pkg` directories. Your code is typically located in the `$GOPATH/src` directory.
If you are not familiar with Go and `GOPATH`, please first read about [writing Go code with `GOPATH`](https://golang.org/doc/gopath_code.html#GOPATH).
@@ -10,11 +10,12 @@
* [Setting `GOPATH`](#setting-gopath)
* [Different `GOPATH`s for different projects](#different-gopaths-for-different-projects)
* [Automatically inferring your `GOPATH`](#automatically-inferring-your-gopath)
+* [Install tools to a separate `GOBIN`](#install-tools-to-a-separate-gobin)
* [Install tools to a separate `GOPATH`](#install-tools-to-a-separate-gopath)
## Check the value of `GOPATH`
-First, it's useful to quickly check that you are using the right `GOPATH`. Two commands report the `GOPATH` value used by the VS Code Go extension: (1) `Go: Current GOPATH`, or (2) `Go: Locate Configured Go Tools`. Use either of these commands to check which `GOPATH` the extension is using.
+First, it's useful to quickly check that you are using the right `GOPATH`. Two commands report the `GOPATH` value used by the VS Code Go extension: (1) [`Go: Current GOPATH`](commands.md#go-current-gopath), or (2) [`Go: Locate Configured Go Tools`](commands.md#go-locate-configured-go-tools). Use either of these commands to check which `GOPATH` the extension is using.
If the `GOPATH` value is incorrect, see the details below on how to configure it.
@@ -22,25 +23,25 @@
If you have chosen not to use [Go modules], you will need to configure your `GOPATH`. Modules have largely eliminated the need for a `GOPATH`, so if you're interested in using them, taking a look at the [modules documentation](modules.md) for the VS Code Go extension.
-Setting `GOPATH` is typically as simple as setting the environment variable once in your system's configuration. Take a look at the [Setting `GOPATH`](https://github.com/golang/go/wiki/SettingGOPATH) Wiki page if you're unsure how to do this.
+Setting `GOPATH` is typically as simple as setting the environment variable once in your system's configuration. Take a look at the [Setting `GOPATH` Wiki](https://github.com/golang/go/wiki/SettingGOPATH) if you're unsure how to do this.
-By default, the extension uses the value of the environment variable `GOPATH`. If no such environment variable is set, the extension runs `go env` and uses the `GOPATH` provided in that output.
+By default, the extension uses the value of the environment variable `GOPATH`. If no such environment variable is set, the extension runs `go env` and uses the `GOPATH` reported by the `go` command.
Note that, much like a `PATH` variable, `GOPATH` can contain multiple directory paths, separated by `:` or `;`. This allows you to set different `GOPATH`s for different projects.
-Still, there are a number of cases in which you might want a more complicated `GOPATH` set-up. This document will explain how to configure and manage your `GOPATH` within the VS Code Go extension.
+Still, there are a number of cases in which you might want a more complicated `GOPATH` set-up. Below, we explain more complex ways to configure and manage your `GOPATH` within the VS Code Go extension.
## Different `GOPATH`s for different projects
-Setting [`go.gopath`](settings.md#gopath) in your [user settings](https://vscode.readthedocs.io/en/latest/getstarted/settings/) overrides the environment's `GOPATH` value.
+Setting [`go.gopath`](settings.md#go.gopath) in your [user settings](https://vscode.readthedocs.io/en/latest/getstarted/settings/) overrides the environment's `GOPATH` value.
-[Workspace settings](https://vscode.readthedocs.io/en/latest/getstarted/settings/) override user settings, so you can use the [`go.gopath`](settings.md#gopath) setting to set different `GOPATH`s for different projects. A `GOPATH` can also contain multiple directories, so this setting is not necessary to achieve this behavior.
+[Workspace settings](https://vscode.readthedocs.io/en/latest/getstarted/settings/) override user settings, so you can use the [`go.gopath`](settings.md#go.gopath) setting to set different `GOPATH`s for different projects. A `GOPATH` can also contain multiple directories, so this setting is not necessary to achieve this behavior.
## Automatically inferring your `GOPATH`
**NOTE: This feature only works in `GOPATH` mode, not in module mode.**
-The [`go.inferGopath`](settings.md#inferGopath) setting overrides the [`go.gopath`](settings.md#gopath) setting. If you set [`go.inferGopath`](settings.md#inferGopath) to `true`, the extension will try to infer your `GOPATH` based on the workspace opened in VS Code. This is done by searching for a `src` directory in your workspace. The parent of this `src` directory is then added to your [global `GOPATH`](#setting-gopath) (`go env GOPATH`).
+The [`go.inferGopath`](settings.md#go.inferGopath) setting overrides the [`go.gopath`](settings.md#go.gopath) setting. If you set [`go.inferGopath`](settings.md#go.inferGopath) to `true`, the extension will try to infer your `GOPATH` based on the workspace opened in VS Code. This is done by searching for a `src` directory in your workspace. The parent of this `src` directory is then added to your [global `GOPATH`](#setting-gopath) (`go env GOPATH`).
For example, say your global `GOPATH` is `$HOME/go`, but you are working in a repository with the following structure.
@@ -51,13 +52,13 @@
└── main.go
```
-If you open the `foo` directory as your workspace root in VS Code, [`"go.inferGopath"`](settings.md#inferGopath) will set your `GOPATH` to `$HOME/go:/path/to/foo/bar`.
+If you open the `foo` directory as your workspace root in VS Code, [`"go.inferGopath"`](settings.md#go.inferGopath) will set your `GOPATH` to `$HOME/go:/path/to/foo/bar`.
This setting is useful because it allows you to avoid setting the `GOPATH` in the workspace settings of each of your projects.
## Install tools to a separate `GOBIN`
-If you find yourself frequently switching between `GOPATH`s, you may have found that the extension prompts you to install tools for every `GOPATH`. You can resolve this by making sure your tool installations are on your `PATH`, or you can configure a separate directory for tool installation: `GOBIN`. This environment variable tells the `go` command where to install all binaries. Configure it by setting:
+If you switch frequently between `GOPATH`s, you may find that the extension prompts you to install tools for every `GOPATH`. You can resolve this by making sure your tool installations are on your `PATH`, or you can configure a separate directory for tool installation: `GOBIN`. This environment variable tells the `go` command where to install all binaries. Configure it by setting:
```json5
"go.toolsEnvVars": {
@@ -69,12 +70,10 @@
**NOTE: The following is only relevant if you are using a Go version that does not support [Go modules], that is, any version of Go before 1.11.**
-Before Go 1.11, the `go get` command installs tools and their source code to your `GOPATH`. Because this extension uses a lot of different tools, this can clutter up your `GOPATH`. If you wish to reduce this clutter, you can have the extension install tools do a different location. This also addresses the issue described above, when switching `GOPATHs` forces you to reinstall Go tools.
+Before Go 1.11, the `go get` command installed tools and their source code to your `GOPATH`. Because this extension uses a lot of different tools, this causes clutter in your `GOPATH`. If you wish to reduce this clutter, you can have the extension install tools to a different location. This also addresses the issue described above, when switching `GOPATHs` forces you to reinstall Go tools.
-This can be done via the [`"go.toolsGopath"`](settings.md#toolsGopath) setting. Use it to specify an alternate directory that the extension can use to install tools. After you set this value, be sure to run the `Go: Install/Update Tools` command so that the Go tools get installed to the provided location.
+This can be done by setting [`"go.toolsGopath"`](settings.md#go.toolsGopath) to an alternate path, only for tool installations. After you configure this setting, be sure to run the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command so that the Go tools get installed to the provided location.
-The extension will fall back to your existing `GOPATH` if tools are not found in the [`go.toolsGopath`](settings.md#toolsGopath) directory.
-
-<!--TODO(rstambler): Should we deprecate this setting for Go > 1.11?-->
+The extension will fall back to your existing `GOPATH` if tools are not found in the [`go.toolsGopath`](settings.md#go.toolsGopath) directory.
[Go modules]: https://blog.golang.org/using-go-modules
diff --git a/docs/gopls.md b/docs/gopls.md
index 39c36f6..25bd24a 100644
--- a/docs/gopls.md
+++ b/docs/gopls.md
@@ -3,7 +3,6 @@
[`gopls`] is the official Go [language server](https://langserver.org/) developed by the Go team. It was developed in response to the release of [Go modules], and it is the recommended approach when working with [Go modules] in VS Code.
[`gopls`] is currently in an alpha state, so it is not enabled by default. Please note that [`gopls`] only supports Go versions above 1.12.
-<!--TODO(rstambler): Change this once we support 1.11 and 1.12 again.-->
[`gopls`] has its own [documentation pages](https://github.com/golang/tools/tree/master/gopls/doc), and they should be treated as the source of truth for how to use [`gopls` in VS Code](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md).
@@ -18,64 +17,47 @@
* [Troubleshooting](https://github.com/golang/tools/blob/master/gopls/doc/troubleshooting.md)
* [Additional resources](#additional-resources)
-<!--TODO(rstambler): Write a gopls troubleshooting section here or in the gopls VS Code docs.-->
-
## Background
This extension functions by shelling out to a number of command-line tools. This introduces complexity, as each feature is provided by a different tool. Language servers enable all editors to support all programming languages without these individualized tools. They also provide speed improvements, as they can cache and reuse results.
-[`gopls`] is the official Go language server. Using `gopls` will enable the VS Code Go extension to provide high-quality Go support as the language evolves.
+[`gopls`] is the official Go language server. Using [`gopls`] will enable the VS Code Go extension to provide high-quality Go support as the language evolves.
To learn more about the context behind [`gopls`], you can watch the [Go pls, stop breaking my editor](https://www.youtube.com/watch?v=EFJfdWzBHwE) talk at GopherCon 2019.
## Enable the language server
-To start using the language server, set [`"go.useLanguageServer": true`](settings.md#useLanguageServer) in your VS Code Go settings.
+To start using the language server, set [`"go.useLanguageServer": true`](settings.md#go.useLanguageServer) in your VS Code Go settings.
-You should see a prompt to install `gopls`. If you do not see a prompt, please run the `Go: Install/Update Tools` command and select `gopls`.
+You should see a prompt to install `gopls`. If you do not see a prompt, please run the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command and select `gopls`.
### Automatic updates
The `gopls` team releases new versions of `gopls` approximately once a month ([release notes](https://github.com/golang/go/issues/33030)). The Go extension will automatically detect that a new version has been released, and a pop-up will appear prompting you to update.
-If you would like to opt-out of these updates, set [`"go.useGoProxyToCheckForToolUpdates"`](settings.md#useGoProxyToCheckForToolUpdates) to `false`.
+If you would like to opt-out of these updates, set [`"go.useGoProxyToCheckForToolUpdates"`](settings.md#go.useGoProxyToCheckForToolUpdates) to `false`.
## Configuration
-There are a number of VS Code Go settings for controlling the language server. These include:
+There are a number of VS Code Go settings for controlling the language server.
-* [`"go.languageServerExperimentalFeatures"`](settings.md#languageServerExperimentalFeatures) allows you to disable certain features.
- * `"diagnostics": false` disables diagnostic warnings from `gopls`. You may want to disable these if you don't like the diagnostics changing as you type.
+* [`"go.languageServerExperimentalFeatures"`](settings.md#go.languageServerExperimentalFeatures) allows you to disable certain features.
+ * `"diagnostics": false` disables diagnostic warnings from `gopls`. You might want to disable these if you don't like the diagnostics changing as you type.
* `"documentLink": false` disables document links. The reason to disable these is explained in [golang/go#39065](https://github.com/golang/go/issues/39065): the Ctrl+Click shortcut for clicking on a link collides with the Ctrl+Click shortcut for go-to-definition.
-
- ```json5
- "go.languageServerExperimentalFeatures": {
- "diagnostics": false,
- "documentLink": false
- }
- ```
-
-* [`"go.languageServerFlags"`](settings.md#languageServerFlags) allows you to pass flags to the `gopls` process.
+* [`"go.languageServerFlags"`](settings.md#go.languageServerFlags) allows you to pass flags to the `gopls` process.
* The `-rpc.trace` flag enables verbose debug logging.
- ```json5
- "go.languageServerFlags": [
- "-rpc.trace"
- ]
- ```
-
### Ignored settings
A number of the extension's settings are not passed in to `gopls`. We are working on unifying all of the settings, but some may still be ignored. These include:
-* [`"go.buildFlags"`](settings.md#buildFlags)
-<!--TODO(rstambler): Complete this list.-->
+* [`"go.buildFlags"`](settings.md#go.buildFlags)
These configurations can be passed to `gopls` via your environment or the `gopls.env` setting. Learn more in the [`gopls` VS Code documentation](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md#build-tags).
### `gopls` settings block
-[`gopls`] exposes a lot more [additional configuration](https://github.com/golang/tools/blob/master/gopls/doc/settings.md). However, because [`gopls`] is in a state of rapid development and change, these settings change frequently. Therefore, we have not yet built these settings into the Go extension.
+`gopls` exposes much more [configuration](https://github.com/golang/tools/blob/master/gopls/doc/settings.md). However, because [`gopls`] is in a state of rapid development and change, these settings change frequently. Therefore, we have not yet built these settings into the Go extension.
As shown in the [`gopls` VS Code user guide](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md), you can still configure these settings through VS Code by adding a `"gopls"` block to your `settings.json` file (Command Palette -> Preferences: Open Settings (JSON)). **You will see an `Unknown Configuration Setting` warning, but the settings will still work.** Add any settings there, and `gopls` will warn you if they are incorrect, unknown, or deprecated.
diff --git a/docs/modules.md b/docs/modules.md
index 31ed4f2..899bb6b 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -1,6 +1,6 @@
# Modules
-This extension mostly supports [Go modules]. However, certain features have not been ported to work with modules. The reason for this is that the Go team is developing a language server, [gopls](gopls.md). This provides a comprehensive solution for [Go modules] support in all editors.
+This extension mostly supports [Go modules]. However, certain features have not been ported to work with modules. The reason for this is that the Go team is developing a language server, [`gopls`](gopls.md). This provides a comprehensive solution for [Go modules] support in all editors.
However, as described in the [language server documentation](gopls.md), `gopls` is still in an alpha state, so it is **not yet** the default in VS Code Go. We understand that many users will not want to use alpha software, so this document describes how this extension works with [Go modules], **without the language server**.
@@ -12,7 +12,6 @@
* [Formatting](#formatting)
* [References and rename](#references-and-rename)
* [Performance](#performance)
- * [Autocompletion](#autocompletion)
## Missing features
@@ -20,17 +19,15 @@
### Formatting
-The default [formatting](features.md#format-and-organize-imports) tool, [`goreturns`](tools.md#formatting), has not been ported to work with modules. As a result, you will need to change your [`"go.formatTool"`](settings.md#formatTool) setting for [formatting and import organization support](features.md#format-and-organize-imports). We recommend changing the value to `"goimports"` instead. Other options are also available, and you can read about them in the [format tools documentation](tools.md#formatting).
+The default [formatting](features.md#format-and-organize-imports) tool, [`goreturns`](tools.md#formatting), has not been ported to work with modules. As a result, you will need to change your [`"go.formatTool"`](settings.md#go.formatTool) setting for [formatting and import organization support](features.md#format-and-organize-imports). We recommend changing the value to `"goimports"` instead. Other options are also available, and you can read about them in the [format tools documentation](tools.md#formatting).
-<!--TODO(rstambler): I never thought about this before, but it seems like we should either change the default or do the port ourselves. I doubt it would take long.-->
-
-### [References](features.md#find-references) and [rename](tools.md#rename)
+### [References](features.md#find-references) and [rename](features.md#rename-symbol)
The tools that provide these two features, [`guru`](tools.md#guru) and [`gorename`](tools.md#gorename), have not been updated for Go modules. Instead, they will be replaced by [`gopls`](gopls.md).
## Performance
-[Go modules] introduced additional complexity to the way that Go tooling has to work. As a result, the performance of a number of tools is worse with modules enabled. Hopefully, you will not notice this too frequently.
+[Go modules] introduced additional complexity to Go tooling. As a result, the performance of a number of tools is worse with modules enabled. Hopefully, you will not notice this too frequently.
One case in which you may notice this is autocompletion. The best solution to this is to switch to [`gopls`](gopls.md), which makes use of an in-memory cache to provide results quickly.
diff --git a/docs/nightly.md b/docs/nightly.md
index e9ff468..b139d98 100644
--- a/docs/nightly.md
+++ b/docs/nightly.md
@@ -8,7 +8,7 @@
## Installation
-To use the [Go Nightly] extension (`golang.go-nightly`), you **must** first disable the standard Go extension (`golang.Go`) The two are not compatible and will cause conflicts if enabled simultaneously.
+To use the [Go Nightly] extension (`golang.go-nightly`), you **must** first disable the standard Go extension (`golang.go`). The two are not compatible and will cause conflicts if enabled simultaneously.
If you'd like to make a permanent switch, you can uninstall the Go extension.
@@ -24,12 +24,10 @@
## Testing pre-releases
-**Note**: Pre-releases are not yet available.
+Pre-releases of the Go extension will be made available on the [Releases page](https://github.com/golang/vscode-go/releases) on GitHub. These will be separate from the Go Nightly extension. If you would like to try a pre-release, follow these instructions:
-Pre-releases of the Go extension will be made available on the [Releases page](https://github.com/golang/vscode-go/releases/tag/latest) on GitHub. These will be separate from the Go Nightly extension. If you would like to try a pre-release, follow these instructions:
-
-1) Download the `.vsix` file from the [Releases page](https://github.com/golang/vscode-go/releases/tag/latest).
-2) Navigate to the Extensions view in VS Code (Ctrl+Shift+X). Click on the "..." in the top-right corner, select "Install from VSIX", and select `Go-latest.vsix`. Alternatively, you can run `code --install-extension Go-latest.vsix` or open the Command Palette and run the "Extensions: Install from VSIX..." command.
+1) Download the `.vsix` file from the [Releases page](https://github.com/golang/vscode-go/releases).
+2) Navigate to the Extensions view in VS Code (Ctrl+Shift+X). Click on the "..." in the top-right corner, select "Install from VSIX", and select the `.vsix` file you downloaded. Alternatively, you can run `code --install-extension Go-latest.vsix` or open the Command Palette and run the "Extensions: Install from VSIX..." command.
3) If prompted, reload VS Code.
**Note**: If you install an extension from a VSIX file, you will stop receiving automatic prompts when updates are released.
diff --git a/docs/nightly/README.md b/docs/nightly/README.md
index 20575aa..13a0c43 100644
--- a/docs/nightly/README.md
+++ b/docs/nightly/README.md
@@ -1,10 +1,10 @@
# Go Nightly for VS Code
> ### **ATTENTION: This is the *preview* version of the [VS Code Go extension](https://github.com/golang/vscode-go), used for early feedback and testing.**
-> It is published nightly and contains previews of new features and bug fixes that are still under review or being tested. Therefore, this extension can be broken or unstable at times. If you are looking for the stable version,
+> It is published nightly and contains previews of new features and bug fixes that are still under review or test. Therefore, this extension can be broken or unstable at times. If you are looking for the stable version,
please install [the default VS Code Go extension](https://marketplace.visualstudio.com/items?itemName=golang.go) instead.
>
-> **NOTE: The stable Go extension (`golang.Go`) cannot be used at the same time as the preview Go Nightly extension (`golang.go-nightly`)**. If you have installed both extensions, you **must disable or uninstall** one of them. For further guidance, read the [documentation on how to disable an extension](https://code.visualstudio.com/docs/editor/extension-gallery#_disable-an-extension).
+> **NOTE: The stable Go extension (`golang.go`) cannot be used at the same time as the preview Go Nightly extension (`golang.go-nightly`)**. If you have installed both extensions, you **must disable or uninstall** one of them. For further guidance, read the [documentation on how to disable an extension](https://code.visualstudio.com/docs/editor/extension-gallery#_disable-an-extension).
> ### **Differences between Go and Go Nightly**
>
diff --git a/docs/settings.md b/docs/settings.md
index 824d565..dd328a8 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -1,8 +1,10 @@
# Settings
-This extension is highly configurable, and as such, offers a number of settings. These can be configured by modifying your [User or Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings). To navigate to your settings, open the Command Palette (Ctrl+Shift+P) and search for "settings". The simplest way to modify your settings is through "Preferences: Open Settings (UI)".
+This extension is highly configurable, and as such, offers a number of settings. These can be configured by modifying your [User or Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings).
-**NOTE: Many of these settings don't apply if you are using [`gopls`](gopls.md). Learn more about `gopls`-specific settings in this [documentation](https://github.com/golang/tools/blob/master/gopls/doc/settings.md).**
+To navigate to your settings, open the Command Palette (Ctrl+Shift+P) and search for "settings". The simplest way to modify your settings is through "Preferences: Open Settings (UI)".
+
+**NOTE: Many of these settings don't apply if you are using [`gopls`](gopls.md). Learn more about [`gopls`-specific settings](gopls.md#ignored-settings).**
## Latest changes
@@ -39,28 +41,3 @@
### lintFlags
This setting can be used to pass additional flags to your lint tool of choice.
-
-Most linters can be configured via special configuration files, but you may still need to pass command-line flags. The configuration documentation for each supported linter is listed here:
-
-* [`staticcheck`](https://staticcheck.io/docs/#configuration)
-* [`golangci-lint`](https://golangci-lint.run/usage/configuration/)
-* [`revive`](https://github.com/mgechev/revive#command-line-flags)
-
-#### Examples
-
-Enable all [`golangci-lint`] linters and only show errors in new code:
-
-```json5
-"go.lintFlags": ["--enable-all", "--new"]
-```
-
-Configure `revive` to exclude `vendor` directories and apply extra configuration with a `config.toml` file:
-
-```json5
-"go.lintFlags": [
- "-exclude=vendor/...",
- "-config=${workspaceFolder}/config.toml"
-]
-```
-
-<!--TODO(rstambler): Automatically generate this list using the package.json.-->
diff --git a/docs/smoke-test.md b/docs/smoke-test.md
index 53ed227..f5486d2 100644
--- a/docs/smoke-test.md
+++ b/docs/smoke-test.md
@@ -4,10 +4,9 @@
## Set up
-First, clone the [golang.org/x/example](https://github.com/golang/example). At the time of writing (June 2020), this repository has not changed since 2017. If it has changed since, these steps may not be exactly reproducible and should be adjusted.
+First, clone [golang.org/x/example](https://github.com/golang/example). At the time of writing (June 2020), this repository has not changed since 2017. If it has changed since, these steps may not be exactly reproducible and should be adjusted.
-<!--TODO(rstambler): Maintain our own smoke tests, or add a go.mod file to this repository.-->
-For now, we smoke test the extension only in `GOPATH` mode.
+For now, we smoke test the extension only in [`GOPATH`](gopath.md) mode.
If it does not already exist:
@@ -36,7 +35,7 @@
## Test autocompletion
-<!--TODO(rstambler): We should require the user install another package in their GOPATH and expect unimported completions from that package.-->
+<!--TODO(rstambler): We should require the user to install another package in their GOPATH and expect unimported completions from that package.-->
1. Trigger autocompletion (Ctrl+Space) after `fmt.`.
2. Trigger autocompletion (Ctrl+Space) after `stringutil.`.
@@ -78,5 +77,3 @@
```
2. Rename `stringutil.Reverse`. `reverse.go` and `reverse_test.go` should be dirtied.
-
-<!--TODO(rstambler): Other features should also be tested. Not sure if this whole smoke test process is worth it or will ever be followed.-->
\ No newline at end of file
diff --git a/docs/tasks.md b/docs/tasks.md
index daf2373..90fc8e8 100644
--- a/docs/tasks.md
+++ b/docs/tasks.md
@@ -10,8 +10,6 @@
Replace the contents of this file with the following and adjust the tasks as needed.
-<!--TODO(rstambler): Can the extension just provide these default tasks?-->
-
```json5
{
"version": "2.0.0",
@@ -40,12 +38,12 @@
You can run these tasks via the `Tasks: Run Task` command or by using the Ctrl+Shift+B shortcut.
-You can also define additional tasks to run other commands, like `go generate`. Here's an example of a task to run only a specific test (`TestBlogUser`, in this case):
+You can also define additional tasks to run other commands, like `go generate`. Here's an example of a task to run only a specific test (`MyTestFunction`, in this case):
```json5
{
- "label": "Blog User test suite",
- "args": [ "test", "./...", "-test.run", "TestBlogUser"]
+ "label": "MyTestFunction",
+ "args": [ "test", "./...", "-test.run", "MyTestFunction"]
}
```
diff --git a/docs/testing.md b/docs/testing.md
index b9f28ae..cf66d5d 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -7,6 +7,8 @@
This is a temporary setup; once GCB fully supports our desired workflow, we plan to use only the GCB-based setup for CI.
+The [release of the Go Nightly](#nightly-release) extension is automated using GitHub Actions.
+
## Testing via GCB
This workflow is triggered for Gerrit CLs and for all commits merged into the master branch. Note that our main repository is [go.googlesource.com/vscode-go](https://go.googlesource.com/vscode-go), and
@@ -24,7 +26,7 @@
gcloud builds submit --config=build/cloudbuild.yaml
```
-In order to modify and rebuild the Docker container image, run:
+To modify and rebuild the Docker container image, run:
```bash
gcloud builds submit --config=build/cloudbuild.container.yaml
diff --git a/docs/tools.md b/docs/tools.md
index 203140e..a99ea96 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -4,14 +4,13 @@
Some of the features can be provided by multiple tools, and this can be configured through the extension's settings. For more details, see the [Documentation](#documentation), [Formatting](#formatting), and [Diagnostics](#diagnostics) sections below.
-<!--TODO(rstambler): Clarify which tools are still needed with gopls.-->
-**NOTE: If you are using the language server, [`gopls`], then most of the below tools are not needed. We strongly recommend using [`gopls`] if you are using Go modules, as it performs better.**
+**NOTE: If you are using the language server, [`gopls`], most of the tools below are not needed.**
## Installation
-These tools will be installed by default when you install the extension. You can manually install or update all of these tools by running the `Go: Install/Update Tools` command. If any tools are missing, you will see an "Analysis Tools Missing" warning in the bottom-right corner of the editor, which will prompt you to install these tools.
+Tools will be installed by default when you install the extension. You can also manually install or update all of these tools by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command. If any tools are missing, you will see an `Analysis Tools Missing` warning in the bottom-right corner of the editor, which will prompt you to install these tools.
-VS Code Go will install the tools to your `GOPATH` by default, but the tools will also be found if they are on your `PATH`. If you wish to use a separate `GOPATH` for tools only, you can configure this via the [`"go.toolsGopath"`](settings.md#toolsGopath) setting.
+VS Code Go will install the tools to your `GOPATH` by default, but the tools will also be found if they are on your `PATH`. Read our [`GOPATH` documentation](gopath.md#install-tools-to-a-separate-gobin) if you wish to learn about storing tools in a separate directory.
## Table of Contents
@@ -49,22 +48,11 @@
This extension requires you to install the Go toolchain, meaning that you have the `go` command on your [`PATH`](https://en.wikipedia.org/wiki/PATH_(variable)). To do this, follow [the Go installation guide](https://golang.org/doc/install).
-The [build-on-save](features.md#build-on-save) and [vet-on-save](features.md#vet-on-save) features are provided by the `go build` and `go vet` commands.
+The [build-on-save](features.md#build-errors) and [vet-on-save](features.md#vet-errors) features are provided by the `go build` and `go vet` commands.
### `gocode`
-Code completion is provided by `gocode`. It is the only tool that runs as a server. This enables it to provide completions faster, since a new process isn't starting per-keystroke. As a result, it is also easier to troubleshoot.
-
-To restart `gocode`, run `gocode close` on the command-line.
-
-To see `gocode`'s internals for debugging purposes, run:
-
-```bash
-gocode close
-gocode -s -debug
-```
-
-Then, type and trigger completions in your VS Code window as usual. You should see information printed in your terminal window.
+Code completion is provided by `gocode`. It is the only tool that runs as a server. This enables it to provide completions faster, since a new process isn't starting per-keystroke.
Different versions of `gocode` are used depending on your version of Go.
@@ -73,6 +61,8 @@
* Go 1.11 and above, with modules enabled: [stamblerre/gocode](https://github.com/stamblerre/gocode)
* This version of `gocode` does not have any caching, so if you find it slow, consider using [gopls] instead.
+Learn how to [troubleshoot `gocode`](troubleshooting.md#autocompletion).
+
### [`gopkgs`](https://pkg.go.dev/github.com/uudashr/gopkgs?tab=overview)
This tool provides autocompletion for unimported packages.
@@ -83,13 +73,13 @@
### [`go-symbols`](https://pkg.go.dev/github.com/acroca/go-symbols?tab=overview)
-This tool provides the [go to symbol](#go-to-symbol) in workspace feature.
+This tool provides the [go to symbol](features.md#go-to-symbol) in workspace feature.
### [`guru`](https://pkg.go.dev/golang.org/x/tools/cmd/guru?tab=doc)
This tool provides the [find references](features.md#find-references) and [find interface implementations](features.md#find-interface-implementations) features.
-It can also be used to provide the [go to definition](features.md#go-to-definition) via the [`"go.docsTool"`](settings.md#docsTool) setting (see [Customization](#Customization)).
+It can also be used to provide the [go to definition](features.md#go-to-definition) via the [`"go.docsTool"`](settings.md#go.docsTool) setting.
`guru` does not have support for Go modules, so we recommend using [`gopls`] for those features instead.
@@ -127,7 +117,7 @@
### [`fillstruct`](https://github.com/davidrjenni/reftools/tree/master/cmd/fillstruct)
-This tool provides support the [`Go: Fill struct`](features.md#fill-struct) command.
+This tool provides support the [`Go: Fill struct`](features.md#fill-struct-literals) command.
### Documentation
@@ -135,13 +125,13 @@
If `gogetdoc` does not work for you, a combination of the [`godef`] and [`godoc`] tools can be used. [`guru`](#guru) can also be used, but only for the [go to definition](features.md#go-to-definition) behavior.
-Configure this via the [`"go.docsTool"`](settings.md#docsTool) setting.
+Configure this via the [`"go.docsTool"`](settings.md#go.docsTool) setting.
### Formatting
Formatting tools are used by the [formatting and import organization](features.md#format-and-organize-imports) features.
-[`goreturns`] is used by default. It formats the file according to the industry standard [`gofmt`] style, organizes imports, and fills in default return values for functions. Other tools can be used for formatting instead; this can be configured with the [`"go.formatTool"`](settings.md#formatTool) setting.
+[`goreturns`] is used by default. It formats the file according to the industry standard [`gofmt`] style, organizes imports, and fills in default return values for functions. Other tools can be used for formatting instead; this can be configured with the [`"go.go.formatTool"`](settings.md#formatTool) setting.
**NOTE: [`goreturns`] does not have support for Go modules, so we recommend using [`goimports`] or [`gopls`] instead.**
@@ -155,17 +145,40 @@
Diagnostic tools are used to surface errors and warnings in your code when you save your file or as you type.
-By default, [`gotype-live`], `go vet`, and [`golint`] are used to provide [build](#build-on-save), [vet](#vet-on-save), and [lint](#lint-on-save) errors. [`gotype-live`] provides build errors as you type, while `go build` can be used to show build errors only on save.
+By default, [`gotype-live`], [`go vet`], and [`golint`] are used to provide [build](features.md#build-errors), [vet](features.md#vet-errors), and [lint](features.md#lint-errors) errors. [`gotype-live`] provides build errors as you type, while `go build` can be used to show build errors only on save.
**NOTE: [`gotype-live`] does not work with modules, so if you are using modules, we recommend using [`gopls`] instead.**
The command used to provide build errors on-save is `go build -i -o` or `go test -i -c -o` (for test files). The binary generated by the build is written to a temporary location.
-Other lint tools can be used instead of [`golint`] by configuring the [`"go.lintTool"`](settings.md#lintTool) setting. Other options include:
+Other lint tools can be used instead of [`golint`] by configuring the [`"go.lintTool"`](settings.md#go.lintTool) setting. Other options include:
-* [`staticcheck`]: This tool provides a great deal of useful checks that are not provided by `golint`. See the full list at [staticcheck.io/docs/checks](https://staticcheck.io/docs/checks). It is also officially supported by the [Go team at Google](https://staticcheck.io/sponsors).
+* [`staticcheck`]: This tool provides a great deal of useful checks that are not provided by [`golint`]. See the full list at [staticcheck.io/docs/checks](https://staticcheck.io/docs/checks). It is also officially supported by the [Go team at Google](https://staticcheck.io/sponsors).
* [`golangci-lint`]: This tool combines a number of existing lint tools, including [staticcheck](#staticcheck), into one interface.
-* [`revive`]: This tool is an enhancement on top of [`golint`](#golint), and it provides additional checks.
+* [`revive`]: This tool is an enhancement on top of [`golint`], and it provides additional checks.
+
+You can use the [`"go.lintFlags"`](settings.md#go.lintFlags) setting to further configure your linter of choice. Most linters can be configured via special configuration files, but you may still need to pass these command-line flags. The configuration documentation for each supported linter is listed here:
+
+* [`staticcheck`](https://staticcheck.io/docs/#configuration)
+* [`golangci-lint`](https://golangci-lint.run/usage/configuration/)
+* [`revive`](https://github.com/mgechev/revive#command-line-flags)
+
+#### Examples
+
+Enable all [`golangci-lint`] linters and only show errors in new code:
+
+```json5
+"go.lintFlags": ["--enable-all", "--new"]
+```
+
+Configure `revive` to exclude `vendor` directories and apply extra configuration with a `config.toml` file:
+
+```json5
+"go.lintFlags": [
+ "-exclude=vendor/...",
+ "-config=${workspaceFolder}/config.toml"
+]
+```
[`gogetdoc`]: https://pkg.go.dev/github.com/zmb3/gogetdoc?tab=overview
[`godef`]: https://pkg.go.dev/github.com/rogpeppe/godef?tab=doc
@@ -180,3 +193,4 @@
[`golangci-lint`]: https://golangci-lint.run/
[`revive`]: https://pkg.go.dev/github.com/mgechev/revive?tab=overview
[`gopls`]: gopls.md
+[`go vet`]: https://golang.org/cmd/vet/
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 2b61c1f..3b111af 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,15 +1,15 @@
# Troubleshooting
-Read this document when you encounter a problem with this extension. Still, remember that this extension has many different features and moving parts. This document can provide guidance, but many cases are not covered here.
+Read this document when you encounter a problem with this extension. It can provide guidance, but many cases are not covered here.
-If you are unable to resolve the problem after following the advice on this page, please take a look at the current [open issues](https:/github.com/golang/vscode-go/issues) to see if your issue has already been reported. If not, please do not hesitate to [ask for help](#ask-for-help).
+If you are unable to resolve the problem after following the advice on this page, please take a look at the current [open issues](https://github.com/golang/vscode-go/issues) to see if your issue has already been reported. If not, please do not hesitate to [ask for help](#ask-for-help).
-The guidance offered here is applicable in most situations, but **note that [debugging](debugging.md#troubleshooting) and [`gopls`](gopls.md) also have their own troubleshooting documentation.**
+**NOTE: [Debugging](debugging.md#troubleshooting) and [`gopls`](gopls.md) also have their own troubleshooting documentation.**
## Overview
-* [Check Known Issues](#check-known-issues)
-* [Check your set up](#check-your-set-up)
+* [Check known issues](#check-known-issues)
+* [Check your setup](#check-your-setup)
* [Environment variables](#environment-variables)
* [Update tools](#update-tools)
* [If tools fail to install or update](#if-tools-fail-to-install-or-update)
@@ -23,25 +23,15 @@
* [Known Issues](#known-issues)
* [Ask for help](#ask-for-help)
-### Check [Known Issues](#known-issues)
+### Check [known issues](#known-issues)
A [list of known issues](#known-issues) is available at the bottom of this page. Take a look and see if you've encountered one of these.
-### Look for error messages
+### Check your setup
-Start off by opening the Output pane (Ctrl+Shift+U). On the right side, open the drop-down titled "Tasks". Any item that starts with "Go" is related to this extension. Browse through these output channels and make note of any error messages.
+First, make sure you understand the difference between [`GOPATH`](gopath.md) and [module](modules.md) modes and know which mode you are using. Run `go version` and `go env` in the [integrated terminal] to check that your environment is configured as you expect.
-You can also look directly in the logs of the Extension Host by selecting `Log (Extension Host)`. These may contain a lot of unrelated information, but they may prove useful. If you are trying to get the logs for a specific operation, like go to definition, clear the logs (Clear Output button on the right side), and perform the operation.
-
-Errors may also be logged to the Developer Tools console. These errors may be more difficult to parse, but you can take a look at them by running the `Developer: Toggle Developer Tools` command from the Command Palette (Ctrl+Shift+P).
-
-### Check your set-up
-
-First, make sure you understand the difference between [`GOPATH`](gopath.md) and [module](modules.md) modes and know which mode you are using. You can run `go version` and `go env` in the [integrated terminal] is configured as you expect.
-
-<!--TODO(rstambler): Locate Configured Go Tools should also print `go env` I think.-->
-
-This extension supports a few meta-commands that can be used for investigation. Try running `Go: Locate Configured Go Tools`. The output should look like:
+This extension supports a few meta-commands that can be used for investigation. Try running [`Go: Locate Configured Go Tools`](commands.md#go-locate-configured-go-tools). The output should look like:
```bash
Checking configured tools....
@@ -71,20 +61,20 @@
gopls: /path/to/bin/gopls installed
```
-If your `GOPATH` or `GOROOT` is undefined, that may indicate a problem. Read more about [setting up your `GOPATH`](gopath.md). A missing `GOROOT` means that you haven't installed Go correctly. This topic is covered in the [Getting Started guide](../README.md#install-go).
+If your `GOPATH` or `GOROOT` is undefined, that may indicate a problem. Read more about [setting up your `GOPATH`](gopath.md#setting-gopath). A missing `GOROOT` means that you haven't installed Go correctly. This topic is covered in the [getting started guide](../README.md#install-go).
-If one of the tools (`gocode`, `gopkgs`, etc.) is not installed, this may also indicate a problem. Take a look at the [list of tools](tools.md) required by this extension. If the missing tool provides the feature you're looking for, that might be the issue. You can install or update tools by running the `Go: Install/Update Tools` command.
+If one of the tools (`gocode`, `gopkgs`, etc.) is not installed, this may also indicate a problem. Take a look at the [list of tools](tools.md) required by this extension. If the missing tool provides the feature you're looking for, that might be the issue. You can install or update tools by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command.
Finally, take a look at your settings in the JSON form (Ctrl+Shift+P -> Preferences: Open Settings (JSON)). This is an easier way to quickly grasp what non-default configurations you have.
Common culprits include:
-* [`go.inferGopath`](settings.md#inferGopath)
-* [`go.toolsGopath`](settings.md#inferGopath)
-* [`go.alternateTools`](settings.md#inferGopath)
-* [`go.useLanguageServer`](settings.md#useLanguageServer)
+* [`go.inferGopath`](settings.md#go.inferGopath)
+* [`go.toolsGopath`](settings.md#go.toolsGopath)
+* [`go.alternateTools`](settings.md#go.alternateTools)
+* [`go.useLanguageServer`](settings.md#go.useLanguageServer)
-Read up on those settings, as well as all of the other [available settings](settings.md). Make sure that you have configured the right settings.
+Read up on those settings, as well as all of the other [available settings](settings.md).
If you are using the language server, please see the language server's [troubleshooting guide](gopls.md).
@@ -92,33 +82,41 @@
Note that extensions run in a separate process from the [integrated terminal] and the rest of the VS Code window. Therefore, environment variables set specifically in the [integrated terminal] are not visible to the extensions.
-Instead, set the environment variables in your terminal before you launch VS Code. Or, set environment variables globally in your configuration (in a `.bash_profile`, for example). You can also set environment variables for only the Go extension by adding them to [`go.toolsEnvVars`](settings.md#toolsEnvVars). Other settings are available to override specific variables, like your `GOPATH`, which can be set through the [`go.gopath`](settings.md#gopath) setting as well.
+Instead, set the environment variables in your terminal before you launch VS Code. Or, set environment variables globally in your configuration (in a `.bash_profile`, for example). You can also set environment variables for only the Go extension by adding them to [`go.toolsEnvVars`](settings.md#go.toolsEnvVars). Other settings are available to override specific variables, like your `GOPATH`, which can be set through the [`go.gopath`](settings.md#go.gopath) setting as well.
+
+### Look for error messages
+
+Start off by opening the Output pane (Ctrl+Shift+U). On the right side, open the drop-down titled "Tasks". Any item that starts with "Go" is related to this extension. Browse through these output channels and make note of any error messages.
+
+You can also look directly in the logs of the Extension Host by selecting `Log (Extension Host)`. These may contain a lot of unrelated information, but they may prove useful. If you are trying to get the logs for a specific operation, like go to definition, clear the logs (Clear Output button on the right side), and perform the operation.
+
+Errors may also be logged to the Developer Tools console. These errors may be more difficult to parse, but you can take a look at them by running the `Developer: Toggle Developer Tools` command from the Command Palette (Ctrl+Shift+P).
### Update tools
-It's possible that you are using an outdated version of a tool, so the bug you are encountering may have already been fixed. You can update all tools at once by running the `Go: Install/Update Tools` command.
+It's possible that you are using an outdated version of a tool, so the bug you are encountering may have already been fixed. You can update all tools at once by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command.
If you would prefer to update only a single tool, you can use the same command, but pick the correct tool. To learn which tool corresponds to the broken feature, read the [Features](features.md) and [Tools](tools.md) documentation pages. [Features](features.md) describes functionality in detail and lists which tool provides that functionality, while [Tools](tools.md) is the reverse, describing each tool and then listing which features it provides.
### If tools fail to install or update
-It's possible that the tool installation or update will itself fail. Error messages should be printed in the output, which will hopefully guide you. If not, you can follow these suggestions.
+It's possible that the tool installation or update will itself fail. Error messages should be printed in the output, which will hopefully guide you.
Try cleaning your module cache (`go clean -modcache`) and installing once again.
-If you are using Go 1.10 or below, something may have gone wrong with the repository that contains the tool on your machine. Try deleting the directory that contains the tool and installing again. The directory will be in your `$GOPATH/src/`. The name of the directory will be the name of the repository in which the tool is hosted; it's usually something like `github.com/stamblerre/gocode`. Note that, if you have configured the [`go.toolsGopath`](settings.md#toolsGopath), you should look in that directory.
+If you are using Go 1.10 or below, something may have gone wrong with the repository that contains the tool on your machine. Try deleting the directory that contains the tool and installing again. The directory will be in your `$GOPATH/src/`. The name of the directory will be the name of the repository in which the tool is hosted; it's usually something like `github.com/stamblerre/gocode`. Note that, if you have configured the [`go.toolsGopath`](settings.md#go.toolsGopath), you should look in that directory.
-If that doesn't work, something may have gone wrong in the repository that contains the tool. Check if there are any issues filed in that repository. If not, please file an issue in that repository and let us know by [filing an issue](https:/github.com/golang/vscode-go/issues/new/choose) in the VS Code Go repository as well.
+If that doesn't work, there may be a problem with the tool itself. Check if there are any issues filed in the tool's repository. If not, please file an issue in that repository and let us know by [filing an issue](https:/github.com/golang/vscode-go/issues/new/choose) in the VS Code Go repository as well.
## Investigate
-Issues in certain parts of the extension, specifically [debugging](debugging.md#troubleshooting) and the [language server](gopls.md#troubleshooting), are described in more depth on other pages. Please take a look at those specific guides.
+Issues in certain parts of the extension, specifically [debugging](debugging.md#troubleshooting) and the [language server](gopls.md), are described in more depth on other pages. Please take a look at those specific guides.
Other issues may be caused by other command-line tools. As mentioned above, to learn which tool corresponds to the broken feature, read the [Features](features.md) and [Tools](tools.md) documentation pages. [Features](features.md) describes functionality in detail and lists which tool provides that functionality, while [Tools](tools.md) is the reverse, describing each tool and then listing which features it provides.
Once you've identified the correct tool, make sure it works for you on the command-line. Read the documentation and usage guide for the tool and try running it manually. Most tools may require you to provide a line and column number or byte offset in a file.
-If the tool works correctly on the command-line, then the issue is in the [VS Code Go extension]. In that case, please [file an issue].
+If the tool works correctly on the command-line, then the issue is in this extension. In that case, please [file an issue].
If the tool does not work correctly on the command-line, that means there is an issue in the tool. In that case, please file an issue in the GitHub repository of the tool itself.
@@ -128,9 +126,9 @@
The following only applies if you are **not** using the language server. If you are, see [the `gopls` troubleshooting guide](gopls.md).
-First, make sure you have already followed the [investigation steps](#investigate) above. The tool that provides autocompletion is called [`gocode`](tools.md#gocode), so try checking error logs and updating [`gocode`](tools.md#gocode). If you are using [Go modules], the binary on your machine will be called `gocode-gomod`, not `gocode`, as the extension uses a different version of `gocode` for modules.
+The tool that provides autocompletion is called [`gocode`](tools.md#gocode), so try checking error logs and updating [`gocode`](tools.md#gocode). If you are using [Go modules], the binary on your machine will be called `gocode-gomod`, not `gocode`, as the extension uses a different version of `gocode` for modules.
-Next, make sure that the package you are trying to complete has been built at least once. You can do this by either running `Go: Build Current Package` or by running `go install` on the command-line. If you have enabled [`go.buildOnSave`](settings.md#buildOnSave) or [`go.gocodeAutobuild`](settings.md#gocodeAutobuild) this should happen automatically.
+Next, make sure that the package you are trying to complete has been built at least once. You can do this by either running [`Go: Build Current Package`](commands.md#go-build-current-package) or by running `go install` on the command-line. If you have enabled [`go.buildOnSave`](settings.md#go.buildOnSave) or [`go.gocodeAutobuild`](settings.md#go.gocodeAutobuild), this should happen automatically.
If you have noticed that your autocompletion results are not missing, but simply out-of date, check the value of your [`"go.buildOnSave"`](settings.md#buildOnSave) setting. If it is `"off"`, then you may not get fresh results your dependencies. You can rebuild your dependencies manually by running `go install`.
@@ -216,11 +214,11 @@
Any errors marked by red squiggles are build errors. These indicate that your code will not compile. If you think these errors are incorrect, try checking on the command-line by running `go build` or `go test`.
-If it does, try copying the exact command used by VS Code Go uses. You can find it by navigating to the output pane (Ctrl+Shift+P -> `View: Toggle Output`). Choose the `Go` output channel from the Tasks drop-down in the top-right corner. This will show the exact command VS Code ran. Copy and run it.
+If the build commands succeed, try copying the exact command used by VS Code Go. You can find it by navigating to the output pane (Ctrl+Shift+P -> `View: Toggle Output`). Choose the `Go` output channel from the Tasks drop-down in the top-right corner. This will show the exact command VS Code ran. Copy and run it.
-If you see the same errors, you may have misconfigured your project. Learn more about how to do this correctly in [Set up your environment](../README.md#set-up-your-environment).
+If you see the same errors, you may have misconfigured your project. Learn more about how to do this correctly in [set up your environment](../README.md#set-up-your-environment).
-If the command runs fine on the command-line, it's possible you've misconfigured something in your VS Code Go environment, such as your [`GOPATH`](gopath.md). Review the [Check your set-up](#check-your-set-up), and if the issue still persists, please [file an issue].
+If the command runs fine on the command-line, it's possible you've misconfigured something in your VS Code Go environment, such as your [`GOPATH`](gopath.md). Review [check your set-up](#check-your-set-up), and if the issue still persists, please [file an issue].
## Ask for help
@@ -228,7 +226,7 @@
Reach out to the VS Code Go maintainers by:
-* [Filing an issue](https:/github.com/golang/vscode-go/issues/new/choose)
+* [Filing an issue](https://github.com/golang/vscode-go/issues/new/choose)
* Asking a question on the `#vscode` channel of the [Gophers Slack]
## Known Issues
@@ -237,7 +235,7 @@
Take a look at the suggestions on [Microsoft/vscode-go#3179](https://github.com/microsoft/vscode-go/issues/3179#issue-600430641). If you still cannot resolve the problem, please [file an issue].
-[Gophers Slack]: https:/gophers.slack.com/
-[file an issue]: https:/github.com/golang/vscode-go/issues/new/choose
+[Gophers Slack]: https://gophers.slack.com/
+[file an issue]: https://github.com/golang/vscode-go/issues/new/choose
[Go modules]: https://blog.golang.org/using-go-modules
[integrated terminal]: https://code.visualstudio.com/docs/editor/integrated-terminal
diff --git a/smoke-test.md b/smoke-test.md
deleted file mode 100644
index 53ed227..0000000
--- a/smoke-test.md
+++ /dev/null
@@ -1,82 +0,0 @@
-# Smoke Test
-
-Before releasing a new version of the extension, please run the following smoke test to make sure that all features are working.
-
-## Set up
-
-First, clone the [golang.org/x/example](https://github.com/golang/example). At the time of writing (June 2020), this repository has not changed since 2017. If it has changed since, these steps may not be exactly reproducible and should be adjusted.
-
-<!--TODO(rstambler): Maintain our own smoke tests, or add a go.mod file to this repository.-->
-For now, we smoke test the extension only in `GOPATH` mode.
-
-If it does not already exist:
-
-```bash
-mkdir $GOPATH/src/github.com/golang
-```
-
-Then,
-
-```bash
-cd $GOPATH/src/github.com/golang
-git clone https://github.com/golang/example
-cd example
-```
-
-Next, [build and sideload the modified Go extension](contributing.md#sideload) and open the `example/hello` directory. Open `hello.go`.
-
-## Test code navigation
-
-1. Go to definition on `fmt.Println`.
-2. Go to definition on `stringutil.Reverse`.
-3. Find all references of `fmt.Println`.
-4. Find all references of `stringutil.Reverse`.
-5. Hover over `fmt.Println`.
-6. Hover over `stringutil.Reverse`.
-
-## Test autocompletion
-
-<!--TODO(rstambler): We should require the user install another package in their GOPATH and expect unimported completions from that package.-->
-
-1. Trigger autocompletion (Ctrl+Space) after `fmt.`.
-2. Trigger autocompletion (Ctrl+Space) after `stringutil.`.
-3. Enter a newline in the `main` function and type `fmt.`.
-4. Enter a newline in the `main` function and type `parser.`. Expect suggestions from the unimported standard library `go/parser` package.
-5. Enter a newline in the `main` function and type `fmt.`. Select the `fmt.Println` completion and observe the outcome. Toggle the `go.useCodeSnippetsOnFunctionSuggest` setting to ensure that placeholders are provided.
-6. Test signature help by manually triggering it (Ctrl+Shift+Space) while completing `fmt.Println`.
-7. Test signature help by manually triggering it (Ctrl+Shift+Space) while completing `stringutil.Reverse`.
-
-## Test diagnostics
-
-Enable `go.buildOnSave`, `go.vetOnSave`, and `go.lintOnSave`.
-
-1. Add `var x int` to the `main` function and expect a build diagnostic.
-2. Add `fmt.Printf("hi", 1)` and expect a vet diagnostic.
-3. Add the following function to the bottom of the file and expect a lint diagnostic.
-
- ```go
- // Hello is hi.
- func Hi() {}
- ```
-
-You can also try toggling the `"package"` and `"workspace"` configurations for these settings.
-
-## Test formatting and import organization
-
-1. Hit enter 3 times in the `main` function and save. Expect formatting to remove all but one line.
-2. Remove the `"fmt"` import. Save and expect it to return.
-3. Remove the `"github.com/golang/example/stringutil"` import. Save and expect it to return.
-4. Confirm that the `Go: Add Import` command works (add `"archive/tar"`).
-
-## Test renaming
-
-1. Add the following to the `main` function, then rename `x` to `y`.
-
- ```go
- var x int
- fmt.Println(x)
- ```
-
-2. Rename `stringutil.Reverse`. `reverse.go` and `reverse_test.go` should be dirtied.
-
-<!--TODO(rstambler): Other features should also be tested. Not sure if this whole smoke test process is worth it or will ever be followed.-->
\ No newline at end of file
