// Copyright 2011 The Go Authors. All rights reserved.

// Use of this source code is governed by a BSD-style

// license that can be found in the LICENSE file.

// Code generated by 'go test cmd/go -v -run=^TestDocsUpToDate$ -fixdocs'; DO NOT EDIT.

// Edit the documentation in other files and then execute 'go generate cmd/go' to generate this one.

// Go is a tool for managing Go source code.

//

// Usage:

//

// go <command> [arguments]

//

// The commands are:

//

// bug start a bug report

// build compile packages and dependencies

// clean remove object files and cached files

// doc show documentation for package or symbol

// env print Go environment information

// fix update packages to use new APIs

// fmt gofmt (reformat) package sources

// generate generate Go files by processing source

// get add dependencies to current module and install them

// install compile and install packages and dependencies

// list list packages or modules

// mod module maintenance

// work workspace maintenance

// run compile and run Go program

// telemetry manage telemetry data and settings

// test test packages

// tool run specified go tool

// version print Go version

// vet report likely mistakes in packages

//

// Use "go help <command>" for more information about a command.

//

// Additional help topics:

//

// buildconstraint build constraints

// buildjson build -json encoding

// buildmode build modes

// c calling between Go and C

// cache build and test caching

// environment environment variables

// filetype file types

// goauth GOAUTH environment variable

// go.mod the go.mod file

// gopath GOPATH environment variable

// goproxy module proxy protocol

// importpath import path syntax

// modules modules, module versions, and more

// module-auth module authentication using go.sum

// packages package lists and patterns

// private configuration for downloading non-public code

// testflag testing flags

// testfunc testing functions

// vcs controlling version control with GOVCS

//

// Use "go help <topic>" for more information about that topic.

//

// # Start a bug report

//

// Usage:

//

// go bug

//

// Bug opens the default browser and starts a new bug report.

// The report includes useful system information.

//

// # Compile packages and dependencies

//

// Usage:

//

// go build [-o output] [build flags] [packages]

//

// Build compiles the packages named by the import paths,

// along with their dependencies, but it does not install the results.

//

// If the arguments to build are a list of .go files from a single directory,

// build treats them as a list of source files specifying a single package.

//

// When compiling packages, build ignores files that end in '_test.go'.

//

// When compiling a single main package, build writes the resulting

// executable to an output file named after the last non-major-version

// component of the package import path. The '.exe' suffix is added

// when writing a Windows executable.

// So 'go build example/sam' writes 'sam' or 'sam.exe'.

// 'go build example.com/foo/v2' writes 'foo' or 'foo.exe', not 'v2.exe'.

//

// When compiling a package from a list of .go files, the executable

// is named after the first source file.

// 'go build ed.go rx.go' writes 'ed' or 'ed.exe'.

//

// When compiling multiple packages or a single non-main package,

// build compiles the packages but discards the resulting object,

// serving only as a check that the packages can be built.

//

// The -o flag forces build to write the resulting executable or object

// to the named output file or directory, instead of the default behavior described

// in the last two paragraphs. If the named output is an existing directory or

// ends with a slash or backslash, then any resulting executables

// will be written to that directory.

//

// The build flags are shared by the build, clean, get, install, list, run,

// and test commands:

//

// -C dir

// Change to dir before running the command.

// Any files named on the command line are interpreted after

// changing directories.

// If used, this flag must be the first one in the command line.

// -a

// force rebuilding of packages that are already up-to-date.

// -n

// print the commands but do not run them.

// -p n

// the number of programs, such as build commands or

// test binaries, that can be run in parallel.

// The default is GOMAXPROCS, normally the number of CPUs available.

// -race

// enable data race detection.

// Supported only on linux/amd64, freebsd/amd64, darwin/amd64, darwin/arm64, windows/amd64,

// linux/ppc64le and linux/arm64 (only for 48-bit VMA).

// -msan

// enable interoperation with memory sanitizer.

// Supported only on linux/amd64, linux/arm64, linux/loong64, freebsd/amd64

// and only with Clang/LLVM as the host C compiler.

// PIE build mode will be used on all platforms except linux/amd64.

// -asan

// enable interoperation with address sanitizer.

// Supported only on linux/arm64, linux/amd64, linux/loong64.

// Supported on linux/amd64 or linux/arm64 and only with GCC 7 and higher

