README.md: rewrite assuming gopls is on by default
Also upload the tool installation screenshot (gif)
Updated docs/tools.md to focus on modern tools and moved legacy tools to the bottom.
Deleted docs/gopls.md because the contents are obsolete or moved to docs/tools.md and README.md.
Change-Id: Ib8051c66fa15be0e6557d7d8dc36d99ac383aea6
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/284584
Trust: Hyang-Ah Hana Kim <hyangah@gmail.com>
Run-TryBot: Hyang-Ah Hana Kim <hyangah@gmail.com>
Reviewed-by: Rebecca Stambler <rstambler@golang.org>
diff --git a/README.md b/README.md
index d89f40b..45ad02a 100644
--- a/README.md
+++ b/README.md
@@ -4,119 +4,105 @@
<!--TODO: We should add a badge for the build status or link to the build dashboard.-->
-This extension provides rich language support for the [Go programming language](https://golang.org/) in VS Code.
+[The VS Code Go extension](https://marketplace.visualstudio.com/items?itemName=golang.go) provides rich language support for the [Go programming language](https://golang.org/).
-Take a look at the [Changelog](CHANGELOG.md) to learn about new features.
-
-> 📣 We will enable the language server ([`gopls`](docs/gopls.md)) by default in the end of Jan 2021. The language server
-> provides language features like intellisense, formatting, refactoring, analysis and many more.
+> 📣 We will enable the language server ([`gopls`]) by default in the end of Jan 2021.
> We recommend switching to the language server now (`"go.useLanguageServer": true`) to confirm it works well for you.
> Please [file a new issue](https://github.com/golang/vscode-go/issues/new/choose) if you notice bugs or missing features.
-## Overview
+## Quick Start
-* [Getting started](#getting-started)
-* [Support for Go modules](#support-for-go-modules)
-* [Features](#features)
- * [Debugging](#debugging)
-* [Customization](#customization)
- * [Linter](#linter)
- * [GOPATH](#gopath)
-* [Language server](#language-server)
-* [Troubleshooting](docs/troubleshooting.md)
-* [Ask for help](#ask-for-help)
-* [Preview version](#preview-version)
-* [Contributing](#contributing)
+Welcome! 👋🏻<br/>
+Whether you are new to Go or an experienced Go developer, we hope this extension fits your needs and enhances your development experience.
-## Getting started
+- **Step 1.** If you haven't done so already, install [Go](https://golang.org) and the [VS Code Go extension](https://marketplace.visualstudio.com/items?itemName=golang.go).
+ - [Go installation guide](https://golang.org/doc/install). This extension works best with Go 1.14+.
+ - [Manage extensions in VS Code](https://code.visualstudio.com/docs/editor/extension-gallery)
+- **Step 2.** To activate the extension, open any directory or workspace containing Go code. Once activated, the [Go status bar](docs/ui.md) will appear in the bottom left corner of the window and show the recognized Go version.
+- **Step 3.** The extension depends on [a set of extra command-line tools](#tools). If they are missing, the extension will show the "⚠️ Analysis Tools Missing" warning. Click the notification to complete the installation.
-Welcome! Whether you are new to Go or an experienced Go developer, we hope this extension will fit your needs and enhance your development experience.
+<p align="center"><img src="docs/images/installtools.gif" width=75%></img>
+<br/><em>(Install Missing Tools)</em>
+</p>
-### Install Go
+You are ready to Go :-) 🎉🎉🎉
-Before you start coding, make sure that you have already installed Go, as explained in the [Go installation guide](https://golang.org/doc/install).
+Please be sure to learn more about many [features](#features) of this extension as well as how to [customize](#customization) them. Take a look at [Troubleshooting](docs/troubleshooting.md) and [Help](#ask-for-help) for further guidance.
-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.
+If you are new to Go, [this article](https://golang.org/doc/code.html) provides the overview on go code organization and basic `go` commands. The recent [Go open source live video](https://opensourcelive.withgoogle.com/events/go/watch?talk=session3) featured VS Code Go and demonstrated how other Gophers use the features to enhance their Go development workflow.
-### Set up your environment
+## Features
-Read about [Go code organization](https://golang.org/doc/code.html) to learn how to configure your environment. This extension works in both [GOPATH](docs/gopath.md) and [module](docs/modules.md) modes.
-We suggest using modules, as they are the new standard and become default from go 1.16 (to be released in early 2021).
+This extension provides many 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 [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. See the [full feature breakdown](docs/features.md) for more details and to learn how to tune the behavior.
-Here are some additional resources for learning about how to set up your Go project:
+<p align=center><img src="docs/images/completion-signature-help.gif" width=75%></img>
+<br/><em>(Code completion and Signature Help)</em>
+</p>
-* [Using Go modules](https://blog.golang.org/using-go-modules)
-* [Modules wiki](https://github.com/golang/go/wiki/Modules)
-* [GOPATH](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable)
+In addition to integrated editing features, the extension provides several commands for working with Go files. You can access any of these by opening the Command Palette (`Ctrl+Shift+P` on Linux/Windows and `Cmd+Shift+P` on Mac), and then typing in the command name. See the [full list of commands](docs/commands.md#detailed-list) provided by the extension.
-**NOTE: If you are using modules, we recommend using the Go [language server](#language-server), which is explained below.**
+<p align=center><img src="docs/images/toggletestfile.gif" width=75%></img>
+<br/><em>(Toggle Test File)</em></p>
+**⚠️ Note**: the default syntax highlighting for Go files is provided by the [TextMate rule](https://github.com/jeff-hykin/better-go-syntax) embedded in VS Code, not by this extension.
-### Install the extension
+## Tools
-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`).
+The extension uses a few command-line tools developed by the Go community. In particular, `go`, `gopls`, and `dlv` are the main tools that implement build/test, language features, and debugging functionalities of this extension. See [Tools](docs/tools.md) for the full list of tools the extension depends on.
-### Activate the Go extension
+In order to locate the command-line tools, the extension searches `$GOPATH/bin` and directories specified in the `PATH` environment variable (or `Path` in Windows) with which the VS Code process has started. If the tools are not found, the extension will prompt you to install the missing tools and show the "⚠️ Analysis Tools Missing" warning in the bottom right corner. Please install them by responding to the warning notification, or by manually running the `Go: Install/Update Go Tools` command. The extension will run the [`go get`](https://golang.org/cmd/go) command to install them.
-To activate the extension, open any directory or workspace containing Go code.
+## Setting up your workspace
-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.
+[Modules](https://golang.org/ref/mod) are how Go manages the versions and dependencies in the recent versions of Go. Modules replace the old `GOPATH`-based approach to specifying which source files are used in a given build, and they are the default build mode after go1.16. While this extension continues to support both Go modules and `GOPATH`-mode, we highly recommend Go development in module mode. If you are working on existing projects, please consider migrating to modules.
-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.
-
-When the extension is active, you should see the [Go status bar](docs/ui.md) in the bottom left corner.
-
-### Start coding
-
-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 [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 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](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. 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#detailed-list) provided by the extension.
-
-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 a comprehensive overview of how to debug your Go programs, please see the [debugging guide](docs/debugging.md).
+Unlike the traditional `GOPATH`-mode, module mode does not require the workspace to be under `GOPATH` nor to use a specific structure. A module is defined by a tree of Go source files with a `go.mod` file in the tree's root directory. Your project may involve one or more modules. If you are working with multiple modules or uncommon project layouts, you will need to specifically configure your workspace, so features like references can work across modules. Please see the [Workspace document](https://github.com/golang/tools/blob/master/gopls/doc/workspace.md) for information on supported workspace layouts.
## Customization
-This extension needs no configuration; it works out of the box. However, you may wish to modify settings to adjust your experience.
+The extension needs no configuration and should work out of the box. However, you may wish to modify settings to meet your needs. Please see the [Settings documentation](docs/settings.md) for the comprehensive list of extension configuration options.
-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.
+### Choosing a different version of Go
-### [Linter](docs/tools.md#diagnostics)
+The extension chooses the `go` command from the `$PATH` (or `$Path`) environment variable by default. You can configure this extension to choose a different version of Go with one of the following options.
-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`].
+ - (Preferred) Adjust your `$PATH` or `$Path` environment variable, and *open VS Code with the adjusted environment* variable, or
+ - Use the Go extension's `"Go: Choose Go Environment"` command that opens a [menu](docs/ui.md) to change the `go` version, or
+ - Use the `"go.alternateTools"` settings and specify the absolute path to the `go` command.
+ ```
+ "go.alternateTools": { "go": "/path/to/go/command" }
+ ```
-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).
+**note**: For historical reasons, some users use the `"go.goroot"` settings or the `GOROOT` environment variable to select the Go SDK location. With the recent versions of Go, that's unnecessary in most cases.
-### [GOPATH](docs/gopath.md)
+### Configuring the installation of command-line tools
-Advanced users may want to set different `GOPATH`s for different projects or install the Go tools to a different `GOPATH`. This is possible and explained in the [`GOPATH documentation`](docs/gopath.md).
+`Go: Install/Update Tools` command uses the `go get` command to download and install requested tools. By default, `go get` will install the compiled tools in one of the following directories.
+ - the directory the `$GOBIN` environment variable specifies, or
+ - the `bin` directory under the first `$GOPATH` (or `"go.gopath"`) directory, or
+ - the `$HOME/go/bin` (or `$USERPROFILE/go/bin`) directory.
+
+Some users prefer to choose a different installation location. In that case, use the `"go.toolsGopath"` setting.
-## [Language Server](docs/gopls.md)
+The extension finds the required tools by their names (`go`, `gopls`, `dlv`, ...). Sometimes, users may need to wrap the tools or want the extension to pick an alternate tool. `"go.alternateTools"` provides a way to configure the extension to use different tools.
-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/).
+### Using a custom linter
-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.
+A commonly customized feature is the linter, which is a tool used to provide coding style feedback and suggestions.
+This extension supports linters such as `staticcheck`, `golangci-lint`, and `revive`. You can choose one of them using the `"go.lintTool"` setting. For customization of the linter, please consult the tools' documentation.
-[`gopls`] is recommended for projects that use Go modules.
+If you are using `staticcheck`, you can enable it via the `gopls` settings block by setting
+```
+ "gopls": {
+ "ui.diagnostic.staticcheck": true
+ }
+```
-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`.
+<!-- TODO: maybe have tips.md or settings.md to discuss more customization and setting tips (e.g. activating signature help after completion, disabling snippets to reduce the interference with gopls' suggestions, setting proxies, etc.) -->
-For more information, see the [`gopls` documentation](docs/gopls.md).
+### Working on the Go standard library and the Go tools
+
+When you need to work on the Go project (https://go.googlesource.com/go), please follow the instruction in the [Standard Library Development](docs/stdlib.md) to adjust your settings.
## Ask for help
@@ -140,6 +126,6 @@
[MIT](LICENSE)
-[`golint`]: https://pkg.go.dev/golang.org/x/lint/golint?tab=overview
[Gophers Slack]: https://gophers.slack.com/
[`gopls`]: https://golang.org/s/gopls
+[`go`]: https://golang.org/cmd/go
diff --git a/docs/commands.md b/docs/commands.md
index 03ae8a4..7777fab 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -1,6 +1,6 @@
# Commands
-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).
+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 on Linux/Windows or Cmd+Shift+P on Mac OS).
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.
diff --git a/docs/gopls.md b/docs/gopls.md
deleted file mode 100644
index fbea475..0000000
--- a/docs/gopls.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# [`gopls`], the Go language server
-
-[`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 not enabled by default yet and users have to opt in by changing from [their settings](#enable-the-language-server). We plan to switch the default and enable it by default early 2021.
-
-[`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).
-
-## Overview
-
-* [Background](#background)
-* [Enable the language server](#enable-the-language-server)
- * [Automatic updates](#automatic-updates)
-* [Configuration](#configuration)
- * [Ignored settings](#ignored-settings)
-* [Troubleshooting](https://github.com/golang/tools/blob/master/gopls/doc/troubleshooting.md)
-* [Additional resources](#additional-resources)
-
-## 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.
-
-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#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`](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#go.useGoProxyToCheckForToolUpdates) to `false`.
-
-## Configuration
-
-There are a number of VS Code Go settings for controlling the language server.
-
-* [`"go.toolsEnvVars"`](settings.md#go.toolsEnvVars) is used when launching `gopls` for the workspace.
-* [`"go.buildFlags"`](settings.md#go.buildFlags) and [`"go.buildTags"`](settings.md#go.buildTags) are propagated to `gopls`.
-* [`"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` is deprecated by `"gopls": { "importShortcut": false }` setting. It was originally meant to disable 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.
-* [`"go.languageServerFlags"`](settings.md#go.languageServerFlags) allows you to pass flags to the `gopls` process.
- * The `-rpc.trace` flag enables verbose debug logging.
-* [`"gopls"`](settings.md#gopls) allows to fine-tune gopls behavior or override the settings propagated from the extension settings (e.g. `"go.buildFlags"`, `"go.toolsEnvVars"`) as shown in the [`gopls` VS Code user guide](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md). The sets of settings recognized by the extension and the gopls may differ if you use an old version or a pre-release version of `gopls`. In that case, the source of truth is in [the documentation](https://github.com/golang/tools/tree/master/gopls/doc/settings.md) in the `gopls` project.
-
-### Ignored settings
-
-Some of the extension's settings are irrelevant when `gopls` is enabled. For example, the extension no longer uses `gocode` or `guru`, so the corresponding settings are no longer applicable. We are trying to document that in the settings' description and the [settings documentation](settings.md). When you find incompelete documentation, please file an issue or send a PR!
-
-## Additional resources
-
-If you encounter an issue while using [`gopls`], take a look at these resources:
-
-* [VS Code user guide](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md)
-* [Known issues](https://github.com/golang/tools/blob/master/gopls/doc/status.md#known-issues)
-* [Troubleshooting](https://github.com/golang/tools/blob/master/gopls/doc/troubleshooting.md)
-* [`gopls` issue tracker](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Agopls)
-
-If you are unable to resolve your issue, please ask for help. Make sure to mention that you are using `gopls`. Here's how to ask for guidance:
-
-* [File a VS Code Go issue](https://github.com/golang/vscode-go/issues/new/choose). If it is a bug in `gopls`, we will transfer your issue to the [`gopls` issue tracker](https://github.com/golang/go/issues).
-* [File a `gopls` issue](https://github.com/golang/go/issues/new) directly.
-* Ask a question in the `#gopls` channel on [Gophers Slack].
-* Ask a question in the `#vscode` channel on [Gophers Slack].
-
-[Go modules]: https://blog.golang.org/using-go-modules
-[`gopls`]: https://golang.org/s/gopls
-[Gophers Slack]: https:/gophers.slack.com/
diff --git a/docs/images/installtools.gif b/docs/images/installtools.gif
new file mode 100644
index 0000000..2a6b49a
--- /dev/null
+++ b/docs/images/installtools.gif
Binary files differ
diff --git a/docs/tools.md b/docs/tools.md
index 8a620aa..e19647b 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -1,102 +1,48 @@
# Tools
-This document describes the tools that power the VS Code Go extension. Each feature is provided by a command-line tool written in Go, so if you experience an issue, it may be due to the underlying tool. Some tools are required for the functionality of the extension, while others are provide optional features.
-
-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.
-
-**NOTE: If you are using the language server, [`gopls`], most of the tools below are not needed.**
-
-## Installation
+This document describes the tools that power the VS Code Go extension.
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`. Read our [`GOPATH` documentation](gopath.md#install-tools-to-a-separate-gobin) if you wish to learn about storing tools in a separate directory.
+VS Code Go will install the tools to your `$GOPATH/bin` by default.
-## Table of Contents
-
-* [Go toolchain](#go-toolchain)
-* [`gocode`](#gocode)
-* [`gopkgs`](#gopkgs)
-* [`go-outline`](#go-outline)
-* [`go-symbols`](#go-symbols)
-* [`guru`](#guru)
-* [`gorename`](#gorename)
-* [`godoctor`](#godoctor)
-* [`delve`](#delve)
-* [`gomodifytags`](#gomodifytags)
-* [`goplay`](#goplay)
-* [`impl`](#impl)
-* [`gotests`](#gotests)
-* [`fillstruct`](#fillstruct)
-* [Documentation](#documentation)
- * [`gogetdoc`]
- * [`godef`]
- * [`godoc`]
-* [Formatting](#formatting)
- * [`goreturns`]
- * [`goimports`]
- * [`gofmt`]
- * [`goformat`]
-* [Diagnostics](#diagnostics)
- * [`gotype-live`]
- * [`golint`]
- * [`staticcheck`]
- * [`golangci-lint`]
- * [`revive`]
-
-### Go toolchain
-
+### [`go`]
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-errors) and [vet-on-save](features.md#vet-errors) features are provided by the `go build` and `go vet` commands.
+The extension runs the [`go`] command to debug and test your go program. By default, this extension assumes that Go is already installed in your system and the `go` command can be found from the `PATH` (or `Path` in some Windows) environment variable.
-### `gocode`
+This extension works best with the [latest versions of Go](https://golang.org/doc/devel/release.html#policy) but some of the features may continue to work with older versions of Go. The Go release policy states that the two newer major releases are officially supported.
-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.
+The extension checks for the availability of the new Go release by periodically checking the [official Go distribution site](https://golang.org/dl) and notifies you of the new version.
-Different versions of `gocode` are used depending on your version of Go.
+### [`gopls`]
+[`gopls`] is the official Go [language server](https://langserver.org/) developed by the Go team. It is the default backend for most of this extension's IntelliSense, code navigation, code editing, and diagnostics features. When the extension starts, it spawns a `gopls` instance in server mode for each VS Code project.
-* Go 1.9 and above: [mdempsky/gocode](https://github.com/mdempsky/gocode)
-* 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.
+`gopls` uses the `go` command to analyze your code. The extension automatically propagates necessary settings such as `"go.buildFlags"`, `"go.buildTags"`, `"go.toolsEnvVars"` and the path to the right `go` command to `gopls`. No extra settings should be necessary, but when you need to adjust `gopls`'s behavior further (e.g., enable more advanced analysis features), please see [all the settings for `gopls`](https://github.com/golang/vscode-go/blob/master/docs/settings.md#settings-for-gopls).
-Learn how to [troubleshoot `gocode`](troubleshooting.md#autocompletion).
+If you encounter issues with `gopls`, please read the [troubleshooting guide](troubleshooting.md#collect-gopls-information). If you want to run the extension without the language server, you can disable it by setting `"go.useLanguageServer": false`.
+
+`gopls` officially supports the four newer major versions of Go. If you are using a very old version of Go, or you explicitly disable the language server, the extension will automatically fall back to the legacy mode. The legacy mode uses old tools instead of `gopls`. Unfortunately many of them are no longer actively maintained and many features the extension provides will not be available.
+You can tell whether the extension is using `gopls`, by checking whether the high voltage icon (⚡) is present in the [Go status bar](docs/ui.md).
+
+`gopls` is under active development, and updating it is important to get new features. The extension periodically checks the [module proxy](https://golang.org/cmd/go/#hdr-Module_proxy_protocol) to detect a new version has been released. When a newer version is available, a pop-up will appear, prompting you to update. If you would like to opt out of this automated update check, set `"go.toolsManagement.checkForUpdates"` to `false`.
+For more information about `gopls`, please visit its [documentation](https://golang.org/s/gopls).
+
+<!-- TODO: link to gopls troubleshooting guide -->
+
+### [`dlv`](https://github.com/go-delve/delve)
+This extension uses Delve for its debug/test functionalities. The extension currently ships with a thin Debug Adapter that implements the [Debug Adapter protocol](https://microsoft.github.io/debug-adapter-protocol/) and connects VS Code and `dlv`.
+
+For a comprehensive overview of how to debug your Go programs, please see the [debugging guide](docs/debugging.md).
+
### [`gopkgs`](https://pkg.go.dev/github.com/uudashr/gopkgs?tab=overview)
-This tool provides autocompletion for unimported packages.
+This tool provides autocompletion for unimported packages. Replacement of `gopkgs` with [`gopls`] is a work-in-progress. <!--TODO: reference to the issue-->
### [`go-outline`](https://pkg.go.dev/github.com/ramya-rao-a/go-outline?tab=overview)
-This tool provides the [document outline](features.md#document-outline) feature, as well as the [go to symbol](features.md#go-to-symbol) in the current file feature.
-
-### [`go-symbols`](https://pkg.go.dev/github.com/acroca/go-symbols?tab=overview)
-
-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#go.docsTool) setting.
-
-`guru` does not have support for Go modules, so we recommend using [`gopls`] for those features instead.
-
-### [`gorename`](https://pkg.go.dev/golang.org/x/tools/cmd/gorename?tab=doc)
-
-This tool provides the [rename symbol](features.md#rename-symbol) feature.
-
-`gorename` does not have support for Go modules, so we recommend using [`gopls`] for this feature instead.
-
-### [`godoctor`](https://github.com/godoctor/godoctor)
-
-This tool provides the [refactoring](features.md#refactor) features.
-
-It does not have support for Go modules, so we expect that [`gopls`] will provide this feature instead ([golang/go#37170](https://github.com/golang/go/issues/37170)).
-
-### [`delve`](https://pkg.go.dev/github.com/go-delve/delve?tab=overview)
-
-This is the debugger for the Go language. It is used to provide the [debugging](debugging.md) features of this extension.
+This tool provides the information needed to compute the various test code lenses. It will be replaced with [`gopls`]. <!--TODO: reference to the issue-->
### [`goplay`](https://pkg.go.dev/github.com/haya14busa/goplay?tab=overview)
@@ -114,47 +60,13 @@
This tool provides support for the [`Go: Generate Unit Tests`](features.md#generate-unit-tests) set of commands.
-### [`fillstruct`](https://github.com/davidrjenni/reftools/tree/master/cmd/fillstruct)
+### [`golint`]
-This tool provides support the [`Go: Fill struct`](features.md#fill-struct-literals) command.
+This is the default lint tool. Other lint tools can be used by configuring the [`"go.lintTool"`](settings.md#go.lintTool) setting. Other options include:
-### Documentation
-
-Documentation tools are used for the [go to definition](features.md#go-to-definition), [signature help](features.md#signature-help), and [quick info on hover](features.md#quick-info-on-hover). [`gogetdoc`] is used by default.
-
-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#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.go.formatTool"`](settings.md#formatTool) setting.
-
-**NOTE: [`goreturns`] does not have support for Go modules, so we recommend using [`goimports`] or [`gopls`] instead.**
-
-Other format tool options include:
-
-* [`goimports`], which applies the default `gofmt` style and organizes imports, but without the behavior of filling in default return values
-* [`gofmt`] only formats the file, without import organization or filling in return values
-* [`goformat`] is a configurable version of [`gofmt`]
-
-### Diagnostics
-
-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](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#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).
-* [`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`], and it provides additional checks.
+ * [`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`], 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:
@@ -179,6 +91,40 @@
]
```
+### Misc tools used in the legacy mode
+
+When `gopls` cannot be used, the extension falls back to the legacy mode. Be aware that many of these tools may be incompatible with the recent versions of Go or do not work in Modules mode.
+
+* [`go-outline`](https://pkg.go.dev/github.com/ramya-rao-a/go-outline?tab=overview):
+In the legacy mode, this tool provides the `[document outline](features.md#document-outline) feature` and the [go to symbol](features.md#go-to-symbol) in the current file feature.
+
+* `gocode`: code completion in the legacy mode is provided by `gocode`. Different versions of `gocode` are used depending on your version of Go.
+ * Go 1.9 and above: [mdempsky/gocode](https://github.com/mdempsky/gocode)
+ * Go 1.11 and above, with modules enabled: [stamblerre/gocode](https://github.com/stamblerre/gocode), named `gocode-gomod` internally.
+
+* [`go-symbols`](https://pkg.go.dev/github.com/acroca/go-symbols?tab=overview): 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): 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#go.docsTool) setting. `guru` does not support Go modules.
+
+* [`gorename`](https://pkg.go.dev/golang.org/x/tools/cmd/gorename?tab=doc): provides the [rename symbol](features.md#rename-symbol) feature. `gorename` does not have support for Go modules
+
+* [`godoctor`](https://github.com/godoctor/godoctor): provides the [refactoring](features.md#refactor) features. It does not support Go modules, and we expect that [`gopls`] will provide this feature instead ([golang/go#37170](https://github.com/golang/go/issues/37170)).
+
+* [`fillstruct`](https://github.com/davidrjenni/reftools/tree/master/cmd/fillstruct): provides support the [`Go: Fill struct`](features.md#fill-struct-literals) command.
+
+* [`gogetdoc`], [`godef`], [`godoc`]: these are documentation tools used for the [go to definition](features.md#go-to-definition), [signature help](features.md#signature-help), and [quick info on hover](features.md#quick-info-on-hover) in the legacy mode. [`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#go.docsTool) setting.
+
+* [`goreturns`], [`gofmt`], [`goimports`]: Formatting tools are used by the [formatting and import organization](features.md#format-and-organize-imports) features. [`goreturns`] is used by default in the legacy mode. 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 that [`goreturns`] does not have support for Go modules.
+
+ * [`goimports`], which applies the default `gofmt` style and organizes imports, but without the behavior of filling in default return values
+ * [`gofmt`] only formats the file, without import organization or filling in return values
+ * [`goformat`] is a configurable version of [`gofmt`]
+
+* Diagnostics tools: 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. [`gotype-live`] does not work with modules.
+
+
+
[`gogetdoc`]: https://pkg.go.dev/github.com/zmb3/gogetdoc?tab=overview
[`godef`]: https://pkg.go.dev/github.com/rogpeppe/godef?tab=doc
[`godoc`]: https://pkg.go.dev/golang.org/x/tools/godoc?tab=doc
@@ -191,5 +137,7 @@
[`staticcheck`]: https://pkg.go.dev/honnef.co/go/tools/staticcheck?tab=overview
[`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/
+[`gopls`]: https://golang.org/s/gopls
+[`go`]: https://golang.org/cmd/go
+
