mirror of https://github.com/golang/go.git
gopls: merge README and user.md
These two pages were serving largely the same function, so it makes more sense to merge them. Mostly deleted all of the information about configuration--its really verbose and not likely to be helpful to users. Change-Id: Id5eb6cd2acc19cc2d863943cb399cfefb6bdcee8 Reviewed-on: https://go-review.googlesource.com/c/tools/+/283644 Trust: Rebecca Stambler <rstambler@golang.org> Run-TryBot: Rebecca Stambler <rstambler@golang.org> gopls-CI: kokoro <noreply+kokoro@google.com> TryBot-Result: Go Bot <gobot@golang.org> Reviewed-by: Heschi Kreinick <heschi@google.com> Reviewed-by: Robert Findley <rfindley@google.com>
This commit is contained in:
Rebecca Stambler
parent
7e51fbd4c4
commit
bec622c317
146
gopls/README.md
146
gopls/README.md
|
|
@ -1,73 +1,117 @@
|
|||
# gopls documentation
|
||||
# `gopls`, the Go language server
|
||||
|
||||
[](https://pkg.go.dev/golang.org/x/tools/gopls)
|
||||
|
||||
gopls (pronounced: "go please") is the official [language server] for the Go language.
|
||||
[`gopls`] (pronounced "Go please") is the official Go [language server]
|
||||
developed by the Go team. It provides IDE features to any [LSP]-compatible
|
||||
editor.
|
||||
|
||||
## Status
|
||||
<!--TODO(rstambler): Add gifs here.-->
|
||||
|
||||
It is currently in **alpha**, so it is **not stable**.
|
||||
You should not need to interact with `gopls` directly--it will be automatically
|
||||
integrated into your editor. The specific features and settings vary slightly
|
||||
by editor, so we recommend that you proceed to the [documentation for your
|
||||
editor](#editors) below.
|
||||
|
||||
You can see more information about the status of gopls and its supported features [here](doc/status.md).
|
||||
## Editors
|
||||
|
||||
## Roadmap
|
||||
To get started with `gopls`, install an LSP plugin in your editor of choice.
|
||||
Below is a list of editors with known integrations for `gopls`.
|
||||
|
||||
The current goal is a fully stable build with the existing feature set, aiming
|
||||
for the first half of 2020, with release candidates earlier in the year.
|
||||
|
||||
This will be the first build that we recommend people use, and will be tagged as the 1.0 version.
|
||||
You can see the set of things being worked on in the [1.0 milestone], in general
|
||||
we are focused on stability, specifically, making sure we have a reliable service that produces an experience in module mode that is not a retrograde step from the old tools in GOPATH mode.
|
||||
|
||||
There is also considerable effort being put into testing in order to make sure that we both have a stable service and also that we do not regress after launch.
|
||||
|
||||
While we may continue to accept contributions for new features, they may be turned off behind a configuration flag if they are not yet stable. See the [gopls unplanned] milestone for deprioritized features.
|
||||
|
||||
This is just a milestone for gopls itself. We work with editor integrators to make sure they can use the latest builds of gopls, and will help them use the 1.0 version as soon as it is ready, but that does not imply anything about the stability, supported features or version of the plugins.
|
||||
|
||||
## Using
|
||||
|
||||
In general you should not need to know anything about gopls, it should be integrated into your editor for you.
|
||||
|
||||
To install for your specific editor you can follow the following instructions
|
||||
|
||||
* [VSCode](doc/vscode.md)
|
||||
* [VSCode](https://github.com/golang/vscode-go)
|
||||
* [Vim / Neovim](doc/vim.md)
|
||||
* [Emacs](doc/emacs.md)
|
||||
* [Acme](doc/acme.md)
|
||||
* [Atom](https://github.com/MordFustang21/ide-gopls)
|
||||
* [Sublime Text](doc/subl.md)
|
||||
* [Atom](doc/atom.md)
|
||||
* [Acme](https://github.com/fhs/acme-lsp)
|
||||
|
||||
See the [user guide](doc/user.md) for more information, including the how to install gopls by hand if you need.
|
||||
If you use `gopls` with an editor that is not on this list, please let us know
|
||||
by [filing an issue](#new-issue) or [modifying this documentation](doc/contributing.md).
|
||||
|
||||
## Issues
|
||||
## Installation
|
||||
|
||||
If you are having issues with gopls, please first check the [known issues](doc/status.md#known-issues) before following the [troubleshooting](doc/troubleshooting.md#steps) guide.
|
||||
If that does not give you the information you need, reach out to us.
|
||||
For the most part, you should not need to install or update `gopls`. Your
|
||||
editor should handle that step for you.
|
||||
|
||||
You can chat with us on:
|
||||
* the golang-tools [mailing list]
|
||||
* the #gopls [slack channel] on the gophers slack
|
||||
If you do want to get the latest stable version of `gopls`, change to any
|
||||
directory that is both outside of your `GOPATH` and outside of a module (a temp
|
||||
directory is fine), and run:
|
||||
|
||||
If you think you have an issue that needs fixing, or a feature suggestion, then please make sure you follow the steps to [file an issue](doc/troubleshooting.md#file-an-issue) with the right information to allow us to address it.
|
||||
```sh
|
||||
GO111MODULE=on go get golang.org/x/tools/gopls@latest
|
||||
```
|
||||
|
||||
If you need to talk to us directly (for instance to file an issue with confidential information in it) you can reach out directly to [@stamblerre] or [@ianthehat].
|
||||
**NOTE**: Do not use the `-u` flag, as it will update your dependencies to
|
||||
incompatible versions.
|
||||
|
||||
## More information
|
||||
To get a specific version of `gopls` (for example, to test a prerelease
|
||||
version), run:
|
||||
|
||||
If you want to know more about it, have an unusual use case, or want to contribute, please read the following documents
|
||||
```sh
|
||||
GO111MODULE=on go get golang.org/x/tools/gopls@vX.Y.Z
|
||||
```
|
||||
|
||||
* [Using gopls](doc/user.md)
|
||||
* [Troubleshooting and reporting issues](doc/troubleshooting.md)
|
||||
* [Integrating gopls with an editor](doc/integrating.md)
|
||||
* [Contributing to gopls](doc/contributing.md)
|
||||
* [Design requirements and decisions](doc/design.md)
|
||||
* [Implementation details](doc/implementation.md)
|
||||
Where `vX.Y.Z` is the desired version.
|
||||
|
||||
### Unstable versions
|
||||
|
||||
To update `gopls` to the latest **unstable** version, use:
|
||||
|
||||
```sh
|
||||
GO111MODULE=on go get golang.org/x/tools/gopls@master golang.org/x/tools@master
|
||||
```
|
||||
|
||||
In general, you should use `@latest` instead, to prevent frequent breakages.
|
||||
|
||||
### Supported Go versions
|
||||
|
||||
`gopls` follows the
|
||||
[Go Release Policy](https://golang.org/doc/devel/release.html#policy),
|
||||
meaning that it officially supports the last 2 major Go releases. Though we
|
||||
try not to break older versions, we do not prioritize issues only affecting
|
||||
legacy Go releases (3 or 4 releases ago).
|
||||
|
||||
## Configuration
|
||||
|
||||
You can configure `gopls` to change your editor experience or view additional
|
||||
debugging information. Configuration options will be made available by your
|
||||
editor, so see your [editor's instructions](#editors) for specific details. A
|
||||
full list of `gopls` settings can be found in the [Settings documentation](doc/settings.md).
|
||||
|
||||
### Environment variables
|
||||
|
||||
`gopls` inherits your editor's environment, so be aware of any environment
|
||||
variables you configure. Some editors, such as VS Code, allow users to
|
||||
selectively override the values of some environment variables.
|
||||
|
||||
### Working on the Go source distribution
|
||||
|
||||
If you are working on the [Go project] itself, the `go` command that `gopls`
|
||||
invokes will have to correspond to the version of the source you are working
|
||||
on. That is, if you have downloaded the code to `$HOME/go`, your `go` command
|
||||
should be the `$HOME/go/bin/go` executable that you built with `make.bash` or
|
||||
equivalent.
|
||||
|
||||
You can achieve this by adding the right version of `go` to your `PATH`
|
||||
(`export PATH=$HOME/go/bin:$PATH` on Unix systems) or by configuring your
|
||||
editor.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you are having issues with `gopls`, please follow the steps described in the
|
||||
[troubleshooting guide](doc/troubleshooting.md).
|
||||
|
||||
## Additional information
|
||||
|
||||
* [Features](doc/features.md)
|
||||
* [Command-line interface](doc/command-line.md)
|
||||
* [Contributing to `gopls`](doc/contributing.md)
|
||||
* [Integrating `gopls` with an editor](doc/design/integrating.md)
|
||||
* [Design requirements and decisions](doc/design/design.md)
|
||||
* [Implementation details](doc/design/implementation.md)
|
||||
* [Open issues](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Agopls)
|
||||
|
||||
[language server]: https://langserver.org
|
||||
[mailing list]: https://groups.google.com/forum/#!forum/golang-tools
|
||||
[slack channel]: https://gophers.slack.com/messages/CJZH85XCZ
|
||||
[@stamblerre]: https://github.com/stamblerre "Rebecca Stambler"
|
||||
[@ianthehat]: https://github.com/ianthehat "Ian Cottrell"
|
||||
[1.0 milestone]: https://github.com/golang/go/milestone/112
|
||||
[gopls unplanned]: https://github.com/golang/go/milestone/124
|
||||
[LSP]: https://microsoft.github.io/language-server-protocol/
|
||||
[Go project]: https://go.googlesource.com/go
|
||||
[Gophers Slack]: https://gophers.slack.com/
|
||||
|
|
|
|||
|
|
@ -1,7 +0,0 @@
|
|||
# Acme
|
||||
|
||||
Use the experimental [`acme-lsp`] plugin.
|
||||
Get started by following the[installation guide].
|
||||
|
||||
[`acme-lsp`]: https://github.com/fhs/acme-lsp
|
||||
[installation guide]: https://github.com/fhs/acme-lsp#gopls
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
# Atom
|
||||
|
||||
Use the [`ide-gopls`] package.
|
||||
You will also need to install the [`atom-ide-ui`] package.
|
||||
|
||||
[`ide-gopls`]: https://github.com/MordFustang21/ide-gopls
|
||||
[`atom-ide-ui`]: https://github.com/facebookarchive/atom-ide-ui
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
# Documentation for contributors
|
||||
|
||||
This documentation augments the general documentation for contributing to the
|
||||
x/tools repository, described at the [repository root](../CONTRIBUTING.md).
|
||||
x/tools repository, described at the [repository root](../../CONTRIBUTING.md).
|
||||
|
||||
Contributions are welcome, but since development is so active, we request that
|
||||
you file an issue and claim it before starting to work on something. Otherwise,
|
||||
|
|
@ -96,7 +96,7 @@ Furthermore, an additional "gopls-CI" pass will be run by _Kokoro_, which is a
|
|||
Jenkins-like Google infrastructure for running Dockerized tests. This allows us
|
||||
to run gopls tests in various environments that would be difficult to add to
|
||||
the TryBots. Notably, Kokoro runs tests on
|
||||
[older Go versions](user.md#supported-go-versions) that are no longer supported
|
||||
[older Go versions](../README.md#supported-go-versions) that are no longer supported
|
||||
by the TryBots.
|
||||
|
||||
## Debugging
|
||||
|
|
|
|||
|
|
@ -150,10 +150,10 @@ will use the same shared daemon.
|
|||
|
||||
**Q: Why am I not saving as much memory as I expected when using a shared gopls?**
|
||||
|
||||
A: As described in [implementation.md](implementation.md), gopls has a concept
|
||||
of view/session/cache. Each session and view map onto exactly one editor
|
||||
session (because they contain things like edited but unsaved buffers). The
|
||||
cache contains things that are independent of any editor session, and can
|
||||
A: As described in [implementation.md](design/implementation.md), gopls has a
|
||||
concept of view/session/cache. Each session and view map onto exactly one
|
||||
editor session (because they contain things like edited but unsaved buffers).
|
||||
The cache contains things that are independent of any editor session, and can
|
||||
therefore be shared.
|
||||
|
||||
When, for example, three editor session are sharing a single gopls process,
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
## Installing `gopls`
|
||||
|
||||
To use `gopls` with Emacs, you must first
|
||||
[install the `gopls` binary](user.md#installation) and ensure that the directory
|
||||
[install the `gopls` binary](../README.md#installation) and ensure that the directory
|
||||
containing the resulting binary (either `$(go env GOBIN)` or `$(go env
|
||||
GOPATH)/bin`) is in your `PATH`.
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ VS Code users should follow [their troubleshooting guide](https://github.com/gol
|
|||
|
||||
1. Verify that your project is in good shape by working with it outside of your editor. Running a command like `go build ./...` in the workspace directory will compile everything. For modules, `go mod tidy` is another good check, though it may modify your `go.mod`.
|
||||
1. Check that your editor isn't showing any diagnostics that indicate a problem with your workspace. They may appear as diagnostics on a Go file's package declaration, diagnostics in a go.mod file, or as a status or progress message. Problems in the workspace configuration can cause many different symptoms. See the [workspace setup instructions](workspace.md) for help.
|
||||
1. Make sure `gopls` is up to date by following the [installation instructions](user.md#installing), then [restarting gopls](#restart-gopls).
|
||||
1. Make sure `gopls` is up to date by following the [installation instructions](../README.md#installation), then [restarting gopls](#restart-gopls).
|
||||
1. Optionally, [ask for help](#ask-for-help) on Gophers Slack.
|
||||
1. Finally, [report the issue](#file-an-issue) to the `gopls` developers.
|
||||
|
||||
|
|
@ -41,7 +41,7 @@ You may have to change your editor's configuration to pass a `-logfile` flag to
|
|||
|
||||
To increase the level of detail in your logs, start `gopls` with the `-rpc.trace` flag. To start a debug server that will allow you to see profiles and memory usage, start `gopls` with `serve --debug=localhost:6060`. You will then be able to view debug information by navigating to `localhost:6060`.
|
||||
|
||||
If you are unsure of how to pass a flag to `gopls` through your editor, please see the [documentation for your editor](user.md#editors).
|
||||
If you are unsure of how to pass a flag to `gopls` through your editor, please see the [documentation for your editor](../README.md#editors).
|
||||
|
||||
## Debug memory usage
|
||||
|
||||
|
|
|
|||
|
|
@ -1,165 +0,0 @@
|
|||
# User guide
|
||||
|
||||
**If you're having issues with `gopls`, please see the
|
||||
[troubleshooting guide](troubleshooting.md).**
|
||||
|
||||
## Editors
|
||||
|
||||
The following is the list of editors with known integrations for `gopls`.
|
||||
|
||||
* [VSCode](vscode.md)
|
||||
* [Vim / Neovim](vim.md)
|
||||
* [Emacs](emacs.md)
|
||||
* [Acme](acme.md)
|
||||
* [Sublime Text](subl.md)
|
||||
* [Atom](atom.md)
|
||||
|
||||
If you use `gopls` with an editor that is not on this list, please let us know
|
||||
by [filing an issue](#new-issue) or [modifying this documentation](contributing.md).
|
||||
|
||||
## Overview
|
||||
|
||||
* [Installation](#installation)
|
||||
* [Configuration](#configuration)
|
||||
|
||||
Learn more at the following pages:
|
||||
|
||||
* [Features](features.md)
|
||||
* [Command-line](command-line.md)
|
||||
|
||||
## Installation
|
||||
|
||||
For the most part, you should not need to install or update `gopls`. Your editor should handle that step for you.
|
||||
|
||||
If you do want to get the latest stable version of `gopls`, change to any directory that is both outside of your `GOPATH` and outside of a module (a temp directory is fine), and run
|
||||
|
||||
```sh
|
||||
go get golang.org/x/tools/gopls@latest
|
||||
```
|
||||
|
||||
**Do not** use the `-u` flag, as it will update your dependencies to incompatible versions.
|
||||
|
||||
To get a specific version of `gopls` (for example, to test a prerelease
|
||||
version), run:
|
||||
|
||||
```sh
|
||||
go get golang.org/x/tools/gopls@vX.Y.Z
|
||||
```
|
||||
|
||||
Where `vX.Y.Z` is the desired version.
|
||||
|
||||
If you see this error:
|
||||
|
||||
```sh
|
||||
$ go get golang.org/x/tools/gopls@latest
|
||||
go: cannot use path@version syntax in GOPATH mode
|
||||
```
|
||||
|
||||
then run
|
||||
|
||||
```sh
|
||||
GO111MODULE=on go get golang.org/x/tools/gopls@latest
|
||||
```
|
||||
|
||||
### Unstable versions
|
||||
|
||||
`go get` doesn't honor the `replace` directive in the `go.mod` of
|
||||
`gopls` when you are outside of the `gopls` module, so a simple `go get`
|
||||
with `@master` could fail. To actually update your `gopls` to the
|
||||
latest **unstable** version, use:
|
||||
|
||||
```sh
|
||||
go get golang.org/x/tools/gopls@master golang.org/x/tools@master
|
||||
```
|
||||
|
||||
In general, you should use `@latest` instead, to prevent frequent
|
||||
breakages.
|
||||
|
||||
### Supported Go versions
|
||||
|
||||
`gopls` follows the
|
||||
[Go Release Policy](https://golang.org/doc/devel/release.html#policy),
|
||||
meaning that it officially supports the last 2 major Go releases. We run CI to
|
||||
verify that the `gopls` tests pass for the last 4 major Go releases, but do not
|
||||
prioritize issues only affecting legacy Go release (3 or 4 releases ago).
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment variables
|
||||
|
||||
These are often inherited from the editor that launches `gopls`, and sometimes
|
||||
the editor has a way to add or replace values before launching. For example,
|
||||
VSCode allows you to configure `go.toolsEnvVars`.
|
||||
|
||||
Configuring your environment correctly is important, as `gopls` relies on the
|
||||
`go` command.
|
||||
|
||||
### Command-line flags
|
||||
|
||||
See the [command-line page](command-line.md) for more information about the
|
||||
flags you might specify. All editors support some way of adding flags to
|
||||
`gopls`, for the most part you should not need to do this unless you have very
|
||||
unusual requirements or are trying to [troubleshoot](troubleshooting.md#steps)
|
||||
`gopls` behavior.
|
||||
|
||||
### Editor settings
|
||||
|
||||
For the most part these will be settings that control how the editor interacts
|
||||
with or uses the results of `gopls`, not modifications to `gopls` itself. This
|
||||
means they are not standardized across editors, and you will have to look at
|
||||
the specific instructions for your editor integration to change them.
|
||||
|
||||
#### The set of workspace folders
|
||||
|
||||
This is one of the most important pieces of configuration. It is the set of
|
||||
folders that gopls considers to be "roots" that it should consider files to
|
||||
be a part of.
|
||||
|
||||
If you are using modules there should be one of these per go.mod that you
|
||||
are working on. If you do not open the right folders, very little will work.
|
||||
**This is the most common misconfiguration of `gopls` that we see**.
|
||||
|
||||
#### Global configuration
|
||||
|
||||
There should be a way of declaring global settings for `gopls` inside the
|
||||
editor. The settings block will be called `"gopls"` and contains a collection
|
||||
of controls for `gopls` that the editor is not expected to understand or
|
||||
control.
|
||||
|
||||
In VSCode, this would be a section in your settings file that might look like
|
||||
this:
|
||||
|
||||
```json5
|
||||
"gopls": {
|
||||
"usePlaceholders": true,
|
||||
"completeUnimported": true
|
||||
},
|
||||
```
|
||||
|
||||
See [Settings](settings.md) for more information about the available
|
||||
configurations.
|
||||
|
||||
#### Workspace folder configuration
|
||||
|
||||
This contains exactly the same set of values that are in the global
|
||||
configuration, but it is fetched for every workspace folder separately.
|
||||
The editor can choose to respond with different values per-folder.
|
||||
|
||||
### Working on the Go source distribution
|
||||
|
||||
If you are working on the [Go project](https://go.googlesource.com/go) itself,
|
||||
your `go` command will have to correspond to the version of the source you are
|
||||
working on. That is, if you have downloaded the code to `$HOME/go`, your `go`
|
||||
command should be the `$HOME/go/bin/go` executable that you built with
|
||||
`make.bash` or equivalent.
|
||||
|
||||
You can achieve this by adding the right version of `go` to your `PATH` (`export PATH=$HOME/go/bin:$PATH` on Unix systems) or by configuring your editor. In VS Code, you can use the `go.alternateTools` setting to point to the correct version of `go`:
|
||||
|
||||
```json5
|
||||
{
|
||||
|
||||
"go.alternateTools": {
|
||||
"go": "$HOME/bin/go"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -1,66 +0,0 @@
|
|||
# VS Code
|
||||
|
||||
Use the [VS Code Go] plugin, with the following configuration:
|
||||
|
||||
```json5
|
||||
"go.useLanguageServer": true,
|
||||
```
|
||||
|
||||
As of February 2020, `gopls` will be enabled by default in [VS Code Go].
|
||||
To learn more, follow along with
|
||||
[golang.vscode-go#1037](https://github.com/golang/vscode-go/issues/1037).
|
||||
|
||||
```json5
|
||||
"gopls": {
|
||||
// Add parameter placeholders when completing a function.
|
||||
"ui.completion.usePlaceholders": true,
|
||||
|
||||
// If true, enable additional analyses with staticcheck.
|
||||
// Warning: This will significantly increase memory usage.
|
||||
"ui.diagnostic.staticcheck": false,
|
||||
|
||||
// For more customization, see
|
||||
// see https://github.com/golang/vscode-go/blob/master/docs/settings.md.
|
||||
}
|
||||
```
|
||||
|
||||
To enable more detailed debug information, add the following to your VSCode settings:
|
||||
|
||||
```json5
|
||||
"go.languageServerFlags": [
|
||||
"-rpc.trace", // for more detailed debug logging
|
||||
"serve",
|
||||
"--debug=localhost:6060", // Optional: investigate memory usage, see profiles
|
||||
],
|
||||
```
|
||||
|
||||
See the section on [command line](command-line.md) arguments for more
|
||||
information about what these do, along with other things like
|
||||
`--logfile=auto` that you might want to use.
|
||||
|
||||
## Build tags and flags
|
||||
|
||||
Build tags and flags will be automatically picked up from `"go.buildTags"` and
|
||||
`"go.buildFlags"` settings. In the rare case that you don't want that default
|
||||
behavior, you can still override the settings from the `gopls` section, using
|
||||
`"gopls": { "build.buildFlags": [] }`.
|
||||
|
||||
## Remote Development with `gopls`
|
||||
|
||||
You can also make use of `gopls` with the
|
||||
[VS Code Remote Development](https://code.visualstudio.com/docs/remote/remote-overview)
|
||||
extensions to enable full-featured Go development on a lightweight client
|
||||
machine, while connected to a more powerful server machine.
|
||||
|
||||
First, install the Remote Development extension of your choice, such as the
|
||||
[Remote - SSH](https://code.visualstudio.com/docs/remote/ssh) extension. Once
|
||||
you open a remote session in a new window, open the Extensions pane
|
||||
(Ctrl+Shift+X) and you will see several different sections listed. In the
|
||||
"Local - Installed" section, navigate to the Go extension and click
|
||||
"Install in SSH: hostname".
|
||||
|
||||
Once you have reloaded VS Code, you will be prompted to install `gopls` and other
|
||||
Go-related tools. After one more reload, you should be ready to develop remotely
|
||||
with VS Code and the Go extension.
|
||||
|
||||
[VS Code Go]: https://github.com/golang/vscode-go
|
||||
|
|
@ -28,7 +28,7 @@ below.
|
|||
|
||||
In VS Code, you can create a workspace folder by setting up a
|
||||
[multi-root workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces).
|
||||
View the [documentation for your editor plugin](user.md#editor) to learn how to
|
||||
View the [documentation for your editor plugin](../README.md#editor) to learn how to
|
||||
configure a workspace folder in your editor.
|
||||
|
||||
#### Workspace module (experimental)
|
||||
|
|
|
|||
Loading…
Reference in New Issue