// or Clang/LLVM 9 and higher.

// And supported on linux/loong64 only with Clang/LLVM 16 and higher.

// -cover

// enable code coverage instrumentation.

// -covermode set,count,atomic

// set the mode for coverage analysis.

// The default is "set" unless -race is enabled,

// in which case it is "atomic".

// The values:

// set: bool: does this statement run?

// count: int: how many times does this statement run?

// atomic: int: count, but correct in multithreaded tests;

// significantly more expensive.

// Sets -cover.

// -coverpkg pattern1,pattern2,pattern3

// For a build that targets package 'main' (e.g. building a Go

// executable), apply coverage analysis to each package whose

// import path matches the patterns. The default is to apply

// coverage analysis to packages in the main Go module. See

// 'go help packages' for a description of package patterns.

// Sets -cover.

// -v

// print the names of packages as they are compiled.

// -work

// print the name of the temporary work directory and

// do not delete it when exiting.

// -x

// print the commands.

// -asmflags '[pattern=]arg list'

// arguments to pass on each go tool asm invocation.

// -buildmode mode

// build mode to use. See 'go help buildmode' for more.

// -buildvcs

// Whether to stamp binaries with version control information

// ("true", "false", or "auto"). By default ("auto"), version control

// information is stamped into a binary if the main package, the main module

// containing it, and the current directory are all in the same repository.

// Use -buildvcs=false to always omit version control information, or

// -buildvcs=true to error out if version control information is available but

// cannot be included due to a missing tool or ambiguous directory structure.

// -compiler name

// name of compiler to use, as in runtime.Compiler (gccgo or gc).

// -gccgoflags '[pattern=]arg list'

// arguments to pass on each gccgo compiler/linker invocation.

// -gcflags '[pattern=]arg list'

// arguments to pass on each go tool compile invocation.

// -installsuffix suffix

// a suffix to use in the name of the package installation directory,

// in order to keep output separate from default builds.

// If using the -race flag, the install suffix is automatically set to race

// or, if set explicitly, has _race appended to it. Likewise for the -msan

// and -asan flags. Using a -buildmode option that requires non-default compile

// flags has a similar effect.

// -json

// Emit build output in JSON suitable for automated processing.

// See 'go help buildjson' for the encoding details.

// -ldflags '[pattern=]arg list'

// arguments to pass on each go tool link invocation.

// -linkshared

// build code that will be linked against shared libraries previously

// created with -buildmode=shared.

// -mod mode

// module download mode to use: readonly, vendor, or mod.

// By default, if a vendor directory is present and the go version in go.mod

// is 1.14 or higher, the go command acts as if -mod=vendor were set.

// Otherwise, the go command acts as if -mod=readonly were set.

// See https://golang.org/ref/mod#build-commands for details.

// -modcacherw

// leave newly-created directories in the module cache read-write

// instead of making them read-only.

// -modfile file

// in module aware mode, read (and possibly write) an alternate go.mod

// file instead of the one in the module root directory. A file named

// "go.mod" must still be present in order to determine the module root

// directory, but it is not accessed. When -modfile is specified, an

// alternate go.sum file is also used: its path is derived from the

// -modfile flag by trimming the ".mod" extension and appending ".sum".

// -overlay file

// read a JSON config file that provides an overlay for build operations.

// The file is a JSON object with a single field, named 'Replace', that

// maps each disk file path (a string) to its backing file path, so that

// a build will run as if the disk file path exists with the contents

// given by the backing file paths, or as if the disk file path does not

// exist if its backing file path is empty. Support for the -overlay flag

// has some limitations: importantly, cgo files included from outside the

// include path must be in the same directory as the Go package they are

// included from, overlays will not appear when binaries and tests are

// run through go run and go test respectively, and files beneath

// GOMODCACHE may not be replaced.

// -pgo file

// specify the file path of a profile for profile-guided optimization (PGO).

// When the special name "auto" is specified, for each main package in the

// build, the go command selects a file named "default.pgo" in the package's

// directory if that file exists, and applies it to the (transitive)

// dependencies of the main package (other packages are not affected).

// Special name "off" turns off PGO. The default is "auto".

// -pkgdir dir

// install and load all packages from dir instead of the usual locations.

// For example, when building with a non-standard configuration,

// use -pkgdir to keep generated packages in a separate location.

// -tags tag,list

