forked from golang/vscode-go
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: update GOPATH, modules, and gopls documentation
This change finishes the general work of updating the documentation. The GOPATH, modules, and gopls pages are finalized. I expect that I still have 3 CLs left in this set of changes: (1) Generating settings and commands docs from the package.json (2) A pass for proofreading, checking links, and other improvements (3) A pass to remove and file issues for all TODOs Let me know if there's anything else I'm missing here. Change-Id: I0ba9c2be9cc92e32dc7bae4526745306ef49a503 Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236840 Reviewed-by: Hyang-Ah Hana Kim <[email protected]>
- Loading branch information
1 parent
cf9d16b
commit 2ce0e4f
Showing
9 changed files
with
329 additions
and
151 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,26 +1,80 @@ | ||
| # `GOPATH` | ||
|
|
||
| At any point in time, you can run the command `Go: Current GOPATH` to see the GOPATH being used by the extension. | ||
| 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. | ||
|
|
||
| ### GOPATH from the environment variable | ||
| Out of the box, the extension uses the value of the environment variable `GOPATH`. From Go 1.8 onwards, if no such environment variable is set, then the default GOPATH as deciphered from the command `go env` is used. | ||
| 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). | ||
|
|
||
| ### GOPATH from `go.gopath` setting | ||
| Setting `go.gopath` in User settings overrides the GOPATH that was derived from the above logic. | ||
| Setting `go.gopath` in Workspace settings overrides the one from User settings. | ||
| You can set multiple folders as GOPATH in this setting. Note that they should be `;` separated in Windows and `:` separated otherwise. | ||
| ## Overview | ||
|
|
||
| ### GOPATH from `go.inferGopath` setting | ||
| Setting `go.inferGopath` overrides the value set in `go.gopath` setting. If `go.inferGopath` is set to true, the extension will try to infer the `GOPATH` from the path of the workspace i.e. the directory opened in `vscode`. It searches upwards in the path for the `src` directory, and sets `GOPATH` to one level above that. It will also include the global GOPATH. Run `go env GOPATH` to find out what your global GOPATH is. | ||
| * [Check the value of `GOPATH`](#check-the-value-of-gopath) | ||
| * [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 `GOPATH`](#install-tools-to-a-separate-gopath) | ||
|
|
||
| For example, if your project looks like `/aaa/bbb/ccc/src/...`, then opening the directory `/aaa/bbb/ccc/src` (or anything below that) will cause the extension to search upwards, find the `src` component in the path, and set the `GOPATH` to one level above that i.e. `GOPATH=/aaa/bbb/ccc`. | ||
| ## Check the value of `GOPATH` | ||
|
|
||
| This setting is useful when you are working on different Go projects which have different GOPATHs. Instead of setting the GOPATH in the workspace settings of each project or setting all the paths as `;`/`:` separated string, you can just set `go.inferGopath` to `true`and the extension uses the right GOPATH automatically. | ||
| 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. | ||
|
|
||
| ### GOPATH for installing the Go tools using `go.toolsGopath` | ||
| If the `GOPATH` value is incorrect, see the details below on how to configure it. | ||
|
|
||
| The `go get` command installs Go tools in your GOPATH. To prevent the Go tools from cluttering your GOPATH, use the `go.toolsGopath` setting to provide a separate GOPATH to use just for the Go tools. | ||
| ## Setting `GOPATH` | ||
|
|
||
| The first time you set `go.toolsGopath`, you will have to run `Go: Install/Update Tools` command so that the Go tools get installed in the provided location. | ||
| 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. | ||
|
|
||
| If `go.toolsGopath` is not set or if the Go tools are not found there, then the Go tools from the GOPATH derived from the logic described in the previous section are used. If not found in there as well, then they are looked for in the paths that are part of the PATH environment variable. | ||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| ## 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. | ||
|
|
||
| [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. | ||
|
|
||
| ## 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`). | ||
|
|
||
| For example, say your global `GOPATH` is `$HOME/go`, but you are working in a repository with the following structure. | ||
|
|
||
| ```bash | ||
| foo/ | ||
| └── bar | ||
| └── src | ||
| └── 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`. | ||
|
|
||
| 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: | ||
|
|
||
| ```json5 | ||
| "go.toolsEnvVars": { | ||
| "GOBIN": "path/to/gobin" | ||
| } | ||
| ``` | ||
|
|
||
| ## Install tools to a separate `GOPATH` | ||
|
|
||
| **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. | ||
|
|
||
| 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. | ||
|
|
||
| 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?--> | ||
|
|
||
| [Go modules]: https://blog.golang.org/using-go-modules |
Oops, something went wrong.