golang.org/x/tools/gopls@v0.15.3/README.md (about)

     1  # `gopls`, the Go language server
     2  
     3  [![PkgGoDev](https://pkg.go.dev/badge/golang.org/x/tools/gopls)](https://pkg.go.dev/golang.org/x/tools/gopls)
     4  
     5  `gopls` (pronounced "Go please") is the official Go [language server] developed
     6  by the Go team. It provides IDE features to any [LSP]-compatible editor.
     7  
     8  <!--TODO(rfindley): Add gifs here.-->
     9  
    10  You should not need to interact with `gopls` directly--it will be automatically
    11  integrated into your editor. The specific features and settings vary slightly
    12  by editor, so we recommend that you proceed to the
    13  [documentation for your editor](#editors) below.
    14  
    15  ## Editors
    16  
    17  To get started with `gopls`, install an LSP plugin in your editor of choice.
    18  
    19  * [VS Code](https://github.com/golang/vscode-go/blob/master/README.md)
    20  * [Vim / Neovim](doc/vim.md)
    21  * [Emacs](doc/emacs.md)
    22  * [Atom](https://github.com/MordFustang21/ide-gopls)
    23  * [Sublime Text](doc/subl.md)
    24  * [Acme](https://github.com/fhs/acme-lsp)
    25  * [Lapce](https://github.com/lapce-community/lapce-go)
    26  
    27  If you use `gopls` with an editor that is not on this list, please send us a CL
    28  [updating this documentation](doc/contributing.md).
    29  
    30  ## Installation
    31  
    32  For the most part, you should not need to install or update `gopls`. Your
    33  editor should handle that step for you.
    34  
    35  If you do want to get the latest stable version of `gopls`, run the following
    36  command:
    37  
    38  ```sh
    39  go install golang.org/x/tools/gopls@latest
    40  ```
    41  
    42  Learn more in the
    43  [advanced installation instructions](doc/advanced.md#installing-unreleased-versions).
    44  
    45  Learn more about gopls releases in the [release policy](doc/releases.md).
    46  
    47  ## Setting up your workspace
    48  
    49  `gopls` supports both Go module, multi-module and GOPATH modes. See the
    50  [workspace documentation](doc/workspace.md) for information on supported
    51  workspace layouts.
    52  
    53  ## Configuration
    54  
    55  You can configure `gopls` to change your editor experience or view additional
    56  debugging information. Configuration options will be made available by your
    57  editor, so see your [editor's instructions](#editors) for specific details. A
    58  full list of `gopls` settings can be found in the [settings documentation](doc/settings.md).
    59  
    60  ### Environment variables
    61  
    62  `gopls` inherits your editor's environment, so be aware of any environment
    63  variables you configure. Some editors, such as VS Code, allow users to
    64  selectively override the values of some environment variables.
    65  
    66  ## Support Policy
    67  
    68  Gopls is maintained by engineers on the
    69  [Go tools team](https://github.com/orgs/golang/teams/tools-team/members),
    70  who actively monitor the
    71  [Go](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Agopls)
    72  and
    73  [VS Code Go](https://github.com/golang/vscode-go/issues) issue trackers.
    74  
    75  ### Supported Go versions
    76  
    77  `gopls` follows the
    78  [Go Release Policy](https://golang.org/doc/devel/release.html#policy),
    79  meaning that it officially supports the last 2 major Go releases. Per
    80  [issue #39146](https://go.dev/issues/39146), we attempt to maintain best-effort
    81  support for the last 4 major Go releases, but this support extends only to not
    82  breaking the build and avoiding easily fixable regressions.
    83  
    84  In the context of this discussion, gopls "supports" a Go version if it supports
    85  being built with that Go version as well as integrating with the `go` command
    86  of that Go version.
    87  
    88  The following table shows the final gopls version that supports a given Go
    89  version. Go releases more recent than any in the table can be used with any
    90  version of gopls.
    91  
    92  | Go Version  | Final gopls version with support (without warnings) |
    93  | ----------- | --------------------------------------------------- |
    94  | Go 1.12     | [gopls@v0.7.5](https://github.com/golang/tools/releases/tag/gopls%2Fv0.7.5) |
    95  | Go 1.15     | [gopls@v0.9.5](https://github.com/golang/tools/releases/tag/gopls%2Fv0.9.5) |
    96  | Go 1.17     | [gopls@v0.11.0](https://github.com/golang/tools/releases/tag/gopls%2Fv0.11.0) |
    97  | Go 1.18     | [gopls@v0.14.2](https://github.com/golang/tools/releases/tag/gopls%2Fv0.14.2) |
    98  
    99  Our extended support is enforced via [continuous integration with older Go
   100  versions](doc/contributing.md#ci). This legacy Go CI may not block releases:
   101  test failures may be skipped rather than fixed. Furthermore, if a regression in
   102  an older Go version causes irreconcilable CI failures, we may drop support for
   103  that Go version in CI if it is 3 or 4 Go versions old.
   104  
   105  ### Supported build systems
   106  
   107  `gopls` currently only supports the `go` command, so if you are using
   108  a different build system, `gopls` will not work well. Bazel is not officially
   109  supported, but may be made to work with an appropriately configured
   110  `go/packages` driver. See
   111  [bazelbuild/rules_go#512](https://github.com/bazelbuild/rules_go/issues/512)
   112  for more information.
   113  You can follow [these instructions](https://github.com/bazelbuild/rules_go/wiki/Editor-setup)
   114  to configure your `gopls` to work with Bazel.
   115  
   116  ### Troubleshooting
   117  
   118  If you are having issues with `gopls`, please follow the steps described in the
   119  [troubleshooting guide](doc/troubleshooting.md).
   120  
   121  ## Additional information
   122  
   123  * [Features](doc/features.md)
   124  * [Command-line interface](doc/command-line.md)
   125  * [Advanced topics](doc/advanced.md)
   126  * [Contributing to `gopls`](doc/contributing.md)
   127  * [Integrating `gopls` with an editor](doc/design/integrating.md)
   128  * [Design requirements and decisions](doc/design/design.md)
   129  * [Implementation details](doc/design/implementation.md)
   130  * [Open issues](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Agopls)
   131  
   132  [language server]: https://langserver.org
   133  [LSP]: https://microsoft.github.io/language-server-protocol/