// a comma-separated list of additional build tags to consider satisfied

// during the build. For more information about build tags, see

// 'go help buildconstraint'. (Earlier versions of Go used a

// space-separated list, and that form is deprecated but still recognized.)

// -trimpath

// remove all file system paths from the resulting executable.

// Instead of absolute file system paths, the recorded file names

// will begin either a module path@version (when using modules),

// or a plain import path (when using the standard library, or GOPATH).

// -toolexec 'cmd args'

// a program to use to invoke toolchain programs like vet and asm.

// For example, instead of running asm, the go command will run

// 'cmd args /path/to/asm <arguments for asm>'.

// The TOOLEXEC_IMPORTPATH environment variable will be set,

// matching 'go list -f {{.ImportPath}}' for the package being built.

//

// The -asmflags, -gccgoflags, -gcflags, and -ldflags flags accept a

// space-separated list of arguments to pass to an underlying tool

// during the build. To embed spaces in an element in the list, surround

// it with either single or double quotes. The argument list may be

// preceded by a package pattern and an equal sign, which restricts

// the use of that argument list to the building of packages matching

// that pattern (see 'go help packages' for a description of package

// patterns). Without a pattern, the argument list applies only to the

// packages named on the command line. The flags may be repeated

// with different patterns in order to specify different arguments for

// different sets of packages. If a package matches patterns given in

// multiple flags, the latest match on the command line wins.

// For example, 'go build -gcflags=-S fmt' prints the disassembly

// only for package fmt, while 'go build -gcflags=all=-S fmt'

// prints the disassembly for fmt and all its dependencies.

//

// For more about specifying packages, see 'go help packages'.

// For more about where packages and binaries are installed,

// run 'go help gopath'.

// For more about calling between Go and C/C++, run 'go help c'.

//

// Note: Build adheres to certain conventions such as those described

// by 'go help gopath'. Not all projects can follow these conventions,

// however. Installations that have their own conventions or that use

// a separate software build system may choose to use lower-level

// invocations such as 'go tool compile' and 'go tool link' to avoid

// some of the overheads and design decisions of the build tool.

//

// See also: go install, go get, go clean.

//

// # Remove object files and cached files

//

// Usage:

//

// go clean [-i] [-r] [-cache] [-testcache] [-modcache] [-fuzzcache] [build flags] [packages]

//

// Clean removes object files from package source directories.

// The go command builds most objects in a temporary directory,

// so go clean is mainly concerned with object files left by other

// tools or by manual invocations of go build.

//

// If a package argument is given or the -i or -r flag is set,

// clean removes the following files from each of the

// source directories corresponding to the import paths:

//

// _obj/ old object directory, left from Makefiles

// _test/ old test directory, left from Makefiles

// _testmain.go old gotest file, left from Makefiles

// test.out old test log, left from Makefiles

// build.out old test log, left from Makefiles

// *.[568ao] object files, left from Makefiles

//

// DIR(.exe) from go build

// DIR.test(.exe) from go test -c

// MAINFILE(.exe) from go build MAINFILE.go

// *.so from SWIG

//

// In the list, DIR represents the final path element of the

// directory, and MAINFILE is the base name of any Go source

// file in the directory that is not included when building

// the package.

//

// The -i flag causes clean to remove the corresponding installed

// archive or binary (what 'go install' would create).

//

// The -n flag causes clean to print the remove commands it would execute,

// but not run them.

//

// The -r flag causes clean to be applied recursively to all the

// dependencies of the packages named by the import paths.

//

// The -x flag causes clean to print remove commands as it executes them.

//

// The -cache flag causes clean to remove the entire go build cache.

//

// The -testcache flag causes clean to expire all test results in the

// go build cache.

//

// The -modcache flag causes clean to remove the entire module

// download cache, including unpacked source code of versioned

// dependencies.

//

// The -fuzzcache flag causes clean to remove files stored in the Go build

// cache for fuzz testing. The fuzzing engine caches files that expand

// code coverage, so removing them may make fuzzing less effective until

// new inputs are found that provide the same coverage. These files are

// distinct from those stored in testdata directory; clean does not remove

// those files.

//

// For more about build flags, see 'go help build'.

//

// For more about specifying packages, see 'go help packages'.

//

// # Show documentation for package or symbol

//

// Usage:

//

// go doc [doc flags] [package|[package.]symbol[.methodOrField]]

