-
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.
_content/doc: document 'go install pkg@version'
For golang/go#33637 For golang/go#40276 Change-Id: I25ef2024867194bd7dc2e70157fef9123498f49d Reviewed-on: https://go-review.googlesource.com/c/website/+/285452 Trust: Jay Conrod <[email protected]> Run-TryBot: Jay Conrod <[email protected]> TryBot-Result: Go Bot <[email protected]> Reviewed-by: Bryan C. Mills <[email protected]>
- Loading branch information
1 parent
dd5775c
commit 4c4fb01
Showing
1 changed file
with
77 additions
and
4 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -948,7 +948,9 @@ which can be set to `on`, `off`, or `auto`. | |
| `go.mod` file: see [Module commands outside a module](#commands-outside). | ||
| * If `GO111MODULE=auto`, the `go` command runs in module-aware mode if a | ||
| `go.mod` file is present in the current directory or any parent directory. | ||
| In Go 1.15 and lower, this was the default behavior. | ||
| In Go 1.15 and lower, this was the default behavior. `go mod` subcommands | ||
| and `go install` with a [version query](#version-queries) run in module-aware | ||
| mode even if no `go.mod` file is present. | ||
|
|
||
| In module-aware mode, `GOPATH` no longer defines the meaning of imports during a | ||
| build, but it still stores downloaded dependencies (in `GOPATH/pkg/mod`; see | ||
|
|
@@ -1058,9 +1060,6 @@ go get [-d] [-t] [-u] [build flags] [packages] | |
| Examples: | ||
|
|
||
| ``` | ||
| # Install the latest version of a tool. | ||
| $ go get golang.org/x/tools/cmd/goimports | ||
| # Upgrade a specific module. | ||
| $ go get -d golang.org/x/net | ||
|
|
@@ -1164,6 +1163,80 @@ the `GOBIN` environment variable, which defaults to `$GOPATH/bin` or | |
| variable](#environment-variables) provides more fine-grained control and | ||
| should be used instead. | ||
|
|
||
| Since Go 1.16, [`go install`](#go-install) is the recommended command for | ||
| building and installing programs. When used with a version suffix (like | ||
| `@latest` or `@v1.4.6`), `go install` builds packages in module-aware mode, | ||
| ignoring the `go.mod` file in the current directory or any parent directory, | ||
| if there is one. | ||
|
|
||
| `go get` is more focused on managing requirements in `go.mod`. The `-d` flag | ||
| is deprecated, and in a future release, it will always be enabled. | ||
|
|
||
| ### `go install` {#go-install} | ||
|
|
||
| Usage: | ||
|
|
||
| ``` | ||
| go install [build flags] [packages] | ||
| ``` | ||
|
|
||
| Examples: | ||
|
|
||
| ``` | ||
| # Install the latest version of a program, | ||
| # ignoring go.mod in the current directory (if any). | ||
| $ go install golang.org/x/tools/gopls@latest | ||
| # Install a specific version of a program. | ||
| $ go install golang.org/x/tools/[email protected] | ||
| # Install a program at the version selected by the module in the current directory. | ||
| $ go install golang.org/x/tools/gopls | ||
| # Install all programs in a directory. | ||
| $ go install ./cmd/... | ||
| ``` | ||
|
|
||
| The `go install` command builds and installs the packages named by the paths | ||
| on the command line. Executables (`main` packages) are installed to the | ||
| directory named by the `GOBIN` environment variable, which defaults to | ||
| `$GOPATH/bin` or `$HOME/go/bin` if the `GOPATH` environment variable is not set. | ||
| Executables in `$GOROOT` are installed in `$GOROOT/bin` or `$GOTOOLDIR` instead | ||
| of `$GOBIN`. | ||
|
|
||
| Since Go 1.16, if the arguments have version suffixes (like `@latest` or | ||
| `@v1.0.0`), `go install` builds packages in module-aware mode, ignoring the | ||
| `go.mod` file in the current directory or any parent directory if there is | ||
| one. This is useful for installing executables without affecting the | ||
| dependencies of the main module. | ||
|
|
||
| To eliminate ambiguity about which module versions are used in the build, the | ||
| arguments must satisfy the following constraints: | ||
|
|
||
| * Arguments must be package paths or package patterns (with "`...`" wildcards). | ||
| They must not be standard packages (like `fmt`), meta-patterns (`std`, `cmd`, | ||
| `all`), or relative or absolute file paths. | ||
| * All arguments must have the same version suffix. Different queries are not | ||
| allowed, even if they refer to the same version. | ||
| * All arguments must refer to packages in the same module at the same version. | ||
| * No module is considered the [main module](#glos-main-module). If the module | ||
| containing packages named on the command line has a `go.mod` file, it must not | ||
| contain directives (`replace` and `exclude`) that would cause it to be | ||
| interpreted differently than if it were the main module. The module must not | ||
| require a higher version of itself. | ||
| * Package path arguments must refer to `main` packages. Pattern arguments | ||
| will only match `main` packages. | ||
|
|
||
| See [Version queries](#version-queries) for supported version query syntax. | ||
| Go 1.15 and lower did not support using version queries with `go install`. | ||
|
|
||
| If the arguments don't have version suffixes, `go install` may run in | ||
| module-aware mode or `GOPATH` mode, depending on the `GO111MODULE` environment | ||
| variable and the presence of a `go.mod` file. See [Module-aware | ||
| commands](#mod-commands) for details. If module-aware mode is enabled, `go | ||
| install` runs in the context of the main module, which may be different from the | ||
| module containing the package being installed. | ||
|
|
||
| ### `go list -m` {#go-list-m} | ||
|
|
||
| Usage: | ||
|
|
||