1 // Copyright 2011 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
5 // Code generated by mkalldocs.sh; DO NOT EDIT.
6 // Edit the documentation in other files and rerun mkalldocs.sh to generate this one.
8 // Go is a tool for managing Go source code.
12 // go <command> [arguments]
16 // bug start a bug report
17 // build compile packages and dependencies
18 // clean remove object files and cached files
19 // doc show documentation for package or symbol
20 // env print Go environment information
21 // fix update packages to use new APIs
22 // fmt gofmt (reformat) package sources
23 // generate generate Go files by processing source
24 // get add dependencies to current module and install them
25 // install compile and install packages and dependencies
26 // list list packages or modules
27 // mod module maintenance
28 // run compile and run Go program
30 // tool run specified go tool
31 // version print Go version
32 // vet report likely mistakes in packages
34 // Use "go help <command>" for more information about a command.
36 // Additional help topics:
38 // buildconstraint build constraints
39 // buildmode build modes
40 // c calling between Go and C
41 // cache build and test caching
42 // environment environment variables
43 // filetype file types
44 // go.mod the go.mod file
45 // gopath GOPATH environment variable
46 // gopath-get legacy GOPATH go get
47 // goproxy module proxy protocol
48 // importpath import path syntax
49 // modules modules, module versions, and more
50 // module-get module-aware go get
51 // module-auth module authentication using go.sum
52 // packages package lists and patterns
53 // private configuration for downloading non-public code
54 // testflag testing flags
55 // testfunc testing functions
57 // vcs controlling version control with GOVCS
59 // Use "go help <topic>" for more information about that topic.
68 // Bug opens the default browser and starts a new bug report.
69 // The report includes useful system information.
72 // Compile packages and dependencies
76 // go build [-o output] [build flags] [packages]
78 // Build compiles the packages named by the import paths,
79 // along with their dependencies, but it does not install the results.
81 // If the arguments to build are a list of .go files from a single directory,
82 // build treats them as a list of source files specifying a single package.
84 // When compiling packages, build ignores files that end in '_test.go'.
86 // When compiling a single main package, build writes
87 // the resulting executable to an output file named after
88 // the first source file ('go build ed.go rx.go' writes 'ed' or 'ed.exe')
89 // or the source code directory ('go build unix/sam' writes 'sam' or 'sam.exe').
90 // The '.exe' suffix is added when writing a Windows executable.
92 // When compiling multiple packages or a single non-main package,
93 // build compiles the packages but discards the resulting object,
94 // serving only as a check that the packages can be built.
96 // The -o flag forces build to write the resulting executable or object
97 // to the named output file or directory, instead of the default behavior described
98 // in the last two paragraphs. If the named output is an existing directory or
99 // ends with a slash or backslash, then any resulting executables
100 // will be written to that directory.
102 // The -i flag installs the packages that are dependencies of the target.
103 // The -i flag is deprecated. Compiled packages are cached automatically.
105 // The build flags are shared by the build, clean, get, install, list, run,
106 // and test commands:
109 // force rebuilding of packages that are already up-to-date.
111 // print the commands but do not run them.
113 // the number of programs, such as build commands or
114 // test binaries, that can be run in parallel.
115 // The default is GOMAXPROCS, normally the number of CPUs available.
117 // enable data race detection.
118 // Supported only on linux/amd64, freebsd/amd64, darwin/amd64, windows/amd64,
119 // linux/ppc64le and linux/arm64 (only for 48-bit VMA).
121 // enable interoperation with memory sanitizer.
122 // Supported only on linux/amd64, linux/arm64
123 // and only with Clang/LLVM as the host C compiler.
124 // On linux/arm64, pie build mode will be used.
126 // print the names of packages as they are compiled.
128 // print the name of the temporary work directory and
129 // do not delete it when exiting.
131 // print the commands.
133 // -asmflags '[pattern=]arg list'
134 // arguments to pass on each go tool asm invocation.
136 // build mode to use. See 'go help buildmode' for more.
138 // name of compiler to use, as in runtime.Compiler (gccgo or gc).
139 // -gccgoflags '[pattern=]arg list'
140 // arguments to pass on each gccgo compiler/linker invocation.
141 // -gcflags '[pattern=]arg list'
142 // arguments to pass on each go tool compile invocation.
143 // -installsuffix suffix
144 // a suffix to use in the name of the package installation directory,
145 // in order to keep output separate from default builds.
146 // If using the -race flag, the install suffix is automatically set to race
147 // or, if set explicitly, has _race appended to it. Likewise for the -msan
148 // flag. Using a -buildmode option that requires non-default compile flags
149 // has a similar effect.
150 // -ldflags '[pattern=]arg list'
151 // arguments to pass on each go tool link invocation.
153 // build code that will be linked against shared libraries previously
154 // created with -buildmode=shared.
156 // module download mode to use: readonly, vendor, or mod.
157 // By default, if a vendor directory is present and the go version in go.mod
158 // is 1.14 or higher, the go command acts as if -mod=vendor were set.
159 // Otherwise, the go command acts as if -mod=readonly were set.
160 // See https://golang.org/ref/mod#build-commands for details.
162 // leave newly-created directories in the module cache read-write
163 // instead of making them read-only.
165 // in module aware mode, read (and possibly write) an alternate go.mod
166 // file instead of the one in the module root directory. A file named
167 // "go.mod" must still be present in order to determine the module root
168 // directory, but it is not accessed. When -modfile is specified, an
169 // alternate go.sum file is also used: its path is derived from the
170 // -modfile flag by trimming the ".mod" extension and appending ".sum".
172 // read a JSON config file that provides an overlay for build operations.
173 // The file is a JSON struct with a single field, named 'Replace', that
174 // maps each disk file path (a string) to its backing file path, so that
175 // a build will run as if the disk file path exists with the contents
176 // given by the backing file paths, or as if the disk file path does not
177 // exist if its backing file path is empty. Support for the -overlay flag
178 // has some limitations: importantly, cgo files included from outside the
179 // include path must be in the same directory as the Go package they are
180 // included from, and overlays will not appear when binaries and tests are
181 // run through go run and go test respectively.
183 // install and load all packages from dir instead of the usual locations.
184 // For example, when building with a non-standard configuration,
185 // use -pkgdir to keep generated packages in a separate location.
187 // a comma-separated list of build tags to consider satisfied during the
188 // build. For more information about build tags, see the description of
189 // build constraints in the documentation for the go/build package.
190 // (Earlier versions of Go used a space-separated list, and that form
191 // is deprecated but still recognized.)
193 // remove all file system paths from the resulting executable.
194 // Instead of absolute file system paths, the recorded file names
195 // will begin with either "go" (for the standard library),
196 // or a module path@version (when using modules),
197 // or a plain import path (when using GOPATH).
198 // -toolexec 'cmd args'
199 // a program to use to invoke toolchain programs like vet and asm.
200 // For example, instead of running asm, the go command will run
201 // 'cmd args /path/to/asm <arguments for asm>'.
202 // The TOOLEXEC_IMPORTPATH environment variable will be set,
203 // matching 'go list -f {{.ImportPath}}' for the package being built.
205 // The -asmflags, -gccgoflags, -gcflags, and -ldflags flags accept a
206 // space-separated list of arguments to pass to an underlying tool
207 // during the build. To embed spaces in an element in the list, surround
208 // it with either single or double quotes. The argument list may be
209 // preceded by a package pattern and an equal sign, which restricts
210 // the use of that argument list to the building of packages matching
211 // that pattern (see 'go help packages' for a description of package
212 // patterns). Without a pattern, the argument list applies only to the
213 // packages named on the command line. The flags may be repeated
214 // with different patterns in order to specify different arguments for
215 // different sets of packages. If a package matches patterns given in
216 // multiple flags, the latest match on the command line wins.
217 // For example, 'go build -gcflags=-S fmt' prints the disassembly
218 // only for package fmt, while 'go build -gcflags=all=-S fmt'
219 // prints the disassembly for fmt and all its dependencies.
221 // For more about specifying packages, see 'go help packages'.
222 // For more about where packages and binaries are installed,
223 // run 'go help gopath'.
224 // For more about calling between Go and C/C++, run 'go help c'.
226 // Note: Build adheres to certain conventions such as those described
227 // by 'go help gopath'. Not all projects can follow these conventions,
228 // however. Installations that have their own conventions or that use
229 // a separate software build system may choose to use lower-level
230 // invocations such as 'go tool compile' and 'go tool link' to avoid
231 // some of the overheads and design decisions of the build tool.
233 // See also: go install, go get, go clean.
236 // Remove object files and cached files
240 // go clean [clean flags] [build flags] [packages]
242 // Clean removes object files from package source directories.
243 // The go command builds most objects in a temporary directory,
244 // so go clean is mainly concerned with object files left by other
245 // tools or by manual invocations of go build.
247 // If a package argument is given or the -i or -r flag is set,
248 // clean removes the following files from each of the
249 // source directories corresponding to the import paths:
251 // _obj/ old object directory, left from Makefiles
252 // _test/ old test directory, left from Makefiles
253 // _testmain.go old gotest file, left from Makefiles
254 // test.out old test log, left from Makefiles
255 // build.out old test log, left from Makefiles
256 // *.[568ao] object files, left from Makefiles
258 // DIR(.exe) from go build
259 // DIR.test(.exe) from go test -c
260 // MAINFILE(.exe) from go build MAINFILE.go
263 // In the list, DIR represents the final path element of the
264 // directory, and MAINFILE is the base name of any Go source
265 // file in the directory that is not included when building
268 // The -i flag causes clean to remove the corresponding installed
269 // archive or binary (what 'go install' would create).
271 // The -n flag causes clean to print the remove commands it would execute,
274 // The -r flag causes clean to be applied recursively to all the
275 // dependencies of the packages named by the import paths.
277 // The -x flag causes clean to print remove commands as it executes them.
279 // The -cache flag causes clean to remove the entire go build cache.
281 // The -testcache flag causes clean to expire all test results in the
284 // The -modcache flag causes clean to remove the entire module
285 // download cache, including unpacked source code of versioned
288 // The -fuzzcache flag causes clean to remove values used for fuzz testing.
290 // For more about build flags, see 'go help build'.
292 // For more about specifying packages, see 'go help packages'.
295 // Show documentation for package or symbol
299 // go doc [doc flags] [package|[package.]symbol[.methodOrField]]
301 // Doc prints the documentation comments associated with the item identified by its
302 // arguments (a package, const, func, type, var, method, or struct field)
303 // followed by a one-line summary of each of the first-level items "under"
304 // that item (package-level declarations for a package, methods for a type,
307 // Doc accepts zero, one, or two arguments.
309 // Given no arguments, that is, when run as
313 // it prints the package documentation for the package in the current directory.
314 // If the package is a command (package main), the exported symbols of the package
315 // are elided from the presentation unless the -cmd flag is provided.
317 // When run with one argument, the argument is treated as a Go-syntax-like
318 // representation of the item to be documented. What the argument selects depends
319 // on what is installed in GOROOT and GOPATH, as well as the form of the argument,
320 // which is schematically one of these:
323 // go doc <sym>[.<methodOrField>]
324 // go doc [<pkg>.]<sym>[.<methodOrField>]
325 // go doc [<pkg>.][<sym>.]<methodOrField>
327 // The first item in this list matched by the argument is the one whose documentation
328 // is printed. (See the examples below.) However, if the argument starts with a capital
329 // letter it is assumed to identify a symbol or method in the current directory.
331 // For packages, the order of scanning is determined lexically in breadth-first order.
332 // That is, the package presented is the one that matches the search and is nearest
333 // the root and lexically first at its level of the hierarchy. The GOROOT tree is
334 // always scanned in its entirety before GOPATH.
336 // If there is no package specified or matched, the package in the current
337 // directory is selected, so "go doc Foo" shows the documentation for symbol Foo in
338 // the current package.
340 // The package path must be either a qualified path or a proper suffix of a
341 // path. The go tool's usual package mechanism does not apply: package path
342 // elements like . and ... are not implemented by go doc.
344 // When run with two arguments, the first must be a full package path (not just a
345 // suffix), and the second is a symbol, or symbol with method or struct field.
346 // This is similar to the syntax accepted by godoc:
348 // go doc <pkg> <sym>[.<methodOrField>]
350 // In all forms, when matching symbols, lower-case letters in the argument match
351 // either case but upper-case letters match exactly. This means that there may be
352 // multiple matches of a lower-case argument in a package if different symbols have
353 // different cases. If this occurs, documentation for all matches is printed.
357 // Show documentation for current package.
359 // Show documentation for Foo in the current package.
360 // (Foo starts with a capital letter so it cannot match
362 // go doc encoding/json
363 // Show documentation for the encoding/json package.
365 // Shorthand for encoding/json.
366 // go doc json.Number (or go doc json.number)
367 // Show documentation and method summary for json.Number.
368 // go doc json.Number.Int64 (or go doc json.number.int64)
369 // Show documentation for json.Number's Int64 method.
371 // Show package docs for the doc command.
372 // go doc -cmd cmd/doc
373 // Show package docs and exported symbols within the doc command.
374 // go doc template.new
375 // Show documentation for html/template's New function.
376 // (html/template is lexically before text/template)
377 // go doc text/template.new # One argument
378 // Show documentation for text/template's New function.
379 // go doc text/template new # Two arguments
380 // Show documentation for text/template's New function.
382 // At least in the current tree, these invocations all print the
383 // documentation for json.Decoder's Decode method:
385 // go doc json.Decoder.Decode
386 // go doc json.decoder.decode
387 // go doc json.decode
388 // cd go/src/encoding/json; go doc decode
392 // Show all the documentation for the package.
394 // Respect case when matching symbols.
396 // Treat a command (package main) like a regular package.
397 // Otherwise package main's exported symbols are hidden
398 // when showing the package's top-level documentation.
400 // One-line representation for each symbol.
402 // Show the full source code for the symbol. This will
403 // display the full Go source of its declaration and
404 // definition, such as a function definition (including
405 // the body), type declaration or enclosing const
406 // block. The output may therefore include unexported
409 // Show documentation for unexported as well as exported
410 // symbols, methods, and fields.
413 // Print Go environment information
417 // go env [-json] [-u] [-w] [var ...]
419 // Env prints Go environment information.
421 // By default env prints information as a shell script
422 // (on Windows, a batch file). If one or more variable
423 // names is given as arguments, env prints the value of
424 // each named variable on its own line.
426 // The -json flag prints the environment in JSON format
427 // instead of as a shell script.
429 // The -u flag requires one or more arguments and unsets
430 // the default setting for the named environment variables,
431 // if one has been set with 'go env -w'.
433 // The -w flag requires one or more arguments of the
434 // form NAME=VALUE and changes the default settings
435 // of the named environment variables to the given values.
437 // For more about environment variables, see 'go help environment'.
440 // Update packages to use new APIs
446 // Fix runs the Go fix command on the packages named by the import paths.
448 // For more about fix, see 'go doc cmd/fix'.
449 // For more about specifying packages, see 'go help packages'.
451 // To run fix with specific options, run 'go tool fix'.
453 // See also: go fmt, go vet.
456 // Gofmt (reformat) package sources
460 // go fmt [-n] [-x] [packages]
462 // Fmt runs the command 'gofmt -l -w' on the packages named
463 // by the import paths. It prints the names of the files that are modified.
465 // For more about gofmt, see 'go doc cmd/gofmt'.
466 // For more about specifying packages, see 'go help packages'.
468 // The -n flag prints commands that would be executed.
469 // The -x flag prints commands as they are executed.
471 // The -mod flag's value sets which module download mode
472 // to use: readonly or vendor. See 'go help modules' for more.
474 // To run gofmt with specific options, run gofmt itself.
476 // See also: go fix, go vet.
479 // Generate Go files by processing source
483 // go generate [-run regexp] [-n] [-v] [-x] [build flags] [file.go... | packages]
485 // Generate runs commands described by directives within existing
486 // files. Those commands can run any process but the intent is to
487 // create or update Go source files.
489 // Go generate is never run automatically by go build, go get, go test,
490 // and so on. It must be run explicitly.
492 // Go generate scans the file for directives, which are lines of
495 // //go:generate command argument...
497 // (note: no leading spaces and no space in "//go") where command
498 // is the generator to be run, corresponding to an executable file
499 // that can be run locally. It must either be in the shell path
500 // (gofmt), a fully qualified path (/usr/you/bin/mytool), or a
501 // command alias, described below.
503 // Note that go generate does not parse the file, so lines that look
504 // like directives in comments or multiline strings will be treated
507 // The arguments to the directive are space-separated tokens or
508 // double-quoted strings passed to the generator as individual
509 // arguments when it is run.
511 // Quoted strings use Go syntax and are evaluated before execution; a
512 // quoted string appears as a single argument to the generator.
514 // To convey to humans and machine tools that code is generated,
515 // generated source should have a line that matches the following
516 // regular expression (in Go syntax):
518 // ^// Code generated .* DO NOT EDIT\.$
520 // This line must appear before the first non-comment, non-blank
523 // Go generate sets several variables when it runs the generator:
526 // The execution architecture (arm, amd64, etc.)
528 // The execution operating system (linux, windows, etc.)
530 // The base name of the file.
532 // The line number of the directive in the source file.
534 // The name of the package of the file containing the directive.
538 // Other than variable substitution and quoted-string evaluation, no
539 // special processing such as "globbing" is performed on the command
542 // As a last step before running the command, any invocations of any
543 // environment variables with alphanumeric names, such as $GOFILE or
544 // $HOME, are expanded throughout the command line. The syntax for
545 // variable expansion is $NAME on all operating systems. Due to the
546 // order of evaluation, variables are expanded even inside quoted
547 // strings. If the variable NAME is not set, $NAME expands to the
550 // A directive of the form,
552 // //go:generate -command xxx args...
554 // specifies, for the remainder of this source file only, that the
555 // string xxx represents the command identified by the arguments. This
556 // can be used to create aliases or to handle multiword generators.
559 // //go:generate -command foo go tool foo
561 // specifies that the command "foo" represents the generator
564 // Generate processes packages in the order given on the command line,
565 // one at a time. If the command line lists .go files from a single directory,
566 // they are treated as a single package. Within a package, generate processes the
567 // source files in a package in file name order, one at a time. Within
568 // a source file, generate runs generators in the order they appear
569 // in the file, one at a time. The go generate tool also sets the build
570 // tag "generate" so that files may be examined by go generate but ignored
573 // For packages with invalid code, generate processes only source files with a
574 // valid package clause.
576 // If any generator returns an error exit status, "go generate" skips
577 // all further processing for that package.
579 // The generator is run in the package's source directory.
581 // Go generate accepts one specific flag:
584 // if non-empty, specifies a regular expression to select
585 // directives whose full original source text (excluding
586 // any trailing spaces and final newline) matches the
589 // It also accepts the standard build flags including -v, -n, and -x.
590 // The -v flag prints the names of packages and files as they are
592 // The -n flag prints commands that would be executed.
593 // The -x flag prints commands as they are executed.
595 // For more about build flags, see 'go help build'.
597 // For more about specifying packages, see 'go help packages'.
600 // Add dependencies to current module and install them
604 // go get [-d] [-t] [-u] [-v] [build flags] [packages]
606 // Get resolves its command-line arguments to packages at specific module versions,
607 // updates go.mod to require those versions, downloads source code into the
608 // module cache, then builds and installs the named packages.
610 // To add a dependency for a package or upgrade it to its latest version:
612 // go get example.com/pkg
614 // To upgrade or downgrade a package to a specific version:
616 // go get example.com/pkg@v1.2.3
618 // To remove a dependency on a module and downgrade modules that require it:
620 // go get example.com/mod@none
622 // See https://golang.org/ref/mod#go-get for details.
624 // The 'go install' command may be used to build and install packages. When a
625 // version is specified, 'go install' runs in module-aware mode and ignores
626 // the go.mod file in the current directory. For example:
628 // go install example.com/pkg@v1.2.3
629 // go install example.com/pkg@latest
631 // See 'go help install' or https://golang.org/ref/mod#go-install for details.
633 // In addition to build flags (listed in 'go help build') 'go get' accepts the
636 // The -t flag instructs get to consider modules needed to build tests of
637 // packages specified on the command line.
639 // The -u flag instructs get to update modules providing dependencies
640 // of packages named on the command line to use newer minor or patch
641 // releases when available.
643 // The -u=patch flag (not -u patch) also instructs get to update dependencies,
644 // but changes the default to select patch releases.
646 // When the -t and -u flags are used together, get will update
647 // test dependencies as well.
649 // The -d flag instructs get not to build or install packages. get will only
650 // update go.mod and download source code needed to build packages.
652 // Building and installing packages with get is deprecated. In a future release,
653 // the -d flag will be enabled by default, and 'go get' will be only be used to
654 // adjust dependencies of the current module. To install a package using
655 // dependencies from the current module, use 'go install'. To install a package
656 // ignoring the current module, use 'go install' with an @version suffix like
657 // "@latest" after each argument.
659 // For more about modules, see https://golang.org/ref/mod.
661 // For more about specifying packages, see 'go help packages'.
663 // This text describes the behavior of get using modules to manage source
664 // code and dependencies. If instead the go command is running in GOPATH
665 // mode, the details of get's flags and effects change, as does 'go help get'.
666 // See 'go help gopath-get'.
668 // See also: go build, go install, go clean, go mod.
671 // Compile and install packages and dependencies
675 // go install [build flags] [packages]
677 // Install compiles and installs the packages named by the import paths.
679 // Executables are installed in the directory named by the GOBIN environment
680 // variable, which defaults to $GOPATH/bin or $HOME/go/bin if the GOPATH
681 // environment variable is not set. Executables in $GOROOT
682 // are installed in $GOROOT/bin or $GOTOOLDIR instead of $GOBIN.
684 // If the arguments have version suffixes (like @latest or @v1.0.0), "go install"
685 // builds packages in module-aware mode, ignoring the go.mod file in the current
686 // directory or any parent directory, if there is one. This is useful for
687 // installing executables without affecting the dependencies of the main module.
688 // To eliminate ambiguity about which module versions are used in the build, the
689 // arguments must satisfy the following constraints:
691 // - Arguments must be package paths or package patterns (with "..." wildcards).
692 // They must not be standard packages (like fmt), meta-patterns (std, cmd,
693 // all), or relative or absolute file paths.
695 // - All arguments must have the same version suffix. Different queries are not
696 // allowed, even if they refer to the same version.
698 // - All arguments must refer to packages in the same module at the same version.
700 // - No module is considered the "main" module. If the module containing
701 // packages named on the command line has a go.mod file, it must not contain
702 // directives (replace and exclude) that would cause it to be interpreted
703 // differently than if it were the main module. The module must not require
704 // a higher version of itself.
706 // - Package path arguments must refer to main packages. Pattern arguments
707 // will only match main packages.
709 // If the arguments don't have version suffixes, "go install" may run in
710 // module-aware mode or GOPATH mode, depending on the GO111MODULE environment
711 // variable and the presence of a go.mod file. See 'go help modules' for details.
712 // If module-aware mode is enabled, "go install" runs in the context of the main
715 // When module-aware mode is disabled, other packages are installed in the
716 // directory $GOPATH/pkg/$GOOS_$GOARCH. When module-aware mode is enabled,
717 // other packages are built and cached but not installed.
719 // The -i flag installs the dependencies of the named packages as well.
720 // The -i flag is deprecated. Compiled packages are cached automatically.
722 // For more about the build flags, see 'go help build'.
723 // For more about specifying packages, see 'go help packages'.
725 // See also: go build, go get, go clean.
728 // List packages or modules
732 // go list [-f format] [-json] [-m] [list flags] [build flags] [packages]
734 // List lists the named packages, one per line.
735 // The most commonly-used flags are -f and -json, which control the form
736 // of the output printed for each package. Other list flags, documented below,
737 // control more specific details.
739 // The default output shows the package import path:
743 // github.com/gorilla/mux
744 // golang.org/x/net/html
746 // The -f flag specifies an alternate format for the list, using the
747 // syntax of package template. The default output is equivalent
748 // to -f '{{.ImportPath}}'. The struct being passed to the template is:
750 // type Package struct {
751 // Dir string // directory containing package sources
752 // ImportPath string // import path of package in dir
753 // ImportComment string // path in import comment on package statement
754 // Name string // package name
755 // Doc string // package documentation string
756 // Target string // install path
757 // Shlib string // the shared library that contains this package (only set when -linkshared)
758 // Goroot bool // is this package in the Go root?
759 // Standard bool // is this package part of the standard Go library?
760 // Stale bool // would 'go install' do anything for this package?
761 // StaleReason string // explanation for Stale==true
762 // Root string // Go root or Go path dir containing this package
763 // ConflictDir string // this directory shadows Dir in $GOPATH
764 // BinaryOnly bool // binary-only package (no longer supported)
765 // ForTest string // package is only for use in named test
766 // Export string // file containing export data (when using -export)
767 // BuildID string // build ID of the compiled package (when using -export)
768 // Module *Module // info about package's containing module, if any (can be nil)
769 // Match []string // command-line patterns matching this package
770 // DepOnly bool // package is only a dependency, not explicitly listed
773 // GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles)
774 // CgoFiles []string // .go source files that import "C"
775 // CompiledGoFiles []string // .go files presented to compiler (when using -compiled)
776 // IgnoredGoFiles []string // .go source files ignored due to build constraints
777 // IgnoredOtherFiles []string // non-.go source files ignored due to build constraints
778 // CFiles []string // .c source files
779 // CXXFiles []string // .cc, .cxx and .cpp source files
780 // MFiles []string // .m source files
781 // HFiles []string // .h, .hh, .hpp and .hxx source files
782 // FFiles []string // .f, .F, .for and .f90 Fortran source files
783 // SFiles []string // .s source files
784 // SwigFiles []string // .swig files
785 // SwigCXXFiles []string // .swigcxx files
786 // SysoFiles []string // .syso object files to add to archive
787 // TestGoFiles []string // _test.go files in package
788 // XTestGoFiles []string // _test.go files outside package
791 // EmbedPatterns []string // //go:embed patterns
792 // EmbedFiles []string // files matched by EmbedPatterns
793 // TestEmbedPatterns []string // //go:embed patterns in TestGoFiles
794 // TestEmbedFiles []string // files matched by TestEmbedPatterns
795 // XTestEmbedPatterns []string // //go:embed patterns in XTestGoFiles
796 // XTestEmbedFiles []string // files matched by XTestEmbedPatterns
799 // CgoCFLAGS []string // cgo: flags for C compiler
800 // CgoCPPFLAGS []string // cgo: flags for C preprocessor
801 // CgoCXXFLAGS []string // cgo: flags for C++ compiler
802 // CgoFFLAGS []string // cgo: flags for Fortran compiler
803 // CgoLDFLAGS []string // cgo: flags for linker
804 // CgoPkgConfig []string // cgo: pkg-config names
806 // // Dependency information
807 // Imports []string // import paths used by this package
808 // ImportMap map[string]string // map from source import to ImportPath (identity entries omitted)
809 // Deps []string // all (recursively) imported dependencies
810 // TestImports []string // imports from TestGoFiles
811 // XTestImports []string // imports from XTestGoFiles
813 // // Error information
814 // Incomplete bool // this package or a dependency has an error
815 // Error *PackageError // error loading package
816 // DepsErrors []*PackageError // errors loading dependencies
819 // Packages stored in vendor directories report an ImportPath that includes the
820 // path to the vendor directory (for example, "d/vendor/p" instead of "p"),
821 // so that the ImportPath uniquely identifies a given copy of a package.
822 // The Imports, Deps, TestImports, and XTestImports lists also contain these
823 // expanded import paths. See golang.org/s/go15vendor for more about vendoring.
825 // The error information, if any, is
827 // type PackageError struct {
828 // ImportStack []string // shortest path from package named on command line to this one
829 // Pos string // position of error (if present, file:line:col)
830 // Err string // the error itself
833 // The module information is a Module struct, defined in the discussion
836 // The template function "join" calls strings.Join.
838 // The template function "context" returns the build context, defined as:
840 // type Context struct {
841 // GOARCH string // target architecture
842 // GOOS string // target operating system
843 // GOROOT string // Go root
844 // GOPATH string // Go path
845 // CgoEnabled bool // whether cgo can be used
846 // UseAllFiles bool // use files regardless of +build lines, file names
847 // Compiler string // compiler to assume when computing target paths
848 // BuildTags []string // build constraints to match in +build lines
849 // ToolTags []string // toolchain-specific build constraints
850 // ReleaseTags []string // releases the current release is compatible with
851 // InstallSuffix string // suffix to use in the name of the install dir
854 // For more information about the meaning of these fields see the documentation
855 // for the go/build package's Context type.
857 // The -json flag causes the package data to be printed in JSON format
858 // instead of using the template format.
860 // The -compiled flag causes list to set CompiledGoFiles to the Go source
861 // files presented to the compiler. Typically this means that it repeats
862 // the files listed in GoFiles and then also adds the Go code generated
863 // by processing CgoFiles and SwigFiles. The Imports list contains the
864 // union of all imports from both GoFiles and CompiledGoFiles.
866 // The -deps flag causes list to iterate over not just the named packages
867 // but also all their dependencies. It visits them in a depth-first post-order
868 // traversal, so that a package is listed only after all its dependencies.
869 // Packages not explicitly listed on the command line will have the DepOnly
870 // field set to true.
872 // The -e flag changes the handling of erroneous packages, those that
873 // cannot be found or are malformed. By default, the list command
874 // prints an error to standard error for each erroneous package and
875 // omits the packages from consideration during the usual printing.
876 // With the -e flag, the list command never prints errors to standard
877 // error and instead processes the erroneous packages with the usual
878 // printing. Erroneous packages will have a non-empty ImportPath and
879 // a non-nil Error field; other information may or may not be missing
882 // The -export flag causes list to set the Export field to the name of a
883 // file containing up-to-date export information for the given package.
885 // The -find flag causes list to identify the named packages but not
886 // resolve their dependencies: the Imports and Deps lists will be empty.
888 // The -test flag causes list to report not only the named packages
889 // but also their test binaries (for packages with tests), to convey to
890 // source code analysis tools exactly how test binaries are constructed.
891 // The reported import path for a test binary is the import path of
892 // the package followed by a ".test" suffix, as in "math/rand.test".
893 // When building a test, it is sometimes necessary to rebuild certain
894 // dependencies specially for that test (most commonly the tested
895 // package itself). The reported import path of a package recompiled
896 // for a particular test binary is followed by a space and the name of
897 // the test binary in brackets, as in "math/rand [math/rand.test]"
898 // or "regexp [sort.test]". The ForTest field is also set to the name
899 // of the package being tested ("math/rand" or "sort" in the previous
902 // The Dir, Target, Shlib, Root, ConflictDir, and Export file paths
903 // are all absolute paths.
905 // By default, the lists GoFiles, CgoFiles, and so on hold names of files in Dir
906 // (that is, paths relative to Dir, not absolute paths).
907 // The generated files added when using the -compiled and -test flags
908 // are absolute paths referring to cached copies of generated Go source files.
909 // Although they are Go source files, the paths may not end in ".go".
911 // The -m flag causes list to list modules instead of packages.
913 // When listing modules, the -f flag still specifies a format template
914 // applied to a Go struct, but now a Module struct:
916 // type Module struct {
917 // Path string // module path
918 // Version string // module version
919 // Versions []string // available module versions (with -versions)
920 // Replace *Module // replaced by this module
921 // Time *time.Time // time version was created
922 // Update *Module // available update, if any (with -u)
923 // Main bool // is this the main module?
924 // Indirect bool // is this module only an indirect dependency of main module?
925 // Dir string // directory holding files for this module, if any
926 // GoMod string // path to go.mod file used when loading this module, if any
927 // GoVersion string // go version used in module
928 // Retracted string // retraction information, if any (with -retracted or -u)
929 // Error *ModuleError // error loading module
932 // type ModuleError struct {
933 // Err string // the error itself
936 // The file GoMod refers to may be outside the module directory if the
937 // module is in the module cache or if the -modfile flag is used.
939 // The default output is to print the module path and then
940 // information about the version and replacement if any.
941 // For example, 'go list -m all' might print:
944 // golang.org/x/text v0.3.0 => /tmp/text
947 // The Module struct has a String method that formats this
948 // line of output, so that the default format is equivalent
949 // to -f '{{.String}}'.
951 // Note that when a module has been replaced, its Replace field
952 // describes the replacement module, and its Dir field is set to
953 // the replacement's source code, if present. (That is, if Replace
954 // is non-nil, then Dir is set to Replace.Dir, with no access to
955 // the replaced source code.)
957 // The -u flag adds information about available upgrades.
958 // When the latest version of a given module is newer than
959 // the current one, list -u sets the Module's Update field
960 // to information about the newer module. list -u will also set
961 // the module's Retracted field if the current version is retracted.
962 // The Module's String method indicates an available upgrade by
963 // formatting the newer version in brackets after the current version.
964 // If a version is retracted, the string "(retracted)" will follow it.
965 // For example, 'go list -m -u all' might print:
968 // golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text
969 // rsc.io/pdf v0.1.1 (retracted) [v0.1.2]
971 // (For tools, 'go list -m -u -json all' may be more convenient to parse.)
973 // The -versions flag causes list to set the Module's Versions field
974 // to a list of all known versions of that module, ordered according
975 // to semantic versioning, earliest to latest. The flag also changes
976 // the default output format to display the module path followed by the
977 // space-separated version list.
979 // The -retracted flag causes list to report information about retracted
980 // module versions. When -retracted is used with -f or -json, the Retracted
981 // field will be set to a string explaining why the version was retracted.
982 // The string is taken from comments on the retract directive in the
983 // module's go.mod file. When -retracted is used with -versions, retracted
984 // versions are listed together with unretracted versions. The -retracted
985 // flag may be used with or without -m.
987 // The arguments to list -m are interpreted as a list of modules, not packages.
988 // The main module is the module containing the current directory.
989 // The active modules are the main module and its dependencies.
990 // With no arguments, list -m shows the main module.
991 // With arguments, list -m shows the modules specified by the arguments.
992 // Any of the active modules can be specified by its module path.
993 // The special pattern "all" specifies all the active modules, first the main
994 // module and then dependencies sorted by module path.
995 // A pattern containing "..." specifies the active modules whose
996 // module paths match the pattern.
997 // A query of the form path@version specifies the result of that query,
998 // which is not limited to active modules.
999 // See 'go help modules' for more about module queries.
1001 // The template function "module" takes a single string argument
1002 // that must be a module path or query and returns the specified
1003 // module as a Module struct. If an error occurs, the result will
1004 // be a Module struct with a non-nil Error field.
1006 // For more about build flags, see 'go help build'.
1008 // For more about specifying packages, see 'go help packages'.
1010 // For more about modules, see https://golang.org/ref/mod.
1013 // Module maintenance
1015 // Go mod provides access to operations on modules.
1017 // Note that support for modules is built into all the go commands,
1018 // not just 'go mod'. For example, day-to-day adding, removing, upgrading,
1019 // and downgrading of dependencies should be done using 'go get'.
1020 // See 'go help modules' for an overview of module functionality.
1024 // go mod <command> [arguments]
1026 // The commands are:
1028 // download download modules to local cache
1029 // edit edit go.mod from tools or scripts
1030 // graph print module requirement graph
1031 // init initialize new module in current directory
1032 // tidy add missing and remove unused modules
1033 // vendor make vendored copy of dependencies
1034 // verify verify dependencies have expected content
1035 // why explain why packages or modules are needed
1037 // Use "go help mod <command>" for more information about a command.
1039 // Download modules to local cache
1043 // go mod download [-x] [-json] [modules]
1045 // Download downloads the named modules, which can be module patterns selecting
1046 // dependencies of the main module or module queries of the form path@version.
1047 // With no arguments, download applies to all dependencies of the main module
1048 // (equivalent to 'go mod download all').
1050 // The go command will automatically download modules as needed during ordinary
1051 // execution. The "go mod download" command is useful mainly for pre-filling
1052 // the local cache or to compute the answers for a Go module proxy.
1054 // By default, download writes nothing to standard output. It may print progress
1055 // messages and errors to standard error.
1057 // The -json flag causes download to print a sequence of JSON objects
1058 // to standard output, describing each downloaded module (or failure),
1059 // corresponding to this Go struct:
1061 // type Module struct {
1062 // Path string // module path
1063 // Version string // module version
1064 // Error string // error loading module
1065 // Info string // absolute path to cached .info file
1066 // GoMod string // absolute path to cached .mod file
1067 // Zip string // absolute path to cached .zip file
1068 // Dir string // absolute path to cached source root directory
1069 // Sum string // checksum for path, version (as in go.sum)
1070 // GoModSum string // checksum for go.mod (as in go.sum)
1073 // The -x flag causes download to print the commands download executes.
1075 // See https://golang.org/ref/mod#go-mod-download for more about 'go mod download'.
1077 // See https://golang.org/ref/mod#version-queries for more about version queries.
1080 // Edit go.mod from tools or scripts
1084 // go mod edit [editing flags] [go.mod]
1086 // Edit provides a command-line interface for editing go.mod,
1087 // for use primarily by tools or scripts. It reads only go.mod;
1088 // it does not look up information about the modules involved.
1089 // By default, edit reads and writes the go.mod file of the main module,
1090 // but a different target file can be specified after the editing flags.
1092 // The editing flags specify a sequence of editing operations.
1094 // The -fmt flag reformats the go.mod file without making other changes.
1095 // This reformatting is also implied by any other modifications that use or
1096 // rewrite the go.mod file. The only time this flag is needed is if no other
1097 // flags are specified, as in 'go mod edit -fmt'.
1099 // The -module flag changes the module's path (the go.mod file's module line).
1101 // The -require=path@version and -droprequire=path flags
1102 // add and drop a requirement on the given module path and version.
1103 // Note that -require overrides any existing requirements on path.
1104 // These flags are mainly for tools that understand the module graph.
1105 // Users should prefer 'go get path@version' or 'go get path@none',
1106 // which make other go.mod adjustments as needed to satisfy
1107 // constraints imposed by other modules.
1109 // The -exclude=path@version and -dropexclude=path@version flags
1110 // add and drop an exclusion for the given module path and version.
1111 // Note that -exclude=path@version is a no-op if that exclusion already exists.
1113 // The -replace=old[@v]=new[@v] flag adds a replacement of the given
1114 // module path and version pair. If the @v in old@v is omitted, a
1115 // replacement without a version on the left side is added, which applies
1116 // to all versions of the old module path. If the @v in new@v is omitted,
1117 // the new path should be a local module root directory, not a module
1118 // path. Note that -replace overrides any redundant replacements for old[@v],
1119 // so omitting @v will drop existing replacements for specific versions.
1121 // The -dropreplace=old[@v] flag drops a replacement of the given
1122 // module path and version pair. If the @v is omitted, a replacement without
1123 // a version on the left side is dropped.
1125 // The -retract=version and -dropretract=version flags add and drop a
1126 // retraction on the given version. The version may be a single version
1127 // like "v1.2.3" or a closed interval like "[v1.1.0,v1.1.9]". Note that
1128 // -retract=version is a no-op if that retraction already exists.
1130 // The -require, -droprequire, -exclude, -dropexclude, -replace,
1131 // -dropreplace, -retract, and -dropretract editing flags may be repeated,
1132 // and the changes are applied in the order given.
1134 // The -go=version flag sets the expected Go language version.
1136 // The -print flag prints the final go.mod in its text format instead of
1137 // writing it back to go.mod.
1139 // The -json flag prints the final go.mod file in JSON format instead of
1140 // writing it back to go.mod. The JSON output corresponds to these Go types:
1142 // type Module struct {
1147 // type GoMod struct {
1150 // Require []Require
1152 // Replace []Replace
1153 // Retract []Retract
1156 // type ModPath struct {
1158 // Deprecated string
1161 // type Require struct {
1167 // type Replace struct {
1172 // type Retract struct {
1178 // Retract entries representing a single version (not an interval) will have
1179 // the "Low" and "High" fields set to the same value.
1181 // Note that this only describes the go.mod file itself, not other modules
1182 // referred to indirectly. For the full set of modules available to a build,
1183 // use 'go list -m -json all'.
1185 // See https://golang.org/ref/mod#go-mod-edit for more about 'go mod edit'.
1188 // Print module requirement graph
1192 // go mod graph [-go=version]
1194 // Graph prints the module requirement graph (with replacements applied)
1195 // in text form. Each line in the output has two space-separated fields: a module
1196 // and one of its requirements. Each module is identified as a string of the form
1197 // path@version, except for the main module, which has no @version suffix.
1199 // The -go flag causes graph to report the module graph as loaded by by the
1200 // given Go version, instead of the version indicated by the 'go' directive
1201 // in the go.mod file.
1203 // See https://golang.org/ref/mod#go-mod-graph for more about 'go mod graph'.
1206 // Initialize new module in current directory
1210 // go mod init [module]
1212 // Init initializes and writes a new go.mod file in the current directory, in
1213 // effect creating a new module rooted at the current directory. The go.mod file
1214 // must not already exist.
1216 // Init accepts one optional argument, the module path for the new module. If the
1217 // module path argument is omitted, init will attempt to infer the module path
1218 // using import comments in .go files, vendoring tool configuration files (like
1219 // Gopkg.lock), and the current directory (if in GOPATH).
1221 // If a configuration file for a vendoring tool is present, init will attempt to
1222 // import module requirements from it.
1224 // See https://golang.org/ref/mod#go-mod-init for more about 'go mod init'.
1227 // Add missing and remove unused modules
1231 // go mod tidy [-e] [-v] [-go=version] [-compat=version]
1233 // Tidy makes sure go.mod matches the source code in the module.
1234 // It adds any missing modules necessary to build the current module's
1235 // packages and dependencies, and it removes unused modules that
1236 // don't provide any relevant packages. It also adds any missing entries
1237 // to go.sum and removes any unnecessary ones.
1239 // The -v flag causes tidy to print information about removed modules
1240 // to standard error.
1242 // The -e flag causes tidy to attempt to proceed despite errors
1243 // encountered while loading packages.
1245 // The -go flag causes tidy to update the 'go' directive in the go.mod
1246 // file to the given version, which may change which module dependencies
1247 // are retained as explicit requirements in the go.mod file.
1248 // (Go versions 1.17 and higher retain more requirements in order to
1249 // support lazy module loading.)
1251 // The -compat flag preserves any additional checksums needed for the
1252 // 'go' command from the indicated major Go release to successfully load
1253 // the module graph, and causes tidy to error out if that version of the
1254 // 'go' command would load any imported package from a different module
1255 // version. By default, tidy acts as if the -compat flag were set to the
1256 // version prior to the one indicated by the 'go' directive in the go.mod
1259 // See https://golang.org/ref/mod#go-mod-tidy for more about 'go mod tidy'.
1262 // Make vendored copy of dependencies
1266 // go mod vendor [-e] [-v]
1268 // Vendor resets the main module's vendor directory to include all packages
1269 // needed to build and test all the main module's packages.
1270 // It does not include test code for vendored packages.
1272 // The -v flag causes vendor to print the names of vendored
1273 // modules and packages to standard error.
1275 // The -e flag causes vendor to attempt to proceed despite errors
1276 // encountered while loading packages.
1278 // See https://golang.org/ref/mod#go-mod-vendor for more about 'go mod vendor'.
1281 // Verify dependencies have expected content
1287 // Verify checks that the dependencies of the current module,
1288 // which are stored in a local downloaded source cache, have not been
1289 // modified since being downloaded. If all the modules are unmodified,
1290 // verify prints "all modules verified." Otherwise it reports which
1291 // modules have been changed and causes 'go mod' to exit with a
1294 // See https://golang.org/ref/mod#go-mod-verify for more about 'go mod verify'.
1297 // Explain why packages or modules are needed
1301 // go mod why [-m] [-vendor] packages...
1303 // Why shows a shortest path in the import graph from the main module to
1304 // each of the listed packages. If the -m flag is given, why treats the
1305 // arguments as a list of modules and finds a path to any package in each
1308 // By default, why queries the graph of packages matched by "go list all",
1309 // which includes tests for reachable packages. The -vendor flag causes why
1310 // to exclude tests of dependencies.
1312 // The output is a sequence of stanzas, one for each package or module
1313 // name on the command line, separated by blank lines. Each stanza begins
1314 // with a comment line "# package" or "# module" giving the target
1315 // package or module. Subsequent lines give a path through the import
1316 // graph, one package per line. If the package or module is not
1317 // referenced from the main module, the stanza will display a single
1318 // parenthesized note indicating that fact.
1322 // $ go mod why golang.org/x/text/language golang.org/x/text/encoding
1323 // # golang.org/x/text/language
1326 // golang.org/x/text/language
1328 // # golang.org/x/text/encoding
1329 // (main module does not need package golang.org/x/text/encoding)
1332 // See https://golang.org/ref/mod#go-mod-why for more about 'go mod why'.
1335 // Compile and run Go program
1339 // go run [build flags] [-exec xprog] package [arguments...]
1341 // Run compiles and runs the named main Go package.
1342 // Typically the package is specified as a list of .go source files from a single
1343 // directory, but it may also be an import path, file system path, or pattern
1344 // matching a single known package, as in 'go run .' or 'go run my/cmd'.
1346 // If the package argument has a version suffix (like @latest or @v1.0.0),
1347 // "go run" builds the program in module-aware mode, ignoring the go.mod file in
1348 // the current directory or any parent directory, if there is one. This is useful
1349 // for running programs without affecting the dependencies of the main module.
1351 // If the package argument doesn't have a version suffix, "go run" may run in
1352 // module-aware mode or GOPATH mode, depending on the GO111MODULE environment
1353 // variable and the presence of a go.mod file. See 'go help modules' for details.
1354 // If module-aware mode is enabled, "go run" runs in the context of the main
1357 // By default, 'go run' runs the compiled binary directly: 'a.out arguments...'.
1358 // If the -exec flag is given, 'go run' invokes the binary using xprog:
1359 // 'xprog a.out arguments...'.
1360 // If the -exec flag is not given, GOOS or GOARCH is different from the system
1361 // default, and a program named go_$GOOS_$GOARCH_exec can be found
1362 // on the current search path, 'go run' invokes the binary using that program,
1363 // for example 'go_js_wasm_exec a.out arguments...'. This allows execution of
1364 // cross-compiled programs when a simulator or other execution method is
1367 // The exit status of Run is not the exit status of the compiled binary.
1369 // For more about build flags, see 'go help build'.
1370 // For more about specifying packages, see 'go help packages'.
1372 // See also: go build.
1379 // go test [build/test flags] [packages] [build/test flags & test binary flags]
1381 // 'Go test' automates testing the packages named by the import paths.
1382 // It prints a summary of the test results in the format:
1384 // ok archive/tar 0.011s
1385 // FAIL archive/zip 0.022s
1386 // ok compress/gzip 0.033s
1389 // followed by detailed output for each failed package.
1391 // 'Go test' recompiles each package along with any files with names matching
1392 // the file pattern "*_test.go".
1393 // These additional files can contain test functions, benchmark functions, fuzz
1394 // targets and example functions. See 'go help testfunc' for more.
1395 // Each listed package causes the execution of a separate test binary.
1396 // Files whose names begin with "_" (including "_test.go") or "." are ignored.
1398 // Test files that declare a package with the suffix "_test" will be compiled as a
1399 // separate package, and then linked and run with the main test binary.
1401 // The go tool will ignore a directory named "testdata", making it available
1402 // to hold ancillary data needed by the tests.
1404 // As part of building a test binary, go test runs go vet on the package
1405 // and its test source files to identify significant problems. If go vet
1406 // finds any problems, go test reports those and does not run the test
1407 // binary. Only a high-confidence subset of the default go vet checks are
1408 // used. That subset is: 'atomic', 'bool', 'buildtags', 'errorsas',
1409 // 'ifaceassert', 'nilfunc', 'printf', and 'stringintconv'. You can see
1410 // the documentation for these and other vet tests via "go doc cmd/vet".
1411 // To disable the running of go vet, use the -vet=off flag.
1413 // All test output and summary lines are printed to the go command's
1414 // standard output, even if the test printed them to its own standard
1415 // error. (The go command's standard error is reserved for printing
1416 // errors building the tests.)
1418 // Go test runs in two different modes:
1420 // The first, called local directory mode, occurs when go test is
1421 // invoked with no package arguments (for example, 'go test' or 'go
1422 // test -v'). In this mode, go test compiles the package sources and
1423 // tests found in the current directory and then runs the resulting
1424 // test binary. In this mode, caching (discussed below) is disabled.
1425 // After the package test finishes, go test prints a summary line
1426 // showing the test status ('ok' or 'FAIL'), package name, and elapsed
1429 // The second, called package list mode, occurs when go test is invoked
1430 // with explicit package arguments (for example 'go test math', 'go
1431 // test ./...', and even 'go test .'). In this mode, go test compiles
1432 // and tests each of the packages listed on the command line. If a
1433 // package test passes, go test prints only the final 'ok' summary
1434 // line. If a package test fails, go test prints the full test output.
1435 // If invoked with the -bench or -v flag, go test prints the full
1436 // output even for passing package tests, in order to display the
1437 // requested benchmark results or verbose logging. After the package
1438 // tests for all of the listed packages finish, and their output is
1439 // printed, go test prints a final 'FAIL' status if any package test
1442 // In package list mode only, go test caches successful package test
1443 // results to avoid unnecessary repeated running of tests. When the
1444 // result of a test can be recovered from the cache, go test will
1445 // redisplay the previous output instead of running the test binary
1446 // again. When this happens, go test prints '(cached)' in place of the
1447 // elapsed time in the summary line.
1449 // The rule for a match in the cache is that the run involves the same
1450 // test binary and the flags on the command line come entirely from a
1451 // restricted set of 'cacheable' test flags, defined as -benchtime, -cpu,
1452 // -list, -parallel, -run, -short, and -v. If a run of go test has any test
1453 // or non-test flags outside this set, the result is not cached. To
1454 // disable test caching, use any test flag or argument other than the
1455 // cacheable flags. The idiomatic way to disable test caching explicitly
1456 // is to use -count=1. Tests that open files within the package's source
1457 // root (usually $GOPATH) or that consult environment variables only
1458 // match future runs in which the files and environment variables are unchanged.
1459 // A cached test result is treated as executing in no time at all,
1460 // so a successful package test result will be cached and reused
1461 // regardless of -timeout setting.
1463 // Run 'go help fuzz' for details around how the go command handles fuzz targets.
1465 // In addition to the build flags, the flags handled by 'go test' itself are:
1468 // Pass the remainder of the command line (everything after -args)
1469 // to the test binary, uninterpreted and unchanged.
1470 // Because this flag consumes the remainder of the command line,
1471 // the package list (if present) must appear before this flag.
1474 // Compile the test binary to pkg.test but do not run it
1475 // (where pkg is the last element of the package's import path).
1476 // The file name can be changed with the -o flag.
1479 // Run the test binary using xprog. The behavior is the same as
1480 // in 'go run'. See 'go help run' for details.
1483 // Install packages that are dependencies of the test.
1484 // Do not run the test.
1485 // The -i flag is deprecated. Compiled packages are cached automatically.
1488 // Convert test output to JSON suitable for automated processing.
1489 // See 'go doc test2json' for the encoding details.
1492 // Compile the test binary to the named file.
1493 // The test still runs (unless -c or -i is specified).
1495 // The test binary also accepts flags that control execution of the test; these
1496 // flags are also accessible by 'go test'. See 'go help testflag' for details.
1498 // For more about build flags, see 'go help build'.
1499 // For more about specifying packages, see 'go help packages'.
1501 // See also: go build, go vet.
1504 // Run specified go tool
1508 // go tool [-n] command [args...]
1510 // Tool runs the go tool command identified by the arguments.
1511 // With no arguments it prints the list of known tools.
1513 // The -n flag causes tool to print the command that would be
1514 // executed but not execute it.
1516 // For more about each tool command, see 'go doc cmd/<command>'.
1523 // go version [-m] [-v] [file ...]
1525 // Version prints the build information for Go executables.
1527 // Go version reports the Go version used to build each of the named
1528 // executable files.
1530 // If no files are named on the command line, go version prints its own
1531 // version information.
1533 // If a directory is named, go version walks that directory, recursively,
1534 // looking for recognized Go binaries and reporting their versions.
1535 // By default, go version does not report unrecognized files found
1536 // during a directory scan. The -v flag causes it to report unrecognized files.
1538 // The -m flag causes go version to print each executable's embedded
1539 // module version information, when available. In the output, the module
1540 // information consists of multiple lines following the version line, each
1541 // indented by a leading tab character.
1543 // See also: go doc runtime/debug.BuildInfo.
1546 // Report likely mistakes in packages
1550 // go vet [-n] [-x] [-vettool prog] [build flags] [vet flags] [packages]
1552 // Vet runs the Go vet command on the packages named by the import paths.
1554 // For more about vet and its flags, see 'go doc cmd/vet'.
1555 // For more about specifying packages, see 'go help packages'.
1556 // For a list of checkers and their flags, see 'go tool vet help'.
1557 // For details of a specific checker such as 'printf', see 'go tool vet help printf'.
1559 // The -n flag prints commands that would be executed.
1560 // The -x flag prints commands as they are executed.
1562 // The -vettool=prog flag selects a different analysis tool with alternative
1563 // or additional checks.
1564 // For example, the 'shadow' analyzer can be built and run using these commands:
1566 // go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow
1567 // go vet -vettool=$(which shadow)
1569 // The build flags supported by go vet are those that control package resolution
1570 // and execution, such as -n, -x, -v, -tags, and -toolexec.
1571 // For more about these flags, see 'go help build'.
1573 // See also: go fmt, go fix.
1576 // Build constraints
1578 // A build constraint, also known as a build tag, is a line comment that begins
1582 // that lists the conditions under which a file should be included in the package.
1583 // Constraints may appear in any kind of source file (not just Go), but
1584 // they must appear near the top of the file, preceded
1585 // only by blank lines and other line comments. These rules mean that in Go
1586 // files a build constraint must appear before the package clause.
1588 // To distinguish build constraints from package documentation,
1589 // a build constraint should be followed by a blank line.
1591 // A build constraint is evaluated as an expression containing options
1592 // combined by ||, &&, and ! operators and parentheses. Operators have
1593 // the same meaning as in Go.
1595 // For example, the following build constraint constrains a file to
1596 // build when the "linux" and "386" constraints are satisfied, or when
1597 // "darwin" is satisfied and "cgo" is not:
1599 // //go:build (linux && 386) || (darwin && !cgo)
1601 // It is an error for a file to have more than one //go:build line.
1603 // During a particular build, the following words are satisfied:
1605 // - the target operating system, as spelled by runtime.GOOS, set with the
1606 // GOOS environment variable.
1607 // - the target architecture, as spelled by runtime.GOARCH, set with the
1608 // GOARCH environment variable.
1609 // - the compiler being used, either "gc" or "gccgo"
1610 // - "cgo", if the cgo command is supported (see CGO_ENABLED in
1611 // 'go help environment').
1612 // - a term for each Go major release, through the current version:
1613 // "go1.1" from Go version 1.1 onward, "go1.12" from Go 1.12, and so on.
1614 // - any additional tags given by the -tags flag (see 'go help build').
1616 // There are no separate build tags for beta or minor releases.
1618 // If a file's name, after stripping the extension and a possible _test suffix,
1619 // matches any of the following patterns:
1623 // (example: source_windows_amd64.go) where GOOS and GOARCH represent
1624 // any known operating system and architecture values respectively, then
1625 // the file is considered to have an implicit build constraint requiring
1626 // those terms (in addition to any explicit constraints in the file).
1628 // Using GOOS=android matches build tags and files as for GOOS=linux
1629 // in addition to android tags and files.
1631 // Using GOOS=illumos matches build tags and files as for GOOS=solaris
1632 // in addition to illumos tags and files.
1634 // Using GOOS=ios matches build tags and files as for GOOS=darwin
1635 // in addition to ios tags and files.
1637 // To keep a file from being considered for the build:
1639 // //go:build ignore
1641 // (any other unsatisfied word will work as well, but "ignore" is conventional.)
1643 // To build a file only when using cgo, and only on Linux and OS X:
1645 // //go:build cgo && (linux || darwin)
1647 // Such a file is usually paired with another file implementing the
1648 // default functionality for other systems, which in this case would
1649 // carry the constraint:
1651 // //go:build !(cgo && (linux || darwin))
1653 // Naming a file dns_windows.go will cause it to be included only when
1654 // building the package for Windows; similarly, math_386.s will be included
1655 // only when building the package for 32-bit x86.
1657 // Go versions 1.16 and earlier used a different syntax for build constraints,
1658 // with a "// +build" prefix. The gofmt command will add an equivalent //go:build
1659 // constraint when encountering the older syntax.
1664 // The 'go build' and 'go install' commands take a -buildmode argument which
1665 // indicates which kind of object file is to be built. Currently supported values
1668 // -buildmode=archive
1669 // Build the listed non-main packages into .a files. Packages named
1670 // main are ignored.
1672 // -buildmode=c-archive
1673 // Build the listed main package, plus all packages it imports,
1674 // into a C archive file. The only callable symbols will be those
1675 // functions exported using a cgo //export comment. Requires
1676 // exactly one main package to be listed.
1678 // -buildmode=c-shared
1679 // Build the listed main package, plus all packages it imports,
1680 // into a C shared library. The only callable symbols will
1681 // be those functions exported using a cgo //export comment.
1682 // Requires exactly one main package to be listed.
1684 // -buildmode=default
1685 // Listed main packages are built into executables and listed
1686 // non-main packages are built into .a files (the default
1689 // -buildmode=shared
1690 // Combine all the listed non-main packages into a single shared
1691 // library that will be used when building with the -linkshared
1692 // option. Packages named main are ignored.
1695 // Build the listed main packages and everything they import into
1696 // executables. Packages not named main are ignored.
1699 // Build the listed main packages and everything they import into
1700 // position independent executables (PIE). Packages not named
1701 // main are ignored.
1703 // -buildmode=plugin
1704 // Build the listed main packages, plus all packages that they
1705 // import, into a Go plugin. Packages not named main are ignored.
1707 // On AIX, when linking a C program that uses a Go archive built with
1708 // -buildmode=c-archive, you must pass -Wl,-bnoobjreorder to the C compiler.
1711 // Calling between Go and C
1713 // There are two different ways to call between Go and C/C++ code.
1715 // The first is the cgo tool, which is part of the Go distribution. For
1716 // information on how to use it see the cgo documentation (go doc cmd/cgo).
1718 // The second is the SWIG program, which is a general tool for
1719 // interfacing between languages. For information on SWIG see
1720 // http://swig.org/. When running go build, any file with a .swig
1721 // extension will be passed to SWIG. Any file with a .swigcxx extension
1722 // will be passed to SWIG with the -c++ option.
1724 // When either cgo or SWIG is used, go build will pass any .c, .m, .s, .S
1725 // or .sx files to the C compiler, and any .cc, .cpp, .cxx files to the C++
1726 // compiler. The CC or CXX environment variables may be set to determine
1727 // the C or C++ compiler, respectively, to use.
1730 // Build and test caching
1732 // The go command caches build outputs for reuse in future builds.
1733 // The default location for cache data is a subdirectory named go-build
1734 // in the standard user cache directory for the current operating system.
1735 // Setting the GOCACHE environment variable overrides this default,
1736 // and running 'go env GOCACHE' prints the current cache directory.
1738 // The go command periodically deletes cached data that has not been
1739 // used recently. Running 'go clean -cache' deletes all cached data.
1741 // The build cache correctly accounts for changes to Go source files,
1742 // compilers, compiler options, and so on: cleaning the cache explicitly
1743 // should not be necessary in typical use. However, the build cache
1744 // does not detect changes to C libraries imported with cgo.
1745 // If you have made changes to the C libraries on your system, you
1746 // will need to clean the cache explicitly or else use the -a build flag
1747 // (see 'go help build') to force rebuilding of packages that
1748 // depend on the updated C libraries.
1750 // The go command also caches successful package test results.
1751 // See 'go help test' for details. Running 'go clean -testcache' removes
1752 // all cached test results (but not cached build results).
1754 // The GODEBUG environment variable can enable printing of debugging
1755 // information about the state of the cache:
1757 // GODEBUG=gocacheverify=1 causes the go command to bypass the
1758 // use of any cache entries and instead rebuild everything and check
1759 // that the results match existing cache entries.
1761 // GODEBUG=gocachehash=1 causes the go command to print the inputs
1762 // for all of the content hashes it uses to construct cache lookup keys.
1763 // The output is voluminous but can be useful for debugging the cache.
1765 // GODEBUG=gocachetest=1 causes the go command to print details of its
1766 // decisions about whether to reuse a cached test result.
1769 // Environment variables
1771 // The go command and the tools it invokes consult environment variables
1772 // for configuration. If an environment variable is unset, the go command
1773 // uses a sensible default setting. To see the effective setting of the
1774 // variable <NAME>, run 'go env <NAME>'. To change the default setting,
1775 // run 'go env -w <NAME>=<VALUE>'. Defaults changed using 'go env -w'
1776 // are recorded in a Go environment configuration file stored in the
1777 // per-user configuration directory, as reported by os.UserConfigDir.
1778 // The location of the configuration file can be changed by setting
1779 // the environment variable GOENV, and 'go env GOENV' prints the
1780 // effective location, but 'go env -w' cannot change the default location.
1781 // See 'go help env' for details.
1783 // General-purpose environment variables:
1786 // Controls whether the go command runs in module-aware mode or GOPATH mode.
1787 // May be "off", "on", or "auto".
1788 // See https://golang.org/ref/mod#mod-commands.
1790 // The gccgo command to run for 'go build -compiler=gccgo'.
1792 // The architecture, or processor, for which to compile code.
1793 // Examples are amd64, 386, arm, ppc64.
1795 // The directory where 'go install' will install a command.
1797 // The directory where the go command will store cached
1798 // information for reuse in future builds.
1800 // The directory where the go command will store downloaded modules.
1802 // Enable various debugging facilities. See 'go doc runtime'
1805 // The location of the Go environment configuration file.
1806 // Cannot be set using 'go env -w'.
1808 // A space-separated list of -flag=value settings to apply
1809 // to go commands by default, when the given flag is known by
1810 // the current command. Each entry must be a standalone flag.
1811 // Because the entries are space-separated, flag values must
1812 // not contain spaces. Flags listed on the command line
1813 // are applied after this list and therefore override it.
1815 // Comma-separated list of glob patterns (in the syntax of Go's path.Match)
1816 // of module path prefixes that should always be fetched in an insecure
1817 // manner. Only applies to dependencies that are being fetched directly.
1818 // GOINSECURE does not disable checksum database validation. GOPRIVATE or
1819 // GONOSUMDB may be used to achieve that.
1821 // The operating system for which to compile code.
1822 // Examples are linux, darwin, windows, netbsd.
1824 // For more details see: 'go help gopath'.
1826 // URL of Go module proxy. See https://golang.org/ref/mod#environment-variables
1827 // and https://golang.org/ref/mod#module-proxy for details.
1828 // GOPRIVATE, GONOPROXY, GONOSUMDB
1829 // Comma-separated list of glob patterns (in the syntax of Go's path.Match)
1830 // of module path prefixes that should always be fetched directly
1831 // or that should not be compared against the checksum database.
1832 // See https://golang.org/ref/mod#private-modules.
1834 // The root of the go tree.
1836 // The name of checksum database to use and optionally its public key and
1837 // URL. See https://golang.org/ref/mod#authenticating.
1839 // The directory where the go command will write
1840 // temporary source files, packages, and binaries.
1842 // Lists version control commands that may be used with matching servers.
1843 // See 'go help vcs'.
1845 // Environment variables for use with cgo:
1848 // The command to use to manipulate library archives when
1849 // building with the gccgo compiler.
1850 // The default is 'ar'.
1852 // The command to use to compile C code.
1854 // Whether the cgo command is supported. Either 0 or 1.
1856 // Flags that cgo will pass to the compiler when compiling
1859 // A regular expression specifying additional flags to allow
1860 // to appear in #cgo CFLAGS source code directives.
1861 // Does not apply to the CGO_CFLAGS environment variable.
1862 // CGO_CFLAGS_DISALLOW
1863 // A regular expression specifying flags that must be disallowed
1864 // from appearing in #cgo CFLAGS source code directives.
1865 // Does not apply to the CGO_CFLAGS environment variable.
1866 // CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
1867 // Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
1868 // but for the C preprocessor.
1869 // CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
1870 // Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
1871 // but for the C++ compiler.
1872 // CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
1873 // Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
1874 // but for the Fortran compiler.
1875 // CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
1876 // Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
1877 // but for the linker.
1879 // The command to use to compile C++ code.
1881 // The command to use to compile Fortran code.
1883 // Path to pkg-config tool.
1885 // Architecture-specific environment variables:
1888 // For GOARCH=arm, the ARM architecture for which to compile.
1889 // Valid values are 5, 6, 7.
1891 // For GOARCH=386, how to implement floating point instructions.
1892 // Valid values are sse2 (default), softfloat.
1894 // For GOARCH=mips{,le}, whether to use floating point instructions.
1895 // Valid values are hardfloat (default), softfloat.
1897 // For GOARCH=mips64{,le}, whether to use floating point instructions.
1898 // Valid values are hardfloat (default), softfloat.
1900 // For GOARCH=ppc64{,le}, the target ISA (Instruction Set Architecture).
1901 // Valid values are power8 (default), power9.
1903 // For GOARCH=wasm, comma-separated list of experimental WebAssembly features to use.
1904 // Valid values are satconv, signext.
1906 // Special-purpose environment variables:
1909 // If set, where to find gccgo tools, such as cgo.
1910 // The default is based on how gccgo was configured.
1912 // The root of the installed Go tree, when it is
1913 // installed in a location other than where it is built.
1914 // File names in stack traces are rewritten from GOROOT to
1916 // GO_EXTLINK_ENABLED
1917 // Whether the linker should use external linking mode
1918 // when using -linkmode=auto with code that uses cgo.
1919 // Set to 0 to disable external linking mode, 1 to enable it.
1920 // GIT_ALLOW_PROTOCOL
1921 // Defined by Git. A colon-separated list of schemes that are allowed
1922 // to be used with git fetch/clone. If set, any scheme not explicitly
1923 // mentioned will be considered insecure by 'go get'.
1924 // Because the variable is defined by Git, the default value cannot
1925 // be set using 'go env -w'.
1927 // Additional information available from 'go env' but not read from the environment:
1930 // The executable file name suffix (".exe" on Windows, "" on other systems).
1932 // A space-separated list of arguments supplied to the CC command.
1934 // The architecture (GOARCH) of the Go toolchain binaries.
1936 // The operating system (GOOS) of the Go toolchain binaries.
1938 // The absolute path to the go.mod of the main module.
1939 // If module-aware mode is enabled, but there is no go.mod, GOMOD will be
1940 // os.DevNull ("/dev/null" on Unix-like systems, "NUL" on Windows).
1941 // If module-aware mode is disabled, GOMOD will be the empty string.
1943 // The directory where the go tools (compile, cover, doc, etc...) are installed.
1945 // The version of the installed Go tree, as reported by runtime.Version.
1950 // The go command examines the contents of a restricted set of files
1951 // in each directory. It identifies which files to examine based on
1952 // the extension of the file name. These extensions are:
1958 // If the package uses cgo or SWIG, these will be compiled with the
1959 // OS-native compiler (typically gcc); otherwise they will
1960 // trigger an error.
1961 // .cc, .cpp, .cxx, .hh, .hpp, .hxx
1962 // C++ source files. Only useful with cgo or SWIG, and always
1963 // compiled with the OS-native compiler.
1965 // Objective-C source files. Only useful with cgo, and always
1966 // compiled with the OS-native compiler.
1968 // Assembler source files.
1969 // If the package uses cgo or SWIG, these will be assembled with the
1970 // OS-native assembler (typically gcc (sic)); otherwise they
1971 // will be assembled with the Go assembler.
1973 // SWIG definition files.
1975 // System object files.
1977 // Files of each of these types except .syso may contain build
1978 // constraints, but the go command stops scanning for build constraints
1979 // at the first item in the file that is not a blank line or //-style
1980 // line comment. See the go/build package documentation for
1986 // A module version is defined by a tree of source files, with a go.mod
1987 // file in its root. When the go command is run, it looks in the current
1988 // directory and then successive parent directories to find the go.mod
1989 // marking the root of the main (current) module.
1991 // The go.mod file format is described in detail at
1992 // https://golang.org/ref/mod#go-mod-file.
1994 // To create a new go.mod file, use 'go mod init'. For details see
1995 // 'go help mod init' or https://golang.org/ref/mod#go-mod-init.
1997 // To add missing module requirements or remove unneeded requirements,
1998 // use 'go mod tidy'. For details, see 'go help mod tidy' or
1999 // https://golang.org/ref/mod#go-mod-tidy.
2001 // To add, upgrade, downgrade, or remove a specific module requirement, use
2002 // 'go get'. For details, see 'go help module-get' or
2003 // https://golang.org/ref/mod#go-get.
2005 // To make other changes or to parse go.mod as JSON for use by other tools,
2006 // use 'go mod edit'. See 'go help mod edit' or
2007 // https://golang.org/ref/mod#go-mod-edit.
2010 // GOPATH environment variable
2012 // The Go path is used to resolve import statements.
2013 // It is implemented by and documented in the go/build package.
2015 // The GOPATH environment variable lists places to look for Go code.
2016 // On Unix, the value is a colon-separated string.
2017 // On Windows, the value is a semicolon-separated string.
2018 // On Plan 9, the value is a list.
2020 // If the environment variable is unset, GOPATH defaults
2021 // to a subdirectory named "go" in the user's home directory
2022 // ($HOME/go on Unix, %USERPROFILE%\go on Windows),
2023 // unless that directory holds a Go distribution.
2024 // Run "go env GOPATH" to see the current GOPATH.
2026 // See https://golang.org/wiki/SettingGOPATH to set a custom GOPATH.
2028 // Each directory listed in GOPATH must have a prescribed structure:
2030 // The src directory holds source code. The path below src
2031 // determines the import path or executable name.
2033 // The pkg directory holds installed package objects.
2034 // As in the Go tree, each target operating system and
2035 // architecture pair has its own subdirectory of pkg
2036 // (pkg/GOOS_GOARCH).
2038 // If DIR is a directory listed in the GOPATH, a package with
2039 // source in DIR/src/foo/bar can be imported as "foo/bar" and
2040 // has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a".
2042 // The bin directory holds compiled commands.
2043 // Each command is named for its source directory, but only
2044 // the final element, not the entire path. That is, the
2045 // command with source in DIR/src/foo/quux is installed into
2046 // DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped
2047 // so that you can add DIR/bin to your PATH to get at the
2048 // installed commands. If the GOBIN environment variable is
2049 // set, commands are installed to the directory it names instead
2050 // of DIR/bin. GOBIN must be an absolute path.
2052 // Here's an example directory layout:
2054 // GOPATH=/home/user/go
2059 // bar/ (go code in package bar)
2061 // quux/ (go code in package main)
2064 // quux (installed command)
2068 // bar.a (installed package object)
2070 // Go searches each directory listed in GOPATH to find source code,
2071 // but new packages are always downloaded into the first directory
2074 // See https://golang.org/doc/code.html for an example.
2076 // GOPATH and Modules
2078 // When using modules, GOPATH is no longer used for resolving imports.
2079 // However, it is still used to store downloaded source code (in GOPATH/pkg/mod)
2080 // and compiled commands (in GOPATH/bin).
2082 // Internal Directories
2084 // Code in or below a directory named "internal" is importable only
2085 // by code in the directory tree rooted at the parent of "internal".
2086 // Here's an extended version of the directory layout above:
2091 // bang/ (go code in package bang)
2093 // foo/ (go code in package foo)
2095 // bar/ (go code in package bar)
2098 // baz/ (go code in package baz)
2100 // quux/ (go code in package main)
2104 // The code in z.go is imported as "foo/internal/baz", but that
2105 // import statement can only appear in source files in the subtree
2106 // rooted at foo. The source files foo/f.go, foo/bar/x.go, and
2107 // foo/quux/y.go can all import "foo/internal/baz", but the source file
2108 // crash/bang/b.go cannot.
2110 // See https://golang.org/s/go14internal for details.
2112 // Vendor Directories
2114 // Go 1.6 includes support for using local copies of external dependencies
2115 // to satisfy imports of those dependencies, often referred to as vendoring.
2117 // Code below a directory named "vendor" is importable only
2118 // by code in the directory tree rooted at the parent of "vendor",
2119 // and only using an import path that omits the prefix up to and
2120 // including the vendor element.
2122 // Here's the example from the previous section,
2123 // but with the "internal" directory renamed to "vendor"
2124 // and a new foo/vendor/crash/bang directory added:
2129 // bang/ (go code in package bang)
2131 // foo/ (go code in package foo)
2133 // bar/ (go code in package bar)
2137 // bang/ (go code in package bang)
2139 // baz/ (go code in package baz)
2141 // quux/ (go code in package main)
2144 // The same visibility rules apply as for internal, but the code
2145 // in z.go is imported as "baz", not as "foo/vendor/baz".
2147 // Code in vendor directories deeper in the source tree shadows
2148 // code in higher directories. Within the subtree rooted at foo, an import
2149 // of "crash/bang" resolves to "foo/vendor/crash/bang", not the
2150 // top-level "crash/bang".
2152 // Code in vendor directories is not subject to import path
2153 // checking (see 'go help importpath').
2155 // When 'go get' checks out or updates a git repository, it now also
2156 // updates submodules.
2158 // Vendor directories do not affect the placement of new repositories
2159 // being checked out for the first time by 'go get': those are always
2160 // placed in the main GOPATH, never in a vendor subtree.
2162 // See https://golang.org/s/go15vendor for details.
2165 // Legacy GOPATH go get
2167 // The 'go get' command changes behavior depending on whether the
2168 // go command is running in module-aware mode or legacy GOPATH mode.
2169 // This help text, accessible as 'go help gopath-get' even in module-aware mode,
2170 // describes 'go get' as it operates in legacy GOPATH mode.
2172 // Usage: go get [-d] [-f] [-t] [-u] [-v] [-fix] [build flags] [packages]
2174 // Get downloads the packages named by the import paths, along with their
2175 // dependencies. It then installs the named packages, like 'go install'.
2177 // The -d flag instructs get to stop after downloading the packages; that is,
2178 // it instructs get not to install the packages.
2180 // The -f flag, valid only when -u is set, forces get -u not to verify that
2181 // each package has been checked out from the source control repository
2182 // implied by its import path. This can be useful if the source is a local fork
2185 // The -fix flag instructs get to run the fix tool on the downloaded packages
2186 // before resolving dependencies or building the code.
2188 // The -t flag instructs get to also download the packages required to build
2189 // the tests for the specified packages.
2191 // The -u flag instructs get to use the network to update the named packages
2192 // and their dependencies. By default, get uses the network to check out
2193 // missing packages but does not use it to look for updates to existing packages.
2195 // The -v flag enables verbose progress and debug output.
2197 // Get also accepts build flags to control the installation. See 'go help build'.
2199 // When checking out a new package, get creates the target directory
2200 // GOPATH/src/<import-path>. If the GOPATH contains multiple entries,
2201 // get uses the first one. For more details see: 'go help gopath'.
2203 // When checking out or updating a package, get looks for a branch or tag
2204 // that matches the locally installed version of Go. The most important
2205 // rule is that if the local installation is running version "go1", get
2206 // searches for a branch or tag named "go1". If no such version exists
2207 // it retrieves the default branch of the package.
2209 // When go get checks out or updates a Git repository,
2210 // it also updates any git submodules referenced by the repository.
2212 // Get never checks out or updates code stored in vendor directories.
2214 // For more about specifying packages, see 'go help packages'.
2216 // For more about how 'go get' finds source code to
2217 // download, see 'go help importpath'.
2219 // This text describes the behavior of get when using GOPATH
2220 // to manage source code and dependencies.
2221 // If instead the go command is running in module-aware mode,
2222 // the details of get's flags and effects change, as does 'go help get'.
2223 // See 'go help modules' and 'go help module-get'.
2225 // See also: go build, go install, go clean.
2228 // Module proxy protocol
2230 // A Go module proxy is any web server that can respond to GET requests for
2231 // URLs of a specified form. The requests have no query parameters, so even
2232 // a site serving from a fixed file system (including a file:/// URL)
2233 // can be a module proxy.
2235 // For details on the GOPROXY protocol, see
2236 // https://golang.org/ref/mod#goproxy-protocol.
2239 // Import path syntax
2241 // An import path (see 'go help packages') denotes a package stored in the local
2242 // file system. In general, an import path denotes either a standard package (such
2243 // as "unicode/utf8") or a package found in one of the work spaces (For more
2244 // details see: 'go help gopath').
2246 // Relative import paths
2248 // An import path beginning with ./ or ../ is called a relative path.
2249 // The toolchain supports relative import paths as a shortcut in two ways.
2251 // First, a relative path can be used as a shorthand on the command line.
2252 // If you are working in the directory containing the code imported as
2253 // "unicode" and want to run the tests for "unicode/utf8", you can type
2254 // "go test ./utf8" instead of needing to specify the full path.
2255 // Similarly, in the reverse situation, "go test .." will test "unicode" from
2256 // the "unicode/utf8" directory. Relative patterns are also allowed, like
2257 // "go test ./..." to test all subdirectories. See 'go help packages' for details
2258 // on the pattern syntax.
2260 // Second, if you are compiling a Go program not in a work space,
2261 // you can use a relative path in an import statement in that program
2262 // to refer to nearby code also not in a work space.
2263 // This makes it easy to experiment with small multipackage programs
2264 // outside of the usual work spaces, but such programs cannot be
2265 // installed with "go install" (there is no work space in which to install them),
2266 // so they are rebuilt from scratch each time they are built.
2267 // To avoid ambiguity, Go programs cannot use relative import paths
2268 // within a work space.
2270 // Remote import paths
2272 // Certain import paths also
2273 // describe how to obtain the source code for the package using
2274 // a revision control system.
2276 // A few common code hosting sites have special syntax:
2278 // Bitbucket (Git, Mercurial)
2280 // import "bitbucket.org/user/project"
2281 // import "bitbucket.org/user/project/sub/directory"
2285 // import "github.com/user/project"
2286 // import "github.com/user/project/sub/directory"
2288 // Launchpad (Bazaar)
2290 // import "launchpad.net/project"
2291 // import "launchpad.net/project/series"
2292 // import "launchpad.net/project/series/sub/directory"
2294 // import "launchpad.net/~user/project/branch"
2295 // import "launchpad.net/~user/project/branch/sub/directory"
2297 // IBM DevOps Services (Git)
2299 // import "hub.jazz.net/git/user/project"
2300 // import "hub.jazz.net/git/user/project/sub/directory"
2302 // For code hosted on other servers, import paths may either be qualified
2303 // with the version control type, or the go tool can dynamically fetch
2304 // the import path over https/http and discover where the code resides
2305 // from a <meta> tag in the HTML.
2307 // To declare the code location, an import path of the form
2309 // repository.vcs/path
2311 // specifies the given repository, with or without the .vcs suffix,
2312 // using the named version control system, and then the path inside
2313 // that repository. The supported version control systems are:
2323 // import "example.org/user/foo.hg"
2325 // denotes the root directory of the Mercurial repository at
2326 // example.org/user/foo or foo.hg, and
2328 // import "example.org/repo.git/foo/bar"
2330 // denotes the foo/bar directory of the Git repository at
2331 // example.org/repo or repo.git.
2333 // When a version control system supports multiple protocols,
2334 // each is tried in turn when downloading. For example, a Git
2335 // download tries https://, then git+ssh://.
2337 // By default, downloads are restricted to known secure protocols
2338 // (e.g. https, ssh). To override this setting for Git downloads, the
2339 // GIT_ALLOW_PROTOCOL environment variable can be set (For more details see:
2340 // 'go help environment').
2342 // If the import path is not a known code hosting site and also lacks a
2343 // version control qualifier, the go tool attempts to fetch the import
2344 // over https/http and looks for a <meta> tag in the document's HTML
2347 // The meta tag has the form:
2349 // <meta name="go-import" content="import-prefix vcs repo-root">
2351 // The import-prefix is the import path corresponding to the repository
2352 // root. It must be a prefix or an exact match of the package being
2353 // fetched with "go get". If it's not an exact match, another http
2354 // request is made at the prefix to verify the <meta> tags match.
2356 // The meta tag should appear as early in the file as possible.
2357 // In particular, it should appear before any raw JavaScript or CSS,
2358 // to avoid confusing the go command's restricted parser.
2360 // The vcs is one of "bzr", "fossil", "git", "hg", "svn".
2362 // The repo-root is the root of the version control system
2363 // containing a scheme and not containing a .vcs qualifier.
2367 // import "example.org/pkg/foo"
2369 // will result in the following requests:
2371 // https://example.org/pkg/foo?go-get=1 (preferred)
2372 // http://example.org/pkg/foo?go-get=1 (fallback, only with use of correctly set GOINSECURE)
2374 // If that page contains the meta tag
2376 // <meta name="go-import" content="example.org git https://code.org/r/p/exproj">
2378 // the go tool will verify that https://example.org/?go-get=1 contains the
2379 // same meta tag and then git clone https://code.org/r/p/exproj into
2380 // GOPATH/src/example.org.
2382 // When using GOPATH, downloaded packages are written to the first directory
2383 // listed in the GOPATH environment variable.
2384 // (See 'go help gopath-get' and 'go help gopath'.)
2386 // When using modules, downloaded packages are stored in the module cache.
2387 // See https://golang.org/ref/mod#module-cache.
2389 // When using modules, an additional variant of the go-import meta tag is
2390 // recognized and is preferred over those listing version control systems.
2391 // That variant uses "mod" as the vcs in the content value, as in:
2393 // <meta name="go-import" content="example.org mod https://code.org/moduleproxy">
2395 // This tag means to fetch modules with paths beginning with example.org
2396 // from the module proxy available at the URL https://code.org/moduleproxy.
2397 // See https://golang.org/ref/mod#goproxy-protocol for details about the
2400 // Import path checking
2402 // When the custom import path feature described above redirects to a
2403 // known code hosting site, each of the resulting packages has two possible
2404 // import paths, using the custom domain or the known hosting site.
2406 // A package statement is said to have an "import comment" if it is immediately
2407 // followed (before the next newline) by a comment of one of these two forms:
2409 // package math // import "path"
2410 // package math /* import "path" */
2412 // The go command will refuse to install a package with an import comment
2413 // unless it is being referred to by that import path. In this way, import comments
2414 // let package authors make sure the custom import path is used and not a
2415 // direct path to the underlying code hosting site.
2417 // Import path checking is disabled for code found within vendor trees.
2418 // This makes it possible to copy code into alternate locations in vendor trees
2419 // without needing to update import comments.
2421 // Import path checking is also disabled when using modules.
2422 // Import path comments are obsoleted by the go.mod file's module statement.
2424 // See https://golang.org/s/go14customimport for details.
2427 // Modules, module versions, and more
2429 // Modules are how Go manages dependencies.
2431 // A module is a collection of packages that are released, versioned, and
2432 // distributed together. Modules may be downloaded directly from version control
2433 // repositories or from module proxy servers.
2435 // For a series of tutorials on modules, see
2436 // https://golang.org/doc/tutorial/create-module.
2438 // For a detailed reference on modules, see https://golang.org/ref/mod.
2440 // By default, the go command may download modules from https://proxy.golang.org.
2441 // It may authenticate modules using the checksum database at
2442 // https://sum.golang.org. Both services are operated by the Go team at Google.
2443 // The privacy policies for these services are available at
2444 // https://proxy.golang.org/privacy and https://sum.golang.org/privacy,
2447 // The go command's download behavior may be configured using GOPROXY, GOSUMDB,
2448 // GOPRIVATE, and other environment variables. See 'go help environment'
2449 // and https://golang.org/ref/mod#private-module-privacy for more information.
2452 // Module authentication using go.sum
2454 // When the go command downloads a module zip file or go.mod file into the
2455 // module cache, it computes a cryptographic hash and compares it with a known
2456 // value to verify the file hasn't changed since it was first downloaded. Known
2457 // hashes are stored in a file in the module root directory named go.sum. Hashes
2458 // may also be downloaded from the checksum database depending on the values of
2459 // GOSUMDB, GOPRIVATE, and GONOSUMDB.
2461 // For details, see https://golang.org/ref/mod#authenticating.
2464 // Package lists and patterns
2466 // Many commands apply to a set of packages:
2468 // go action [packages]
2470 // Usually, [packages] is a list of import paths.
2472 // An import path that is a rooted path or that begins with
2473 // a . or .. element is interpreted as a file system path and
2474 // denotes the package in that directory.
2476 // Otherwise, the import path P denotes the package found in
2477 // the directory DIR/src/P for some DIR listed in the GOPATH
2478 // environment variable (For more details see: 'go help gopath').
2480 // If no import paths are given, the action applies to the
2481 // package in the current directory.
2483 // There are four reserved names for paths that should not be used
2484 // for packages to be built with the go tool:
2486 // - "main" denotes the top-level package in a stand-alone executable.
2488 // - "all" expands to all packages found in all the GOPATH
2489 // trees. For example, 'go list all' lists all the packages on the local
2490 // system. When using modules, "all" expands to all packages in
2491 // the main module and their dependencies, including dependencies
2492 // needed by tests of any of those.
2494 // - "std" is like all but expands to just the packages in the standard
2497 // - "cmd" expands to the Go repository's commands and their
2498 // internal libraries.
2500 // Import paths beginning with "cmd/" only match source code in
2501 // the Go repository.
2503 // An import path is a pattern if it includes one or more "..." wildcards,
2504 // each of which can match any string, including the empty string and
2505 // strings containing slashes. Such a pattern expands to all package
2506 // directories found in the GOPATH trees with names matching the
2509 // To make common patterns more convenient, there are two special cases.
2510 // First, /... at the end of the pattern can match an empty string,
2511 // so that net/... matches both net and packages in its subdirectories, like net/http.
2512 // Second, any slash-separated pattern element containing a wildcard never
2513 // participates in a match of the "vendor" element in the path of a vendored
2514 // package, so that ./... does not match packages in subdirectories of
2515 // ./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do.
2516 // Note, however, that a directory named vendor that itself contains code
2517 // is not a vendored package: cmd/vendor would be a command named vendor,
2518 // and the pattern cmd/... matches it.
2519 // See golang.org/s/go15vendor for more about vendoring.
2521 // An import path can also name a package to be downloaded from
2522 // a remote repository. Run 'go help importpath' for details.
2524 // Every package in a program must have a unique import path.
2525 // By convention, this is arranged by starting each path with a
2526 // unique prefix that belongs to you. For example, paths used
2527 // internally at Google all begin with 'google', and paths
2528 // denoting remote repositories begin with the path to the code,
2529 // such as 'github.com/user/repo'.
2531 // Packages in a program need not have unique package names,
2532 // but there are two reserved package names with special meaning.
2533 // The name main indicates a command, not a library.
2534 // Commands are built into binaries and cannot be imported.
2535 // The name documentation indicates documentation for
2536 // a non-Go program in the directory. Files in package documentation
2537 // are ignored by the go command.
2539 // As a special case, if the package list is a list of .go files from a
2540 // single directory, the command is applied to a single synthesized
2541 // package made up of exactly those files, ignoring any build constraints
2542 // in those files and ignoring any other files in the directory.
2544 // Directory and file names that begin with "." or "_" are ignored
2545 // by the go tool, as are directories named "testdata".
2548 // Configuration for downloading non-public code
2550 // The go command defaults to downloading modules from the public Go module
2551 // mirror at proxy.golang.org. It also defaults to validating downloaded modules,
2552 // regardless of source, against the public Go checksum database at sum.golang.org.
2553 // These defaults work well for publicly available source code.
2555 // The GOPRIVATE environment variable controls which modules the go command
2556 // considers to be private (not available publicly) and should therefore not use
2557 // the proxy or checksum database. The variable is a comma-separated list of
2558 // glob patterns (in the syntax of Go's path.Match) of module path prefixes.
2561 // GOPRIVATE=*.corp.example.com,rsc.io/private
2563 // causes the go command to treat as private any module with a path prefix
2564 // matching either pattern, including git.corp.example.com/xyzzy, rsc.io/private,
2565 // and rsc.io/private/quux.
2567 // For fine-grained control over module download and validation, the GONOPROXY
2568 // and GONOSUMDB environment variables accept the same kind of glob list
2569 // and override GOPRIVATE for the specific decision of whether to use the proxy
2570 // and checksum database, respectively.
2572 // For example, if a company ran a module proxy serving private modules,
2573 // users would configure go using:
2575 // GOPRIVATE=*.corp.example.com
2576 // GOPROXY=proxy.example.com
2579 // The GOPRIVATE variable is also used to define the "public" and "private"
2580 // patterns for the GOVCS variable; see 'go help vcs'. For that usage,
2581 // GOPRIVATE applies even in GOPATH mode. In that case, it matches import paths
2582 // instead of module paths.
2584 // The 'go env -w' command (see 'go help env') can be used to set these variables
2585 // for future go command invocations.
2587 // For more details, see https://golang.org/ref/mod#private-modules.
2592 // The 'go test' command takes both flags that apply to 'go test' itself
2593 // and flags that apply to the resulting test binary.
2595 // Several of the flags control profiling and write an execution profile
2596 // suitable for "go tool pprof"; run "go tool pprof -h" for more
2597 // information. The --alloc_space, --alloc_objects, and --show_bytes
2598 // options of pprof control how the information is presented.
2600 // The following flags are recognized by the 'go test' command and
2601 // control the execution of any test:
2604 // Run only those benchmarks matching a regular expression.
2605 // By default, no benchmarks are run.
2606 // To run all benchmarks, use '-bench .' or '-bench=.'.
2607 // The regular expression is split by unbracketed slash (/)
2608 // characters into a sequence of regular expressions, and each
2609 // part of a benchmark's identifier must match the corresponding
2610 // element in the sequence, if any. Possible parents of matches
2611 // are run with b.N=1 to identify sub-benchmarks. For example,
2612 // given -bench=X/Y, top-level benchmarks matching X are run
2613 // with b.N=1 to find any sub-benchmarks matching Y, which are
2614 // then run in full.
2617 // Run enough iterations of each benchmark to take t, specified
2618 // as a time.Duration (for example, -benchtime 1h30s).
2619 // The default is 1 second (1s).
2620 // The special syntax Nx means to run the benchmark N times
2621 // (for example, -benchtime 100x).
2624 // Run each test, benchmark, and fuzz targets' seed corpora n times
2626 // If -cpu is set, run n times for each GOMAXPROCS value.
2627 // Examples are always run once.
2630 // Enable coverage analysis.
2631 // Note that because coverage works by annotating the source
2632 // code before compilation, compilation and test failures with
2633 // coverage enabled may report line numbers that don't correspond
2634 // to the original sources.
2636 // -covermode set,count,atomic
2637 // Set the mode for coverage analysis for the package[s]
2638 // being tested. The default is "set" unless -race is enabled,
2639 // in which case it is "atomic".
2641 // set: bool: does this statement run?
2642 // count: int: how many times does this statement run?
2643 // atomic: int: count, but correct in multithreaded tests;
2644 // significantly more expensive.
2647 // -coverpkg pattern1,pattern2,pattern3
2648 // Apply coverage analysis in each test to packages matching the patterns.
2649 // The default is for each test to analyze only the package being tested.
2650 // See 'go help packages' for a description of package patterns.
2654 // Specify a list of GOMAXPROCS values for which the tests, benchmarks or
2655 // fuzz targets should be executed. The default is the current value
2659 // Do not start new tests after the first test failure.
2662 // Run the fuzz target with the given regexp. Must match exactly one fuzz
2663 // target. This is an experimental feature.
2666 // Run enough iterations of the fuzz test to take t, specified as a
2667 // time.Duration (for example, -fuzztime 1h30s). The default is to run
2669 // The special syntax Nx means to run the fuzz test N times
2670 // (for example, -fuzztime 100x).
2673 // Keep running the fuzz target if a crasher is found.
2676 // List tests, benchmarks, fuzz targets, or examples matching the regular
2677 // expression. No tests, benchmarks, fuzz targets, or examples will be run.
2678 // This will only list top-level tests. No subtest or subbenchmarks will be
2682 // Allow parallel execution of test functions that call t.Parallel, and
2683 // f.Fuzz functions that call t.Parallel when running the seed corpus.
2684 // The value of this flag is the maximum number of tests to run
2685 // simultaneously. While fuzzing, the value of this flag is the
2686 // maximum number of workers to run the fuzz function simultaneously,
2687 // regardless of whether t.Parallel has been called; by default, it is set
2688 // to the value of GOMAXPROCS.
2689 // Note that -parallel only applies within a single test binary.
2690 // The 'go test' command may run tests for different packages
2691 // in parallel as well, according to the setting of the -p flag
2692 // (see 'go help build').
2695 // Run only those tests, examples, and fuzz targets matching the regular
2696 // expression. For tests, the regular expression is split by unbracketed
2697 // slash (/) characters into a sequence of regular expressions, and each
2698 // part of a test's identifier must match the corresponding element in
2699 // the sequence, if any. Note that possible parents of matches are
2700 // run too, so that -run=X/Y matches and runs and reports the result
2701 // of all tests matching X, even those without sub-tests matching Y,
2702 // because it must run them to look for those sub-tests.
2705 // Tell long-running tests to shorten their run time.
2706 // It is off by default but set during all.bash so that installing
2707 // the Go tree can run a sanity check but not spend time running
2708 // exhaustive tests.
2710 // -shuffle off,on,N
2711 // Randomize the execution order of tests and benchmarks.
2712 // It is off by default. If -shuffle is set to on, then it will seed
2713 // the randomizer using the system clock. If -shuffle is set to an
2714 // integer N, then N will be used as the seed value. In both cases,
2715 // the seed will be reported for reproducibility.
2718 // If a test binary runs longer than duration d, panic.
2719 // If d is 0, the timeout is disabled.
2720 // The default is 10 minutes (10m).
2723 // Verbose output: log all tests as they are run. Also print all
2724 // text from Log and Logf calls even if the test succeeds.
2727 // Configure the invocation of "go vet" during "go test"
2728 // to use the comma-separated list of vet checks.
2729 // If list is empty, "go test" runs "go vet" with a curated list of
2730 // checks believed to be always worth addressing.
2731 // If list is "off", "go test" does not run "go vet" at all.
2733 // The following flags are also recognized by 'go test' and can be used to
2734 // profile the tests during execution:
2737 // Print memory allocation statistics for benchmarks.
2739 // -blockprofile block.out
2740 // Write a goroutine blocking profile to the specified file
2741 // when all tests are complete.
2742 // Writes test binary as -c would.
2744 // -blockprofilerate n
2745 // Control the detail provided in goroutine blocking profiles by
2746 // calling runtime.SetBlockProfileRate with n.
2747 // See 'go doc runtime.SetBlockProfileRate'.
2748 // The profiler aims to sample, on average, one blocking event every
2749 // n nanoseconds the program spends blocked. By default,
2750 // if -test.blockprofile is set without this flag, all blocking events
2751 // are recorded, equivalent to -test.blockprofilerate=1.
2753 // -coverprofile cover.out
2754 // Write a coverage profile to the file after all tests have passed.
2757 // -cpuprofile cpu.out
2758 // Write a CPU profile to the specified file before exiting.
2759 // Writes test binary as -c would.
2761 // -memprofile mem.out
2762 // Write an allocation profile to the file after all tests have passed.
2763 // Writes test binary as -c would.
2765 // -memprofilerate n
2766 // Enable more precise (and expensive) memory allocation profiles by
2767 // setting runtime.MemProfileRate. See 'go doc runtime.MemProfileRate'.
2768 // To profile all memory allocations, use -test.memprofilerate=1.
2770 // -mutexprofile mutex.out
2771 // Write a mutex contention profile to the specified file
2772 // when all tests are complete.
2773 // Writes test binary as -c would.
2775 // -mutexprofilefraction n
2776 // Sample 1 in n stack traces of goroutines holding a
2779 // -outputdir directory
2780 // Place output files from profiling in the specified directory,
2781 // by default the directory in which "go test" is running.
2784 // Write an execution trace to the specified file before exiting.
2786 // Each of these flags is also recognized with an optional 'test.' prefix,
2787 // as in -test.v. When invoking the generated test binary (the result of
2788 // 'go test -c') directly, however, the prefix is mandatory.
2790 // The 'go test' command rewrites or removes recognized flags,
2791 // as appropriate, both before and after the optional package list,
2792 // before invoking the test binary.
2794 // For instance, the command
2796 // go test -v -myflag testdata -cpuprofile=prof.out -x
2798 // will compile the test binary and then run it as
2800 // pkg.test -test.v -myflag testdata -test.cpuprofile=prof.out
2802 // (The -x flag is removed because it applies only to the go command's
2803 // execution, not to the test itself.)
2805 // The test flags that generate profiles (other than for coverage) also
2806 // leave the test binary in pkg.test for use when analyzing the profiles.
2808 // When 'go test' runs a test binary, it does so from within the
2809 // corresponding package's source code directory. Depending on the test,
2810 // it may be necessary to do the same when invoking a generated test
2813 // The command-line package list, if present, must appear before any
2814 // flag not known to the go test command. Continuing the example above,
2815 // the package list would have to appear before -myflag, but could appear
2816 // on either side of -v.
2818 // When 'go test' runs in package list mode, 'go test' caches successful
2819 // package test results to avoid unnecessary repeated running of tests. To
2820 // disable test caching, use any test flag or argument other than the
2821 // cacheable flags. The idiomatic way to disable test caching explicitly
2822 // is to use -count=1.
2824 // To keep an argument for a test binary from being interpreted as a
2825 // known flag or a package name, use -args (see 'go help test') which
2826 // passes the remainder of the command line through to the test binary
2827 // uninterpreted and unaltered.
2829 // For instance, the command
2831 // go test -v -args -x -v
2833 // will compile the test binary and then run it as
2835 // pkg.test -test.v -x -v
2839 // go test -args math
2841 // will compile the test binary and then run it as
2845 // In the first example, the -x and the second -v are passed through to the
2846 // test binary unchanged and with no effect on the go command itself.
2847 // In the second example, the argument math is passed through to the test
2848 // binary, instead of being interpreted as the package list.
2851 // Testing functions
2853 // The 'go test' command expects to find test, benchmark, and example functions
2854 // in the "*_test.go" files corresponding to the package under test.
2856 // A test function is one named TestXxx (where Xxx does not start with a
2857 // lower case letter) and should have the signature,
2859 // func TestXxx(t *testing.T) { ... }
2861 // A benchmark function is one named BenchmarkXxx and should have the signature,
2863 // func BenchmarkXxx(b *testing.B) { ... }
2865 // A fuzz target is one named FuzzXxx and should have the signature,
2867 // func FuzzXxx(f *testing.F) { ... }
2869 // An example function is similar to a test function but, instead of using
2870 // *testing.T to report success or failure, prints output to os.Stdout.
2871 // If the last comment in the function starts with "Output:" then the output
2872 // is compared exactly against the comment (see examples below). If the last
2873 // comment begins with "Unordered output:" then the output is compared to the
2874 // comment, however the order of the lines is ignored. An example with no such
2875 // comment is compiled but not executed. An example with no text after
2876 // "Output:" is compiled, executed, and expected to produce no output.
2878 // Godoc displays the body of ExampleXxx to demonstrate the use
2879 // of the function, constant, or variable Xxx. An example of a method M with
2880 // receiver type T or *T is named ExampleT_M. There may be multiple examples
2881 // for a given function, constant, or variable, distinguished by a trailing _xxx,
2882 // where xxx is a suffix not beginning with an upper case letter.
2884 // Here is an example of an example:
2886 // func ExamplePrintln() {
2887 // Println("The output of\nthis example.")
2888 // // Output: The output of
2892 // Here is another example where the ordering of the output is ignored:
2894 // func ExamplePerm() {
2895 // for _, value := range Perm(4) {
2896 // fmt.Println(value)
2899 // // Unordered output: 4
2906 // The entire test file is presented as the example when it contains a single
2907 // example function, at least one other function, type, variable, or constant
2908 // declaration, and no fuzz targets or test or benchmark functions.
2910 // See the documentation of the testing package for more information.
2915 // By default, go test will build and run the fuzz targets using the target's seed
2916 // corpus only. Any generated corpora in $GOCACHE that were previously written by
2917 // the fuzzing engine will not be run by default.
2919 // When -fuzz is set, the binary will be instrumented for coverage. After all
2920 // tests, examples, benchmark functions, and the seed corpora for all fuzz targets
2921 // have been run, go test will begin to fuzz the specified fuzz target.
2922 // Note that this feature is experimental.
2924 // -run can be used for testing a single seed corpus entry for a fuzz target. The
2925 // regular expression value of -run can be in the form $target/$name, where $target
2926 // is the name of the fuzz target, and $name is the name of the file (ignoring file
2927 // extensions) to run. For example, -run=FuzzFoo/497b6f87.
2929 // See https://golang.org/s/draft-fuzzing-design for more details.
2932 // Controlling version control with GOVCS
2934 // The 'go get' command can run version control commands like git
2935 // to download imported code. This functionality is critical to the decentralized
2936 // Go package ecosystem, in which code can be imported from any server,
2937 // but it is also a potential security problem, if a malicious server finds a
2938 // way to cause the invoked version control command to run unintended code.
2940 // To balance the functionality and security concerns, the 'go get' command
2941 // by default will only use git and hg to download code from public servers.
2942 // But it will use any known version control system (bzr, fossil, git, hg, svn)
2943 // to download code from private servers, defined as those hosting packages
2944 // matching the GOPRIVATE variable (see 'go help private'). The rationale behind
2945 // allowing only Git and Mercurial is that these two systems have had the most
2946 // attention to issues of being run as clients of untrusted servers. In contrast,
2947 // Bazaar, Fossil, and Subversion have primarily been used in trusted,
2948 // authenticated environments and are not as well scrutinized as attack surfaces.
2950 // The version control command restrictions only apply when using direct version
2951 // control access to download code. When downloading modules from a proxy,
2952 // 'go get' uses the proxy protocol instead, which is always permitted.
2953 // By default, the 'go get' command uses the Go module mirror (proxy.golang.org)
2954 // for public packages and only falls back to version control for private
2955 // packages or when the mirror refuses to serve a public package (typically for
2956 // legal reasons). Therefore, clients can still access public code served from
2957 // Bazaar, Fossil, or Subversion repositories by default, because those downloads
2958 // use the Go module mirror, which takes on the security risk of running the
2959 // version control commands using a custom sandbox.
2961 // The GOVCS variable can be used to change the allowed version control systems
2962 // for specific packages (identified by a module or import path).
2963 // The GOVCS variable applies when building package in both module-aware mode
2964 // and GOPATH mode. When using modules, the patterns match against the module path.
2965 // When using GOPATH, the patterns match against the import path corresponding to
2966 // the root of the version control repository.
2968 // The general form of the GOVCS setting is a comma-separated list of
2969 // pattern:vcslist rules. The pattern is a glob pattern that must match
2970 // one or more leading elements of the module or import path. The vcslist
2971 // is a pipe-separated list of allowed version control commands, or "all"
2972 // to allow use of any known command, or "off" to disallow all commands.
2973 // Note that if a module matches a pattern with vcslist "off", it may still be
2974 // downloaded if the origin server uses the "mod" scheme, which instructs the
2975 // go command to download the module using the GOPROXY protocol.
2976 // The earliest matching pattern in the list applies, even if later patterns
2977 // might also match.
2979 // For example, consider:
2981 // GOVCS=github.com:git,evil.com:off,*:git|hg
2983 // With this setting, code with a module or import path beginning with
2984 // github.com/ can only use git; paths on evil.com cannot use any version
2985 // control command, and all other paths (* matches everything) can use
2988 // The special patterns "public" and "private" match public and private
2989 // module or import paths. A path is private if it matches the GOPRIVATE
2990 // variable; otherwise it is public.
2992 // If no rules in the GOVCS variable match a particular module or import path,
2993 // the 'go get' command applies its default rule, which can now be summarized
2994 // in GOVCS notation as 'public:git|hg,private:all'.
2996 // To allow unfettered use of any version control system for any package, use:
3000 // To disable all use of version control, use:
3004 // The 'go env -w' command (see 'go help env') can be used to set the GOVCS
3005 // variable for future go command invocations.