//

// Doc prints the documentation comments associated with the item identified by its

// arguments (a package, const, func, type, var, method, or struct field)

// followed by a one-line summary of each of the first-level items "under"

// that item (package-level declarations for a package, methods for a type,

// etc.).

//

// Doc accepts zero, one, or two arguments.

//

// Given no arguments, that is, when run as

//

// go doc

//

// it prints the package documentation for the package in the current directory.

// If the package is a command (package main), the exported symbols of the package

// are elided from the presentation unless the -cmd flag is provided.

//

// When run with one argument, the argument is treated as a Go-syntax-like

// representation of the item to be documented. What the argument selects depends

// on what is installed in GOROOT and GOPATH, as well as the form of the argument,

// which is schematically one of these:

//

// go doc <pkg>

// go doc <sym>[.<methodOrField>]

// go doc [<pkg>.]<sym>[.<methodOrField>]

// go doc [<pkg>.][<sym>.]<methodOrField>

//

// The first item in this list matched by the argument is the one whose documentation

// is printed. (See the examples below.) However, if the argument starts with a capital

// letter it is assumed to identify a symbol or method in the current directory.

//

// For packages, the order of scanning is determined lexically in breadth-first order.

// That is, the package presented is the one that matches the search and is nearest

// the root and lexically first at its level of the hierarchy. The GOROOT tree is

// always scanned in its entirety before GOPATH.

//

// If there is no package specified or matched, the package in the current

// directory is selected, so "go doc Foo" shows the documentation for symbol Foo in

// the current package.

//

// The package path must be either a qualified path or a proper suffix of a

// path. The go tool's usual package mechanism does not apply: package path

// elements like . and ... are not implemented by go doc.

//

// When run with two arguments, the first is a package path (full path or suffix),

// and the second is a symbol, or symbol with method or struct field:

//

// go doc <pkg> <sym>[.<methodOrField>]

//

// In all forms, when matching symbols, lower-case letters in the argument match

// either case but upper-case letters match exactly. This means that there may be

// multiple matches of a lower-case argument in a package if different symbols have

// different cases. If this occurs, documentation for all matches is printed.

//

// Examples:

//

// go doc

// Show documentation for current package.

// go doc Foo

// Show documentation for Foo in the current package.

// (Foo starts with a capital letter so it cannot match

// a package path.)

// go doc encoding/json

// Show documentation for the encoding/json package.

// go doc json

// Shorthand for encoding/json.

// go doc json.Number (or go doc json.number)

// Show documentation and method summary for json.Number.

// go doc json.Number.Int64 (or go doc json.number.int64)

// Show documentation for json.Number's Int64 method.

// go doc cmd/doc

// Show package docs for the doc command.

// go doc -cmd cmd/doc

// Show package docs and exported symbols within the doc command.

// go doc template.new

// Show documentation for html/template's New function.

// (html/template is lexically before text/template)

// go doc text/template.new # One argument

// Show documentation for text/template's New function.

// go doc text/template new # Two arguments

// Show documentation for text/template's New function.

//

// At least in the current tree, these invocations all print the

// documentation for json.Decoder's Decode method:

//

// go doc json.Decoder.Decode

// go doc json.decoder.decode

// go doc json.decode

// cd go/src/encoding/json; go doc decode

//

// Flags:

//

// -all

// Show all the documentation for the package.

// -c

// Respect case when matching symbols.

// -cmd

// Treat a command (package main) like a regular package.

// Otherwise package main's exported symbols are hidden

// when showing the package's top-level documentation.

// -short

// One-line representation for each symbol.

// -src

// Show the full source code for the symbol. This will

// display the full Go source of its declaration and

// definition, such as a function definition (including

// the body), type declaration or enclosing const

// block. The output may therefore include unexported

// details.

// -u

// Show documentation for unexported as well as exported

// symbols, methods, and fields.

//

// # Print Go environment information

//

// Usage:

//

// go env [-json] [-changed] [-u] [-w] [var ...]

//

// Env prints Go environment information.

//

// By default env prints information as a shell script

// (on Windows, a batch file). If one or more variable

// names is given as arguments, env prints the value of

// each named variable on its own line.

//

// The -json flag prints the environment in JSON format

// instead of as a shell script.

//

// The -u flag requires one or more arguments and unsets

// the default setting for the named environment variables,

// if one has been set with 'go env -w'.

//

// The -w flag requires one or more arguments of the

// form NAME=VALUE and changes the default settings

// of the named environment variables to the given values.

//

// The -changed flag prints only those settings whose effective

// value differs from the default value that would be obtained in

// an empty environment with no prior uses of the -w flag.

//

// For more about environment variables, see 'go help environment'.

//

// # Update packages to use new APIs

//

// Usage:

//

// go fix [-fix list] [packages]

//

// Fix runs the Go fix command on the packages named by the import paths.

//

// The -fix flag sets a comma-separated list of fixes to run.

// The default is all known fixes.

// (Its value is passed to 'go tool fix -r'.)

//

// For more about fix, see 'go doc cmd/fix'.

// For more about specifying packages, see 'go help packages'.

//

// To run fix with other options, run 'go tool fix'.

//

// See also: go fmt, go vet.

//

// # Gofmt (reformat) package sources

//

// Usage:

//

// go fmt [-n] [-x] [packages]

//

// Fmt runs the command 'gofmt -l -w' on the packages named

// by the import paths. It prints the names of the files that are modified.

//

// For more about gofmt, see 'go doc cmd/gofmt'.

// For more about specifying packages, see 'go help packages'.

//

// The -n flag prints commands that would be executed.

// The -x flag prints commands as they are executed.

//

// The -mod flag's value sets which module download mode

// to use: readonly or vendor. See 'go help modules' for more.

//

// To run gofmt with specific options, run gofmt itself.

//

// See also: go fix, go vet.

//

// # Generate Go files by processing source

//

// Usage:

//

// go generate [-run regexp] [-n] [-v] [-x] [build flags] [file.go... | packages]

//

// Generate runs commands described by directives within existing

// files. Those commands can run any process but the intent is to

// create or update Go source files.

//

// Go generate is never run automatically by go build, go test,

// and so on. It must be run explicitly.

//

// Go generate scans the file for directives, which are lines of

// the form,

//

// //go:generate command argument...

//

// (note: no leading spaces and no space in "//go") where command

// is the generator to be run, corresponding to an executable file

// that can be run locally. It must either be in the shell path

// (gofmt), a fully qualified path (/usr/you/bin/mytool), or a

// command alias, described below.

//

// Note that go generate does not parse the file, so lines that look

// like directives in comments or multiline strings will be treated

// as directives.

//

// The arguments to the directive are space-separated tokens or

// double-quoted strings passed to the generator as individual

// arguments when it is run.

//

// Quoted strings use Go syntax and are evaluated before execution; a

// quoted string appears as a single argument to the generator.

//

// To convey to humans and machine tools that code is generated,

// generated source should have a line that matches the following

// regular expression (in Go syntax):

//

// ^// Code generated .* DO NOT EDIT\.$

//

// This line must appear before the first non-comment, non-blank

// text in the file.

//

// Go generate sets several variables when it runs the generator:

//

// $GOARCH

// The execution architecture (arm, amd64, etc.)

// $GOOS

// The execution operating system (linux, windows, etc.)

// $GOFILE

// The base name of the file.

// $GOLINE

// The line number of the directive in the source file.

// $GOPACKAGE

// The name of the package of the file containing the directive.

// $GOROOT

// The GOROOT directory for the 'go' command that invoked the

// generator, containing the Go toolchain and standard library.

// $DOLLAR

// A dollar sign.

// $PATH

// The $PATH of the parent process, with $GOROOT/bin

// placed at the beginning. This causes generators

// that execute 'go' commands to use the same 'go'

// as the parent 'go generate' command.

//

// Other than variable substitution and quoted-string evaluation, no

// special processing such as "globbing" is performed on the command

// line.

//

// As a last step before running the command, any invocations of any

// environment variables with alphanumeric names, such as $GOFILE or

// $HOME, are expanded throughout the command line. The syntax for

// variable expansion is $NAME on all operating systems. Due to the

// order of evaluation, variables are expanded even inside quoted

// strings. If the variable NAME is not set, $NAME expands to the

// empty string.

//

// A directive of the form,

//

// //go:generate -command xxx args...

//

// specifies, for the remainder of this source file only, that the

// string xxx represents the command identified by the arguments. This

// can be used to create aliases or to handle multiword generators.

// For example,

//

// //go:generate -command foo go tool foo

//

// specifies that the command "foo" represents the generator

// "go tool foo".

//

// Generate processes packages in the order given on the command line,

// one at a time. If the command line lists .go files from a single directory,

// they are treated as a single package. Within a package, generate processes the

// source files in a package in file name order, one at a time. Within

// a source file, generate runs generators in the order they appear

// in the file, one at a time. The go generate tool also sets the build

// tag "generate" so that files may be examined by go generate but ignored

// during build.

//

// For packages with invalid code, generate processes only source files with a

// valid package clause.

//

// If any generator returns an error exit status, "go generate" skips

// all further processing for that package.

//

// The generator is run in the package's source directory.

//

// Go generate accepts two specific flags:

//

// -run=""

// if non-empty, specifies a regular expression to select

// directives whose full original source text (excluding

// any trailing spaces and final newline) matches the

// expression.

//

// -skip=""

// if non-empty, specifies a regular expression to suppress

// directives whose full original source text (excluding

// any trailing spaces and final newline) matches the

// expression. If a directive matches both the -run and

// the -skip arguments, it is skipped.

//

// It also accepts the standard build flags including -v, -n, and -x.

// The -v flag prints the names of packages and files as they are

// processed.

// The -n flag prints commands that would be executed.

// The -x flag prints commands as they are executed.

//

// For more about build flags, see 'go help build'.

//

// For more about specifying packages, see 'go help packages'.

//

// # Add dependencies to current module and install them

//

// Usage:

//

// go get [-t] [-u] [-tool] [build flags] [packages]

//

// Get resolves its command-line arguments to packages at specific module versions,

// updates go.mod to require those versions, and downloads source code into the

// module cache.

//

// To add a dependency for a package or upgrade it to its latest version:

//

// go get example.com/pkg

//

// To upgrade or downgrade a package to a specific version:

//

// go get example.com/pkg@v1.2.3

//

// To remove a dependency on a module and downgrade modules that require it:

//

// go get example.com/mod@none

//

// To upgrade the minimum required Go version to the latest released Go version:

//

// go get go@latest

//

// To upgrade the Go toolchain to the latest patch release of the current Go toolchain:

//

// go get toolchain@patch

//

// See https://golang.org/ref/mod#go-get for details.

//

// In earlier versions of Go, 'go get' was used to build and install packages.

// Now, 'go get' is dedicated to adjusting dependencies in go.mod. 'go install'

// may be used to build and install commands instead. When a version is specified,

// 'go install' runs in module-aware mode and ignores the go.mod file in the

// current directory. For example:

//

// go install example.com/pkg@v1.2.3

// go install example.com/pkg@latest

//

// See 'go help install' or https://golang.org/ref/mod#go-install for details.

//

// 'go get' accepts the following flags.

//

// The -t flag instructs get to consider modules needed to build tests of

// packages specified on the command line.

//

// The -u flag instructs get to update modules providing dependencies

// of packages named on the command line to use newer minor or patch

// releases when available.

//

// The -u=patch flag (not -u patch) also instructs get to update dependencies,

// but changes the default to select patch releases.

//

// When the -t and -u flags are used together, get will update

// test dependencies as well.

//

// The -tool flag instructs go to add a matching tool line to go.mod for each

// listed package. If -tool is used with @none, the line will be removed.

//

// The -x flag prints commands as they are executed. This is useful for

// debugging version control commands when a module is downloaded directly

// from a repository.

//

// For more about build flags, see 'go help build'.

//

// For more about modules, see https://golang.org/ref/mod.

//

// For more about using 'go get' to update the minimum Go version and

// suggested Go toolchain, see https://go.dev/doc/toolchain.

//

// For more about specifying packages, see 'go help packages'.

//

// See also: go build, go install, go clean, go mod.

//

// # Compile and install packages and dependencies

//

// Usage:

//

// go install [build flags] [packages]

//

// Install compiles and installs the packages named by the import paths.

//

// Executables are installed in 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.

//

// 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.

//

// - Package path arguments must refer to main packages. Pattern arguments

// will only match main packages.

//

// - No module is considered the "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.

//

// - Vendor directories are not used in any module. (Vendor directories are not

// included in the module zip files downloaded by '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 'go help modules' for details.

// If module-aware mode is enabled, "go install" runs in the context of the main

// module.

//

// When module-aware mode is disabled, non-main packages are installed in the

// directory $GOPATH/pkg/$GOOS_$GOARCH. When module-aware mode is enabled,

// non-main packages are built and cached but not installed.

//

// Before Go 1.20, the standard library was installed to

// $GOROOT/pkg/$GOOS_$GOARCH.

// Starting in Go 1.20, the standard library is built and cached but not installed.

// Setting GODEBUG=installgoroot=all restores the use of

// $GOROOT/pkg/$GOOS_$GOARCH.

//

// For more about build flags, see 'go help build'.

//

// For more about specifying packages, see 'go help packages'.

//

// See also: go build, go get, go clean.

//

// # List packages or modules

//

// Usage:

//

// go list [-f format] [-json] [-m] [list flags] [build flags] [packages]

//

// List lists the named packages, one per line.

// The most commonly-used flags are -f and -json, which control the form

// of the output printed for each package. Other list flags, documented below,

// control more specific details.

//

// The default output shows the package import path:

//

// bytes

// encoding/json

// github.com/gorilla/mux

// golang.org/x/net/html

//

// The -f flag specifies an alternate format for the list, using the

// syntax of package template. The default output is equivalent

// to -f '{{.ImportPath}}'. The struct being passed to the template is:

//

// type Package struct {

// Dir string // directory containing package sources

// ImportPath string // import path of package in dir

// ImportComment string // path in import comment on package statement

// Name string // package name

// Doc string // package documentation string

// Target string // install path

// Shlib string // the shared library that contains this package (only set when -linkshared)

// Goroot bool // is this package in the Go root?

// Standard bool // is this package part of the standard Go library?

// Stale bool // would 'go install' do anything for this package?

// StaleReason string // explanation for Stale==true

// Root string // Go root or Go path dir containing this package

// ConflictDir string // this directory shadows Dir in $GOPATH

// BinaryOnly bool // binary-only package (no longer supported)

// ForTest string // package is only for use in named test

// Export string // file containing export data (when using -export)

// BuildID string // build ID of the compiled package (when using -export)

// Module *Module // info about package's containing module, if any (can be nil)

// Match []string // command-line patterns matching this package

// DepOnly bool // package is only a dependency, not explicitly listed

// DefaultGODEBUG string // default GODEBUG setting, for main packages

//

// // Source files

// GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles)

// CgoFiles []string // .go source files that import "C"

// CompiledGoFiles []string // .go files presented to compiler (when using -compiled)

// IgnoredGoFiles []string // .go source files ignored due to build constraints

// IgnoredOtherFiles []string // non-.go source files ignored due to build constraints

// CFiles []string // .c source files

// CXXFiles []string // .cc, .cxx and .cpp source files

// MFiles []string // .m source files

// HFiles []string // .h, .hh, .hpp and .hxx source files

// FFiles []string // .f, .F, .for and .f90 Fortran source files

// SFiles []string // .s source files

// SwigFiles []string // .swig files

// SwigCXXFiles []string // .swigcxx files

// SysoFiles []string // .syso object files to add to archive

// TestGoFiles []string // _test.go files in package

// XTestGoFiles []string // _test.go files outside package

//

// // Embedded files

// EmbedPatterns []string // //go:embed patterns

// EmbedFiles []string // files matched by EmbedPatterns

// TestEmbedPatterns []string // //go:embed patterns in TestGoFiles

// TestEmbedFiles []string // files matched by TestEmbedPatterns

// XTestEmbedPatterns []string // //go:embed patterns in XTestGoFiles

// XTestEmbedFiles []string // files matched by XTestEmbedPatterns

//

// // Cgo directives

// CgoCFLAGS []string // cgo: flags for C compiler

// CgoCPPFLAGS []string // cgo: flags for C preprocessor

// CgoCXXFLAGS []string // cgo: flags for C++ compiler

// CgoFFLAGS []string // cgo: flags for Fortran compiler

// CgoLDFLAGS []string // cgo: flags for linker

// CgoPkgConfig []string // cgo: pkg-config names

//

// // Dependency information

// Imports []string // import paths used by this package

// ImportMap map[string]string // map from source import to ImportPath (identity entries omitted)

// Deps []string // all (recursively) imported dependencies

// TestImports []string // imports from TestGoFiles

// XTestImports []string // imports from XTestGoFiles

//

// // Error information

// Incomplete bool // this package or a dependency has an error

// Error *PackageError // error loading package

// DepsErrors []*PackageError // errors loading dependencies

// }

//

// Packages stored in vendor directories report an ImportPath that includes the

// path to the vendor directory (for example, "d/vendor/p" instead of "p"),

// so that the ImportPath uniquely identifies a given copy of a package.

// The Imports, Deps, TestImports, and XTestImports lists also contain these

// expanded import paths. See golang.org/s/go15vendor for more about vendoring.

//

// The error information, if any, is

//

// type PackageError struct {

// ImportStack []string // shortest path from package named on command line to this one

// Pos string // position of error (if present, file:line:col)

// Err string // the error itself

// }

//

// The module information is a Module struct, defined in the discussion

// of list -m below.

//

// The template function "join" calls strings.Join.

//

// The template function "context" returns the build context, defined as:

//

// type Context struct {

// GOARCH string // target architecture

// GOOS string // target operating system

// GOROOT string // Go root

// GOPATH string // Go path

// CgoEnabled bool // whether cgo can be used

// UseAllFiles bool // use files regardless of //go:build lines, file names

// Compiler string // compiler to assume when computing target paths

// BuildTags []string // build constraints to match in //go:build lines

// ToolTags []string // toolchain-specific build constraints

// ReleaseTags []string // releases the current release is compatible with

// InstallSuffix string // suffix to use in the name of the install dir

// }

//

// For more information about the meaning of these fields see the documentation

// for the go/build package's Context type.

//

// The -json flag causes the package data to be printed in JSON format

// instead of using the template format. The JSON flag can optionally be

// provided with a set of comma-separated required field names to be output.

// If so, those required fields will always appear in JSON output, but

// others may be omitted to save work in computing the JSON struct.

//

// The -compiled flag causes list to set CompiledGoFiles to the Go source

// files presented to the compiler. Typically this means that it repeats

// the files listed in GoFiles and then also adds the Go code generated

// by processing CgoFiles and SwigFiles. The Imports list contains the

// union of all imports from both GoFiles and CompiledGoFiles.

//

// The -deps flag causes list to iterate over not just the named packages

// but also all their dependencies. It visits them in a depth-first post-order

// traversal, so that a package is listed only after all its dependencies.

// Packages not explicitly listed on the command line will have the DepOnly

// field set to true.

//

// The -e flag changes the handling of erroneous packages, those that

// cannot be found or are malformed. By default, the list command

// prints an error to standard error for each erroneous package and

// omits the packages from consideration during the usual printing.

// With the -e flag, the list command never prints errors to standard

// error and instead processes the erroneous packages with the usual

// printing. Erroneous packages will have a non-empty ImportPath and

// a non-nil Error field; other information may or may not be missing

// (zeroed).

//

// The -export flag causes list to set the Export field to the name of a

// file containing up-to-date export information for the given package,

// and the BuildID field to the build ID of the compiled package.

//

// The -find flag causes list to identify the named packages but not

// resolve their dependencies: the Imports and Deps lists will be empty.

// With the -find flag, the -deps, -test and -export commands cannot be

// used.

//

// The -test flag causes list to report not only the named packages

// but also their test binaries (for packages with tests), to convey to

// source code analysis tools exactly how test binaries are constructed.

// The reported import path for a test binary is the import path of

// the package followed by a ".test" suffix, as in "math/rand.test".

// When building a test, it is sometimes necessary to rebuild certain

// dependencies specially for that test (most commonly the tested

// package itself). The reported import path of a package recompiled

// for a particular test binary is followed by a space and the name of

// the test binary in brackets, as in "math/rand [math/rand.test]"

// or "regexp [sort.test]". The ForTest field is also set to the name

// of the package being tested ("math/rand" or "sort" in the previous

// examples).

//

// The Dir, Target, Shlib, Root, ConflictDir, and Export file paths

// are all absolute paths.

//

// By default, the lists GoFiles, CgoFiles, and so on hold names of files in Dir

// (that is, paths relative to Dir, not absolute paths).

// The generated files added when using the -compiled and -test flags

// are absolute paths referring to cached copies of generated Go source files.

// Although they are Go source files, the paths may not end in ".go".

//

// The -m flag causes list to list modules instead of packages.

//

// When listing modules, the -f flag still specifies a format template