...
Run Format

Source file src/cmd/go/alldocs.go

Documentation: cmd/go

     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.
     4  
     5  // Code generated by mkalldocs.sh; DO NOT EDIT.
     6  // Edit the documentation in other files and rerun mkalldocs.sh to generate this one.
     7  
     8  // Go is a tool for managing Go source code.
     9  //
    10  // Usage:
    11  //
    12  // 	go <command> [arguments]
    13  //
    14  // The commands are:
    15  //
    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         download and install packages and dependencies
    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
    29  // 	test        test packages
    30  // 	tool        run specified go tool
    31  // 	version     print Go version
    32  // 	vet         report likely mistakes in packages
    33  //
    34  // Use "go help <command>" for more information about a command.
    35  //
    36  // Additional help topics:
    37  //
    38  // 	buildmode   build modes
    39  // 	c           calling between Go and C
    40  // 	cache       build and test caching
    41  // 	environment environment variables
    42  // 	filetype    file types
    43  // 	go.mod      the go.mod file
    44  // 	gopath      GOPATH environment variable
    45  // 	gopath-get  legacy GOPATH go get
    46  // 	goproxy     module proxy protocol
    47  // 	importpath  import path syntax
    48  // 	modules     modules, module versions, and more
    49  // 	module-get  module-aware go get
    50  // 	packages    package lists and patterns
    51  // 	testflag    testing flags
    52  // 	testfunc    testing functions
    53  //
    54  // Use "go help <topic>" for more information about that topic.
    55  //
    56  //
    57  // Start a bug report
    58  //
    59  // Usage:
    60  //
    61  // 	go bug
    62  //
    63  // Bug opens the default browser and starts a new bug report.
    64  // The report includes useful system information.
    65  //
    66  //
    67  // Compile packages and dependencies
    68  //
    69  // Usage:
    70  //
    71  // 	go build [-o output] [-i] [build flags] [packages]
    72  //
    73  // Build compiles the packages named by the import paths,
    74  // along with their dependencies, but it does not install the results.
    75  //
    76  // If the arguments to build are a list of .go files, build treats
    77  // them as a list of source files specifying a single package.
    78  //
    79  // When compiling a single main package, build writes
    80  // the resulting executable to an output file named after
    81  // the first source file ('go build ed.go rx.go' writes 'ed' or 'ed.exe')
    82  // or the source code directory ('go build unix/sam' writes 'sam' or 'sam.exe').
    83  // The '.exe' suffix is added when writing a Windows executable.
    84  //
    85  // When compiling multiple packages or a single non-main package,
    86  // build compiles the packages but discards the resulting object,
    87  // serving only as a check that the packages can be built.
    88  //
    89  // When compiling packages, build ignores files that end in '_test.go'.
    90  //
    91  // The -o flag, only allowed when compiling a single package,
    92  // forces build to write the resulting executable or object
    93  // to the named output file, instead of the default behavior described
    94  // in the last two paragraphs.
    95  //
    96  // The -i flag installs the packages that are dependencies of the target.
    97  //
    98  // The build flags are shared by the build, clean, get, install, list, run,
    99  // and test commands:
   100  //
   101  // 	-a
   102  // 		force rebuilding of packages that are already up-to-date.
   103  // 	-n
   104  // 		print the commands but do not run them.
   105  // 	-p n
   106  // 		the number of programs, such as build commands or
   107  // 		test binaries, that can be run in parallel.
   108  // 		The default is the number of CPUs available.
   109  // 	-race
   110  // 		enable data race detection.
   111  // 		Supported only on linux/amd64, freebsd/amd64, darwin/amd64 and windows/amd64.
   112  // 	-msan
   113  // 		enable interoperation with memory sanitizer.
   114  // 		Supported only on linux/amd64, linux/arm64
   115  // 		and only with Clang/LLVM as the host C compiler.
   116  // 	-v
   117  // 		print the names of packages as they are compiled.
   118  // 	-work
   119  // 		print the name of the temporary work directory and
   120  // 		do not delete it when exiting.
   121  // 	-x
   122  // 		print the commands.
   123  //
   124  // 	-asmflags '[pattern=]arg list'
   125  // 		arguments to pass on each go tool asm invocation.
   126  // 	-buildmode mode
   127  // 		build mode to use. See 'go help buildmode' for more.
   128  // 	-compiler name
   129  // 		name of compiler to use, as in runtime.Compiler (gccgo or gc).
   130  // 	-gccgoflags '[pattern=]arg list'
   131  // 		arguments to pass on each gccgo compiler/linker invocation.
   132  // 	-gcflags '[pattern=]arg list'
   133  // 		arguments to pass on each go tool compile invocation.
   134  // 	-installsuffix suffix
   135  // 		a suffix to use in the name of the package installation directory,
   136  // 		in order to keep output separate from default builds.
   137  // 		If using the -race flag, the install suffix is automatically set to race
   138  // 		or, if set explicitly, has _race appended to it. Likewise for the -msan
   139  // 		flag. Using a -buildmode option that requires non-default compile flags
   140  // 		has a similar effect.
   141  // 	-ldflags '[pattern=]arg list'
   142  // 		arguments to pass on each go tool link invocation.
   143  // 	-linkshared
   144  // 		link against shared libraries previously created with
   145  // 		-buildmode=shared.
   146  // 	-mod mode
   147  // 		module download mode to use: readonly or vendor.
   148  // 		See 'go help modules' for more.
   149  // 	-pkgdir dir
   150  // 		install and load all packages from dir instead of the usual locations.
   151  // 		For example, when building with a non-standard configuration,
   152  // 		use -pkgdir to keep generated packages in a separate location.
   153  // 	-tags 'tag list'
   154  // 		a space-separated list of build tags to consider satisfied during the
   155  // 		build. For more information about build tags, see the description of
   156  // 		build constraints in the documentation for the go/build package.
   157  // 	-toolexec 'cmd args'
   158  // 		a program to use to invoke toolchain programs like vet and asm.
   159  // 		For example, instead of running asm, the go command will run
   160  // 		'cmd args /path/to/asm <arguments for asm>'.
   161  //
   162  // The -asmflags, -gccgoflags, -gcflags, and -ldflags flags accept a
   163  // space-separated list of arguments to pass to an underlying tool
   164  // during the build. To embed spaces in an element in the list, surround
   165  // it with either single or double quotes. The argument list may be
   166  // preceded by a package pattern and an equal sign, which restricts
   167  // the use of that argument list to the building of packages matching
   168  // that pattern (see 'go help packages' for a description of package
   169  // patterns). Without a pattern, the argument list applies only to the
   170  // packages named on the command line. The flags may be repeated
   171  // with different patterns in order to specify different arguments for
   172  // different sets of packages. If a package matches patterns given in
   173  // multiple flags, the latest match on the command line wins.
   174  // For example, 'go build -gcflags=-S fmt' prints the disassembly
   175  // only for package fmt, while 'go build -gcflags=all=-S fmt'
   176  // prints the disassembly for fmt and all its dependencies.
   177  //
   178  // For more about specifying packages, see 'go help packages'.
   179  // For more about where packages and binaries are installed,
   180  // run 'go help gopath'.
   181  // For more about calling between Go and C/C++, run 'go help c'.
   182  //
   183  // Note: Build adheres to certain conventions such as those described
   184  // by 'go help gopath'. Not all projects can follow these conventions,
   185  // however. Installations that have their own conventions or that use
   186  // a separate software build system may choose to use lower-level
   187  // invocations such as 'go tool compile' and 'go tool link' to avoid
   188  // some of the overheads and design decisions of the build tool.
   189  //
   190  // See also: go install, go get, go clean.
   191  //
   192  //
   193  // Remove object files and cached files
   194  //
   195  // Usage:
   196  //
   197  // 	go clean [clean flags] [build flags] [packages]
   198  //
   199  // Clean removes object files from package source directories.
   200  // The go command builds most objects in a temporary directory,
   201  // so go clean is mainly concerned with object files left by other
   202  // tools or by manual invocations of go build.
   203  //
   204  // Specifically, clean removes the following files from each of the
   205  // source directories corresponding to the import paths:
   206  //
   207  // 	_obj/            old object directory, left from Makefiles
   208  // 	_test/           old test directory, left from Makefiles
   209  // 	_testmain.go     old gotest file, left from Makefiles
   210  // 	test.out         old test log, left from Makefiles
   211  // 	build.out        old test log, left from Makefiles
   212  // 	*.[568ao]        object files, left from Makefiles
   213  //
   214  // 	DIR(.exe)        from go build
   215  // 	DIR.test(.exe)   from go test -c
   216  // 	MAINFILE(.exe)   from go build MAINFILE.go
   217  // 	*.so             from SWIG
   218  //
   219  // In the list, DIR represents the final path element of the
   220  // directory, and MAINFILE is the base name of any Go source
   221  // file in the directory that is not included when building
   222  // the package.
   223  //
   224  // The -i flag causes clean to remove the corresponding installed
   225  // archive or binary (what 'go install' would create).
   226  //
   227  // The -n flag causes clean to print the remove commands it would execute,
   228  // but not run them.
   229  //
   230  // The -r flag causes clean to be applied recursively to all the
   231  // dependencies of the packages named by the import paths.
   232  //
   233  // The -x flag causes clean to print remove commands as it executes them.
   234  //
   235  // The -cache flag causes clean to remove the entire go build cache.
   236  //
   237  // The -testcache flag causes clean to expire all test results in the
   238  // go build cache.
   239  //
   240  // The -modcache flag causes clean to remove the entire module
   241  // download cache, including unpacked source code of versioned
   242  // dependencies.
   243  //
   244  // For more about build flags, see 'go help build'.
   245  //
   246  // For more about specifying packages, see 'go help packages'.
   247  //
   248  //
   249  // Show documentation for package or symbol
   250  //
   251  // Usage:
   252  //
   253  // 	go doc [-u] [-c] [package|[package.]symbol[.methodOrField]]
   254  //
   255  // Doc prints the documentation comments associated with the item identified by its
   256  // arguments (a package, const, func, type, var, method, or struct field)
   257  // followed by a one-line summary of each of the first-level items "under"
   258  // that item (package-level declarations for a package, methods for a type,
   259  // etc.).
   260  //
   261  // Doc accepts zero, one, or two arguments.
   262  //
   263  // Given no arguments, that is, when run as
   264  //
   265  // 	go doc
   266  //
   267  // it prints the package documentation for the package in the current directory.
   268  // If the package is a command (package main), the exported symbols of the package
   269  // are elided from the presentation unless the -cmd flag is provided.
   270  //
   271  // When run with one argument, the argument is treated as a Go-syntax-like
   272  // representation of the item to be documented. What the argument selects depends
   273  // on what is installed in GOROOT and GOPATH, as well as the form of the argument,
   274  // which is schematically one of these:
   275  //
   276  // 	go doc <pkg>
   277  // 	go doc <sym>[.<methodOrField>]
   278  // 	go doc [<pkg>.]<sym>[.<methodOrField>]
   279  // 	go doc [<pkg>.][<sym>.]<methodOrField>
   280  //
   281  // The first item in this list matched by the argument is the one whose documentation
   282  // is printed. (See the examples below.) However, if the argument starts with a capital
   283  // letter it is assumed to identify a symbol or method in the current directory.
   284  //
   285  // For packages, the order of scanning is determined lexically in breadth-first order.
   286  // That is, the package presented is the one that matches the search and is nearest
   287  // the root and lexically first at its level of the hierarchy. The GOROOT tree is
   288  // always scanned in its entirety before GOPATH.
   289  //
   290  // If there is no package specified or matched, the package in the current
   291  // directory is selected, so "go doc Foo" shows the documentation for symbol Foo in
   292  // the current package.
   293  //
   294  // The package path must be either a qualified path or a proper suffix of a
   295  // path. The go tool's usual package mechanism does not apply: package path
   296  // elements like . and ... are not implemented by go doc.
   297  //
   298  // When run with two arguments, the first must be a full package path (not just a
   299  // suffix), and the second is a symbol, or symbol with method or struct field.
   300  // This is similar to the syntax accepted by godoc:
   301  //
   302  // 	go doc <pkg> <sym>[.<methodOrField>]
   303  //
   304  // In all forms, when matching symbols, lower-case letters in the argument match
   305  // either case but upper-case letters match exactly. This means that there may be
   306  // multiple matches of a lower-case argument in a package if different symbols have
   307  // different cases. If this occurs, documentation for all matches is printed.
   308  //
   309  // Examples:
   310  // 	go doc
   311  // 		Show documentation for current package.
   312  // 	go doc Foo
   313  // 		Show documentation for Foo in the current package.
   314  // 		(Foo starts with a capital letter so it cannot match
   315  // 		a package path.)
   316  // 	go doc encoding/json
   317  // 		Show documentation for the encoding/json package.
   318  // 	go doc json
   319  // 		Shorthand for encoding/json.
   320  // 	go doc json.Number (or go doc json.number)
   321  // 		Show documentation and method summary for json.Number.
   322  // 	go doc json.Number.Int64 (or go doc json.number.int64)
   323  // 		Show documentation for json.Number's Int64 method.
   324  // 	go doc cmd/doc
   325  // 		Show package docs for the doc command.
   326  // 	go doc -cmd cmd/doc
   327  // 		Show package docs and exported symbols within the doc command.
   328  // 	go doc template.new
   329  // 		Show documentation for html/template's New function.
   330  // 		(html/template is lexically before text/template)
   331  // 	go doc text/template.new # One argument
   332  // 		Show documentation for text/template's New function.
   333  // 	go doc text/template new # Two arguments
   334  // 		Show documentation for text/template's New function.
   335  //
   336  // 	At least in the current tree, these invocations all print the
   337  // 	documentation for json.Decoder's Decode method:
   338  //
   339  // 	go doc json.Decoder.Decode
   340  // 	go doc json.decoder.decode
   341  // 	go doc json.decode
   342  // 	cd go/src/encoding/json; go doc decode
   343  //
   344  // Flags:
   345  // 	-c
   346  // 		Respect case when matching symbols.
   347  // 	-cmd
   348  // 		Treat a command (package main) like a regular package.
   349  // 		Otherwise package main's exported symbols are hidden
   350  // 		when showing the package's top-level documentation.
   351  // 	-u
   352  // 		Show documentation for unexported as well as exported
   353  // 		symbols, methods, and fields.
   354  //
   355  //
   356  // Print Go environment information
   357  //
   358  // Usage:
   359  //
   360  // 	go env [-json] [var ...]
   361  //
   362  // Env prints Go environment information.
   363  //
   364  // By default env prints information as a shell script
   365  // (on Windows, a batch file). If one or more variable
   366  // names is given as arguments, env prints the value of
   367  // each named variable on its own line.
   368  //
   369  // The -json flag prints the environment in JSON format
   370  // instead of as a shell script.
   371  //
   372  // For more about environment variables, see 'go help environment'.
   373  //
   374  //
   375  // Update packages to use new APIs
   376  //
   377  // Usage:
   378  //
   379  // 	go fix [packages]
   380  //
   381  // Fix runs the Go fix command on the packages named by the import paths.
   382  //
   383  // For more about fix, see 'go doc cmd/fix'.
   384  // For more about specifying packages, see 'go help packages'.
   385  //
   386  // To run fix with specific options, run 'go tool fix'.
   387  //
   388  // See also: go fmt, go vet.
   389  //
   390  //
   391  // Gofmt (reformat) package sources
   392  //
   393  // Usage:
   394  //
   395  // 	go fmt [-n] [-x] [packages]
   396  //
   397  // Fmt runs the command 'gofmt -l -w' on the packages named
   398  // by the import paths. It prints the names of the files that are modified.
   399  //
   400  // For more about gofmt, see 'go doc cmd/gofmt'.
   401  // For more about specifying packages, see 'go help packages'.
   402  //
   403  // The -n flag prints commands that would be executed.
   404  // The -x flag prints commands as they are executed.
   405  //
   406  // To run gofmt with specific options, run gofmt itself.
   407  //
   408  // See also: go fix, go vet.
   409  //
   410  //
   411  // Generate Go files by processing source
   412  //
   413  // Usage:
   414  //
   415  // 	go generate [-run regexp] [-n] [-v] [-x] [build flags] [file.go... | packages]
   416  //
   417  // Generate runs commands described by directives within existing
   418  // files. Those commands can run any process but the intent is to
   419  // create or update Go source files.
   420  //
   421  // Go generate is never run automatically by go build, go get, go test,
   422  // and so on. It must be run explicitly.
   423  //
   424  // Go generate scans the file for directives, which are lines of
   425  // the form,
   426  //
   427  // 	//go:generate command argument...
   428  //
   429  // (note: no leading spaces and no space in "//go") where command
   430  // is the generator to be run, corresponding to an executable file
   431  // that can be run locally. It must either be in the shell path
   432  // (gofmt), a fully qualified path (/usr/you/bin/mytool), or a
   433  // command alias, described below.
   434  //
   435  // To convey to humans and machine tools that code is generated,
   436  // generated source should have a line early in the file that
   437  // matches the following regular expression (in Go syntax):
   438  //
   439  // 	^// Code generated .* DO NOT EDIT\.$
   440  //
   441  // Note that go generate does not parse the file, so lines that look
   442  // like directives in comments or multiline strings will be treated
   443  // as directives.
   444  //
   445  // The arguments to the directive are space-separated tokens or
   446  // double-quoted strings passed to the generator as individual
   447  // arguments when it is run.
   448  //
   449  // Quoted strings use Go syntax and are evaluated before execution; a
   450  // quoted string appears as a single argument to the generator.
   451  //
   452  // Go generate sets several variables when it runs the generator:
   453  //
   454  // 	$GOARCH
   455  // 		The execution architecture (arm, amd64, etc.)
   456  // 	$GOOS
   457  // 		The execution operating system (linux, windows, etc.)
   458  // 	$GOFILE
   459  // 		The base name of the file.
   460  // 	$GOLINE
   461  // 		The line number of the directive in the source file.
   462  // 	$GOPACKAGE
   463  // 		The name of the package of the file containing the directive.
   464  // 	$DOLLAR
   465  // 		A dollar sign.
   466  //
   467  // Other than variable substitution and quoted-string evaluation, no
   468  // special processing such as "globbing" is performed on the command
   469  // line.
   470  //
   471  // As a last step before running the command, any invocations of any
   472  // environment variables with alphanumeric names, such as $GOFILE or
   473  // $HOME, are expanded throughout the command line. The syntax for
   474  // variable expansion is $NAME on all operating systems. Due to the
   475  // order of evaluation, variables are expanded even inside quoted
   476  // strings. If the variable NAME is not set, $NAME expands to the
   477  // empty string.
   478  //
   479  // A directive of the form,
   480  //
   481  // 	//go:generate -command xxx args...
   482  //
   483  // specifies, for the remainder of this source file only, that the
   484  // string xxx represents the command identified by the arguments. This
   485  // can be used to create aliases or to handle multiword generators.
   486  // For example,
   487  //
   488  // 	//go:generate -command foo go tool foo
   489  //
   490  // specifies that the command "foo" represents the generator
   491  // "go tool foo".
   492  //
   493  // Generate processes packages in the order given on the command line,
   494  // one at a time. If the command line lists .go files, they are treated
   495  // as a single package. Within a package, generate processes the
   496  // source files in a package in file name order, one at a time. Within
   497  // a source file, generate runs generators in the order they appear
   498  // in the file, one at a time.
   499  //
   500  // If any generator returns an error exit status, "go generate" skips
   501  // all further processing for that package.
   502  //
   503  // The generator is run in the package's source directory.
   504  //
   505  // Go generate accepts one specific flag:
   506  //
   507  // 	-run=""
   508  // 		if non-empty, specifies a regular expression to select
   509  // 		directives whose full original source text (excluding
   510  // 		any trailing spaces and final newline) matches the
   511  // 		expression.
   512  //
   513  // It also accepts the standard build flags including -v, -n, and -x.
   514  // The -v flag prints the names of packages and files as they are
   515  // processed.
   516  // The -n flag prints commands that would be executed.
   517  // The -x flag prints commands as they are executed.
   518  //
   519  // For more about build flags, see 'go help build'.
   520  //
   521  // For more about specifying packages, see 'go help packages'.
   522  //
   523  //
   524  // Download and install packages and dependencies
   525  //
   526  // Usage:
   527  //
   528  // 	go get [-d] [-f] [-t] [-u] [-v] [-fix] [-insecure] [build flags] [packages]
   529  //
   530  // Get downloads the packages named by the import paths, along with their
   531  // dependencies. It then installs the named packages, like 'go install'.
   532  //
   533  // The -d flag instructs get to stop after downloading the packages; that is,
   534  // it instructs get not to install the packages.
   535  //
   536  // The -f flag, valid only when -u is set, forces get -u not to verify that
   537  // each package has been checked out from the source control repository
   538  // implied by its import path. This can be useful if the source is a local fork
   539  // of the original.
   540  //
   541  // The -fix flag instructs get to run the fix tool on the downloaded packages
   542  // before resolving dependencies or building the code.
   543  //
   544  // The -insecure flag permits fetching from repositories and resolving
   545  // custom domains using insecure schemes such as HTTP. Use with caution.
   546  //
   547  // The -t flag instructs get to also download the packages required to build
   548  // the tests for the specified packages.
   549  //
   550  // The -u flag instructs get to use the network to update the named packages
   551  // and their dependencies. By default, get uses the network to check out
   552  // missing packages but does not use it to look for updates to existing packages.
   553  //
   554  // The -v flag enables verbose progress and debug output.
   555  //
   556  // Get also accepts build flags to control the installation. See 'go help build'.
   557  //
   558  // When checking out a new package, get creates the target directory
   559  // GOPATH/src/<import-path>. If the GOPATH contains multiple entries,
   560  // get uses the first one. For more details see: 'go help gopath'.
   561  //
   562  // When checking out or updating a package, get looks for a branch or tag
   563  // that matches the locally installed version of Go. The most important
   564  // rule is that if the local installation is running version "go1", get
   565  // searches for a branch or tag named "go1". If no such version exists
   566  // it retrieves the default branch of the package.
   567  //
   568  // When go get checks out or updates a Git repository,
   569  // it also updates any git submodules referenced by the repository.
   570  //
   571  // Get never checks out or updates code stored in vendor directories.
   572  //
   573  // For more about specifying packages, see 'go help packages'.
   574  //
   575  // For more about how 'go get' finds source code to
   576  // download, see 'go help importpath'.
   577  //
   578  // This text describes the behavior of get when using GOPATH
   579  // to manage source code and dependencies.
   580  // If instead the go command is running in module-aware mode,
   581  // the details of get's flags and effects change, as does 'go help get'.
   582  // See 'go help modules' and 'go help module-get'.
   583  //
   584  // See also: go build, go install, go clean.
   585  //
   586  //
   587  // Compile and install packages and dependencies
   588  //
   589  // Usage:
   590  //
   591  // 	go install [-i] [build flags] [packages]
   592  //
   593  // Install compiles and installs the packages named by the import paths.
   594  //
   595  // The -i flag installs the dependencies of the named packages as well.
   596  //
   597  // For more about the build flags, see 'go help build'.
   598  // For more about specifying packages, see 'go help packages'.
   599  //
   600  // See also: go build, go get, go clean.
   601  //
   602  //
   603  // List packages or modules
   604  //
   605  // Usage:
   606  //
   607  // 	go list [-f format] [-json] [-m] [list flags] [build flags] [packages]
   608  //
   609  // List lists the named packages, one per line.
   610  // The most commonly-used flags are -f and -json, which control the form
   611  // of the output printed for each package. Other list flags, documented below,
   612  // control more specific details.
   613  //
   614  // The default output shows the package import path:
   615  //
   616  //     bytes
   617  //     encoding/json
   618  //     github.com/gorilla/mux
   619  //     golang.org/x/net/html
   620  //
   621  // The -f flag specifies an alternate format for the list, using the
   622  // syntax of package template. The default output is equivalent
   623  // to -f '{{.ImportPath}}'. The struct being passed to the template is:
   624  //
   625  //     type Package struct {
   626  //         Dir           string   // directory containing package sources
   627  //         ImportPath    string   // import path of package in dir
   628  //         ImportComment string   // path in import comment on package statement
   629  //         Name          string   // package name
   630  //         Doc           string   // package documentation string
   631  //         Target        string   // install path
   632  //         Shlib         string   // the shared library that contains this package (only set when -linkshared)
   633  //         Goroot        bool     // is this package in the Go root?
   634  //         Standard      bool     // is this package part of the standard Go library?
   635  //         Stale         bool     // would 'go install' do anything for this package?
   636  //         StaleReason   string   // explanation for Stale==true
   637  //         Root          string   // Go root or Go path dir containing this package
   638  //         ConflictDir   string   // this directory shadows Dir in $GOPATH
   639  //         BinaryOnly    bool     // binary-only package: cannot be recompiled from sources
   640  //         ForTest       string   // package is only for use in named test
   641  //         Export        string   // file containing export data (when using -export)
   642  //         Module        *Module  // info about package's containing module, if any (can be nil)
   643  //         Match         []string // command-line patterns matching this package
   644  //         DepOnly       bool     // package is only a dependency, not explicitly listed
   645  //
   646  //         // Source files
   647  //         GoFiles         []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles)
   648  //         CgoFiles        []string // .go source files that import "C"
   649  //         CompiledGoFiles []string // .go files presented to compiler (when using -compiled)
   650  //         IgnoredGoFiles  []string // .go source files ignored due to build constraints
   651  //         CFiles          []string // .c source files
   652  //         CXXFiles        []string // .cc, .cxx and .cpp source files
   653  //         MFiles          []string // .m source files
   654  //         HFiles          []string // .h, .hh, .hpp and .hxx source files
   655  //         FFiles          []string // .f, .F, .for and .f90 Fortran source files
   656  //         SFiles          []string // .s source files
   657  //         SwigFiles       []string // .swig files
   658  //         SwigCXXFiles    []string // .swigcxx files
   659  //         SysoFiles       []string // .syso object files to add to archive
   660  //         TestGoFiles     []string // _test.go files in package
   661  //         XTestGoFiles    []string // _test.go files outside package
   662  //
   663  //         // Cgo directives
   664  //         CgoCFLAGS    []string // cgo: flags for C compiler
   665  //         CgoCPPFLAGS  []string // cgo: flags for C preprocessor
   666  //         CgoCXXFLAGS  []string // cgo: flags for C++ compiler
   667  //         CgoFFLAGS    []string // cgo: flags for Fortran compiler
   668  //         CgoLDFLAGS   []string // cgo: flags for linker
   669  //         CgoPkgConfig []string // cgo: pkg-config names
   670  //
   671  //         // Dependency information
   672  //         Imports      []string          // import paths used by this package
   673  //         ImportMap    map[string]string // map from source import to ImportPath (identity entries omitted)
   674  //         Deps         []string          // all (recursively) imported dependencies
   675  //         TestImports  []string          // imports from TestGoFiles
   676  //         XTestImports []string          // imports from XTestGoFiles
   677  //
   678  //         // Error information
   679  //         Incomplete bool            // this package or a dependency has an error
   680  //         Error      *PackageError   // error loading package
   681  //         DepsErrors []*PackageError // errors loading dependencies
   682  //     }
   683  //
   684  // Packages stored in vendor directories report an ImportPath that includes the
   685  // path to the vendor directory (for example, "d/vendor/p" instead of "p"),
   686  // so that the ImportPath uniquely identifies a given copy of a package.
   687  // The Imports, Deps, TestImports, and XTestImports lists also contain these
   688  // expanded import paths. See golang.org/s/go15vendor for more about vendoring.
   689  //
   690  // The error information, if any, is
   691  //
   692  //     type PackageError struct {
   693  //         ImportStack   []string // shortest path from package named on command line to this one
   694  //         Pos           string   // position of error (if present, file:line:col)
   695  //         Err           string   // the error itself
   696  //     }
   697  //
   698  // The module information is a Module struct, defined in the discussion
   699  // of list -m below.
   700  //
   701  // The template function "join" calls strings.Join.
   702  //
   703  // The template function "context" returns the build context, defined as:
   704  //
   705  //     type Context struct {
   706  //         GOARCH        string   // target architecture
   707  //         GOOS          string   // target operating system
   708  //         GOROOT        string   // Go root
   709  //         GOPATH        string   // Go path
   710  //         CgoEnabled    bool     // whether cgo can be used
   711  //         UseAllFiles   bool     // use files regardless of +build lines, file names
   712  //         Compiler      string   // compiler to assume when computing target paths
   713  //         BuildTags     []string // build constraints to match in +build lines
   714  //         ReleaseTags   []string // releases the current release is compatible with
   715  //         InstallSuffix string   // suffix to use in the name of the install dir
   716  //     }
   717  //
   718  // For more information about the meaning of these fields see the documentation
   719  // for the go/build package's Context type.
   720  //
   721  // The -json flag causes the package data to be printed in JSON format
   722  // instead of using the template format.
   723  //
   724  // The -compiled flag causes list to set CompiledGoFiles to the Go source
   725  // files presented to the compiler. Typically this means that it repeats
   726  // the files listed in GoFiles and then also adds the Go code generated
   727  // by processing CgoFiles and SwigFiles. The Imports list contains the
   728  // union of all imports from both GoFiles and CompiledGoFiles.
   729  //
   730  // The -deps flag causes list to iterate over not just the named packages
   731  // but also all their dependencies. It visits them in a depth-first post-order
   732  // traversal, so that a package is listed only after all its dependencies.
   733  // Packages not explicitly listed on the command line will have the DepOnly
   734  // field set to true.
   735  //
   736  // The -e flag changes the handling of erroneous packages, those that
   737  // cannot be found or are malformed. By default, the list command
   738  // prints an error to standard error for each erroneous package and
   739  // omits the packages from consideration during the usual printing.
   740  // With the -e flag, the list command never prints errors to standard
   741  // error and instead processes the erroneous packages with the usual
   742  // printing. Erroneous packages will have a non-empty ImportPath and
   743  // a non-nil Error field; other information may or may not be missing
   744  // (zeroed).
   745  //
   746  // The -export flag causes list to set the Export field to the name of a
   747  // file containing up-to-date export information for the given package.
   748  //
   749  // The -find flag causes list to identify the named packages but not
   750  // resolve their dependencies: the Imports and Deps lists will be empty.
   751  //
   752  // The -test flag causes list to report not only the named packages
   753  // but also their test binaries (for packages with tests), to convey to
   754  // source code analysis tools exactly how test binaries are constructed.
   755  // The reported import path for a test binary is the import path of
   756  // the package followed by a ".test" suffix, as in "math/rand.test".
   757  // When building a test, it is sometimes necessary to rebuild certain
   758  // dependencies specially for that test (most commonly the tested
   759  // package itself). The reported import path of a package recompiled
   760  // for a particular test binary is followed by a space and the name of
   761  // the test binary in brackets, as in "math/rand [math/rand.test]"
   762  // or "regexp [sort.test]". The ForTest field is also set to the name
   763  // of the package being tested ("math/rand" or "sort" in the previous
   764  // examples).
   765  //
   766  // The Dir, Target, Shlib, Root, ConflictDir, and Export file paths
   767  // are all absolute paths.
   768  //
   769  // By default, the lists GoFiles, CgoFiles, and so on hold names of files in Dir
   770  // (that is, paths relative to Dir, not absolute paths).
   771  // The generated files added when using the -compiled and -test flags
   772  // are absolute paths referring to cached copies of generated Go source files.
   773  // Although they are Go source files, the paths may not end in ".go".
   774  //
   775  // The -m flag causes list to list modules instead of packages.
   776  //
   777  // When listing modules, the -f flag still specifies a format template
   778  // applied to a Go struct, but now a Module struct:
   779  //
   780  //     type Module struct {
   781  //         Path     string       // module path
   782  //         Version  string       // module version
   783  //         Versions []string     // available module versions (with -versions)
   784  //         Replace  *Module      // replaced by this module
   785  //         Time     *time.Time   // time version was created
   786  //         Update   *Module      // available update, if any (with -u)
   787  //         Main     bool         // is this the main module?
   788  //         Indirect bool         // is this module only an indirect dependency of main module?
   789  //         Dir      string       // directory holding files for this module, if any
   790  //         GoMod    string       // path to go.mod file for this module, if any
   791  //         Error    *ModuleError // error loading module
   792  //     }
   793  //
   794  //     type ModuleError struct {
   795  //         Err string // the error itself
   796  //     }
   797  //
   798  // The default output is to print the module path and then
   799  // information about the version and replacement if any.
   800  // For example, 'go list -m all' might print:
   801  //
   802  //     my/main/module
   803  //     golang.org/x/text v0.3.0 => /tmp/text
   804  //     rsc.io/pdf v0.1.1
   805  //
   806  // The Module struct has a String method that formats this
   807  // line of output, so that the default format is equivalent
   808  // to -f '{{.String}}'.
   809  //
   810  // Note that when a module has been replaced, its Replace field
   811  // describes the replacement module, and its Dir field is set to
   812  // the replacement's source code, if present. (That is, if Replace
   813  // is non-nil, then Dir is set to Replace.Dir, with no access to
   814  // the replaced source code.)
   815  //
   816  // The -u flag adds information about available upgrades.
   817  // When the latest version of a given module is newer than
   818  // the current one, list -u sets the Module's Update field
   819  // to information about the newer module.
   820  // The Module's String method indicates an available upgrade by
   821  // formatting the newer version in brackets after the current version.
   822  // For example, 'go list -m -u all' might print:
   823  //
   824  //     my/main/module
   825  //     golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text
   826  //     rsc.io/pdf v0.1.1 [v0.1.2]
   827  //
   828  // (For tools, 'go list -m -u -json all' may be more convenient to parse.)
   829  //
   830  // The -versions flag causes list to set the Module's Versions field
   831  // to a list of all known versions of that module, ordered according
   832  // to semantic versioning, earliest to latest. The flag also changes
   833  // the default output format to display the module path followed by the
   834  // space-separated version list.
   835  //
   836  // The arguments to list -m are interpreted as a list of modules, not packages.
   837  // The main module is the module containing the current directory.
   838  // The active modules are the main module and its dependencies.
   839  // With no arguments, list -m shows the main module.
   840  // With arguments, list -m shows the modules specified by the arguments.
   841  // Any of the active modules can be specified by its module path.
   842  // The special pattern "all" specifies all the active modules, first the main
   843  // module and then dependencies sorted by module path.
   844  // A pattern containing "..." specifies the active modules whose
   845  // module paths match the pattern.
   846  // A query of the form path@version specifies the result of that query,
   847  // which is not limited to active modules.
   848  // See 'go help modules' for more about module queries.
   849  //
   850  // The template function "module" takes a single string argument
   851  // that must be a module path or query and returns the specified
   852  // module as a Module struct. If an error occurs, the result will
   853  // be a Module struct with a non-nil Error field.
   854  //
   855  // For more about build flags, see 'go help build'.
   856  //
   857  // For more about specifying packages, see 'go help packages'.
   858  //
   859  // For more about modules, see 'go help modules'.
   860  //
   861  //
   862  // Module maintenance
   863  //
   864  // Go mod provides access to operations on modules.
   865  //
   866  // Note that support for modules is built into all the go commands,
   867  // not just 'go mod'. For example, day-to-day adding, removing, upgrading,
   868  // and downgrading of dependencies should be done using 'go get'.
   869  // See 'go help modules' for an overview of module functionality.
   870  //
   871  // Usage:
   872  //
   873  // 	go mod <command> [arguments]
   874  //
   875  // The commands are:
   876  //
   877  // 	download    download modules to local cache
   878  // 	edit        edit go.mod from tools or scripts
   879  // 	graph       print module requirement graph
   880  // 	init        initialize new module in current directory
   881  // 	tidy        add missing and remove unused modules
   882  // 	vendor      make vendored copy of dependencies
   883  // 	verify      verify dependencies have expected content
   884  // 	why         explain why packages or modules are needed
   885  //
   886  // Use "go help mod <command>" for more information about a command.
   887  //
   888  // Download modules to local cache
   889  //
   890  // Usage:
   891  //
   892  // 	go mod download [-json] [modules]
   893  //
   894  // Download downloads the named modules, which can be module patterns selecting
   895  // dependencies of the main module or module queries of the form path@version.
   896  // With no arguments, download applies to all dependencies of the main module.
   897  //
   898  // The go command will automatically download modules as needed during ordinary
   899  // execution. The "go mod download" command is useful mainly for pre-filling
   900  // the local cache or to compute the answers for a Go module proxy.
   901  //
   902  // By default, download reports errors to standard error but is otherwise silent.
   903  // The -json flag causes download to print a sequence of JSON objects
   904  // to standard output, describing each downloaded module (or failure),
   905  // corresponding to this Go struct:
   906  //
   907  //     type Module struct {
   908  //         Path     string // module path
   909  //         Version  string // module version
   910  //         Error    string // error loading module
   911  //         Info     string // absolute path to cached .info file
   912  //         GoMod    string // absolute path to cached .mod file
   913  //         Zip      string // absolute path to cached .zip file
   914  //         Dir      string // absolute path to cached source root directory
   915  //         Sum      string // checksum for path, version (as in go.sum)
   916  //         GoModSum string // checksum for go.mod (as in go.sum)
   917  //     }
   918  //
   919  // See 'go help modules' for more about module queries.
   920  //
   921  //
   922  // Edit go.mod from tools or scripts
   923  //
   924  // Usage:
   925  //
   926  // 	go mod edit [editing flags] [go.mod]
   927  //
   928  // Edit provides a command-line interface for editing go.mod,
   929  // for use primarily by tools or scripts. It reads only go.mod;
   930  // it does not look up information about the modules involved.
   931  // By default, edit reads and writes the go.mod file of the main module,
   932  // but a different target file can be specified after the editing flags.
   933  //
   934  // The editing flags specify a sequence of editing operations.
   935  //
   936  // The -fmt flag reformats the go.mod file without making other changes.
   937  // This reformatting is also implied by any other modifications that use or
   938  // rewrite the go.mod file. The only time this flag is needed is if no other
   939  // flags are specified, as in 'go mod edit -fmt'.
   940  //
   941  // The -module flag changes the module's path (the go.mod file's module line).
   942  //
   943  // The -require=path@version and -droprequire=path flags
   944  // add and drop a requirement on the given module path and version.
   945  // Note that -require overrides any existing requirements on path.
   946  // These flags are mainly for tools that understand the module graph.
   947  // Users should prefer 'go get path@version' or 'go get path@none',
   948  // which make other go.mod adjustments as needed to satisfy
   949  // constraints imposed by other modules.
   950  //
   951  // The -exclude=path@version and -dropexclude=path@version flags
   952  // add and drop an exclusion for the given module path and version.
   953  // Note that -exclude=path@version is a no-op if that exclusion already exists.
   954  //
   955  // The -replace=old[@v]=new[@v] and -dropreplace=old[@v] flags
   956  // add and drop a replacement of the given module path and version pair.
   957  // If the @v in old@v is omitted, the replacement applies to all versions
   958  // with the old module path. If the @v in new@v is omitted, the new path
   959  // should be a local module root directory, not a module path.
   960  // Note that -replace overrides any existing replacements for old[@v].
   961  //
   962  // The -require, -droprequire, -exclude, -dropexclude, -replace,
   963  // and -dropreplace editing flags may be repeated, and the changes
   964  // are applied in the order given.
   965  //
   966  // The -print flag prints the final go.mod in its text format instead of
   967  // writing it back to go.mod.
   968  //
   969  // The -json flag prints the final go.mod file in JSON format instead of
   970  // writing it back to go.mod. The JSON output corresponds to these Go types:
   971  //
   972  // 	type Module struct {
   973  // 		Path string
   974  // 		Version string
   975  // 	}
   976  //
   977  // 	type GoMod struct {
   978  // 		Module Module
   979  // 		Require []Require
   980  // 		Exclude []Module
   981  // 		Replace []Replace
   982  // 	}
   983  //
   984  // 	type Require struct {
   985  // 		Path string
   986  // 		Version string
   987  // 		Indirect bool
   988  // 	}
   989  //
   990  // 	type Replace struct {
   991  // 		Old Module
   992  // 		New Module
   993  // 	}
   994  //
   995  // Note that this only describes the go.mod file itself, not other modules
   996  // referred to indirectly. For the full set of modules available to a build,
   997  // use 'go list -m -json all'.
   998  //
   999  // For example, a tool can obtain the go.mod as a data structure by
  1000  // parsing the output of 'go mod edit -json' and can then make changes
  1001  // by invoking 'go mod edit' with -require, -exclude, and so on.
  1002  //
  1003  //
  1004  // Print module requirement graph
  1005  //
  1006  // Usage:
  1007  //
  1008  // 	go mod graph
  1009  //
  1010  // Graph prints the module requirement graph (with replacements applied)
  1011  // in text form. Each line in the output has two space-separated fields: a module
  1012  // and one of its requirements. Each module is identified as a string of the form
  1013  // path@version, except for the main module, which has no @version suffix.
  1014  //
  1015  //
  1016  // Initialize new module in current directory
  1017  //
  1018  // Usage:
  1019  //
  1020  // 	go mod init [module]
  1021  //
  1022  // Init initializes and writes a new go.mod to the current directory,
  1023  // in effect creating a new module rooted at the current directory.
  1024  // The file go.mod must not already exist.
  1025  // If possible, init will guess the module path from import comments
  1026  // (see 'go help importpath') or from version control configuration.
  1027  // To override this guess, supply the module path as an argument.
  1028  //
  1029  //
  1030  // Add missing and remove unused modules
  1031  //
  1032  // Usage:
  1033  //
  1034  // 	go mod tidy [-v]
  1035  //
  1036  // Tidy makes sure go.mod matches the source code in the module.
  1037  // It adds any missing modules necessary to build the current module's
  1038  // packages and dependencies, and it removes unused modules that
  1039  // don't provide any relevant packages. It also adds any missing entries
  1040  // to go.sum and removes any unnecessary ones.
  1041  //
  1042  // The -v flag causes tidy to print information about removed modules
  1043  // to standard error.
  1044  //
  1045  //
  1046  // Make vendored copy of dependencies
  1047  //
  1048  // Usage:
  1049  //
  1050  // 	go mod vendor [-v]
  1051  //
  1052  // Vendor resets the main module's vendor directory to include all packages
  1053  // needed to build and test all the main module's packages.
  1054  // It does not include test code for vendored packages.
  1055  //
  1056  // The -v flag causes vendor to print the names of vendored
  1057  // modules and packages to standard error.
  1058  //
  1059  //
  1060  // Verify dependencies have expected content
  1061  //
  1062  // Usage:
  1063  //
  1064  // 	go mod verify
  1065  //
  1066  // Verify checks that the dependencies of the current module,
  1067  // which are stored in a local downloaded source cache, have not been
  1068  // modified since being downloaded. If all the modules are unmodified,
  1069  // verify prints "all modules verified." Otherwise it reports which
  1070  // modules have been changed and causes 'go mod' to exit with a
  1071  // non-zero status.
  1072  //
  1073  //
  1074  // Explain why packages or modules are needed
  1075  //
  1076  // Usage:
  1077  //
  1078  // 	go mod why [-m] [-vendor] packages...
  1079  //
  1080  // Why shows a shortest path in the import graph from the main module to
  1081  // each of the listed packages. If the -m flag is given, why treats the
  1082  // arguments as a list of modules and finds a path to any package in each
  1083  // of the modules.
  1084  //
  1085  // By default, why queries the graph of packages matched by "go list all",
  1086  // which includes tests for reachable packages. The -vendor flag causes why
  1087  // to exclude tests of dependencies.
  1088  //
  1089  // The output is a sequence of stanzas, one for each package or module
  1090  // name on the command line, separated by blank lines. Each stanza begins
  1091  // with a comment line "# package" or "# module" giving the target
  1092  // package or module. Subsequent lines give a path through the import
  1093  // graph, one package per line. If the package or module is not
  1094  // referenced from the main module, the stanza will display a single
  1095  // parenthesized note indicating that fact.
  1096  //
  1097  // For example:
  1098  //
  1099  // 	$ go mod why golang.org/x/text/language golang.org/x/text/encoding
  1100  // 	# golang.org/x/text/language
  1101  // 	rsc.io/quote
  1102  // 	rsc.io/sampler
  1103  // 	golang.org/x/text/language
  1104  //
  1105  // 	# golang.org/x/text/encoding
  1106  // 	(main module does not need package golang.org/x/text/encoding)
  1107  // 	$
  1108  //
  1109  //
  1110  // Compile and run Go program
  1111  //
  1112  // Usage:
  1113  //
  1114  // 	go run [build flags] [-exec xprog] package [arguments...]
  1115  //
  1116  // Run compiles and runs the named main Go package.
  1117  // Typically the package is specified as a list of .go source files,
  1118  // but it may also be an import path, file system path, or pattern
  1119  // matching a single known package, as in 'go run .' or 'go run my/cmd'.
  1120  //
  1121  // By default, 'go run' runs the compiled binary directly: 'a.out arguments...'.
  1122  // If the -exec flag is given, 'go run' invokes the binary using xprog:
  1123  // 	'xprog a.out arguments...'.
  1124  // If the -exec flag is not given, GOOS or GOARCH is different from the system
  1125  // default, and a program named go_$GOOS_$GOARCH_exec can be found
  1126  // on the current search path, 'go run' invokes the binary using that program,
  1127  // for example 'go_nacl_386_exec a.out arguments...'. This allows execution of
  1128  // cross-compiled programs when a simulator or other execution method is
  1129  // available.
  1130  //
  1131  // The exit status of Run is not the exit status of the compiled binary.
  1132  //
  1133  // For more about build flags, see 'go help build'.
  1134  // For more about specifying packages, see 'go help packages'.
  1135  //
  1136  // See also: go build.
  1137  //
  1138  //
  1139  // Test packages
  1140  //
  1141  // Usage:
  1142  //
  1143  // 	go test [build/test flags] [packages] [build/test flags & test binary flags]
  1144  //
  1145  // 'Go test' automates testing the packages named by the import paths.
  1146  // It prints a summary of the test results in the format:
  1147  //
  1148  // 	ok   archive/tar   0.011s
  1149  // 	FAIL archive/zip   0.022s
  1150  // 	ok   compress/gzip 0.033s
  1151  // 	...
  1152  //
  1153  // followed by detailed output for each failed package.
  1154  //
  1155  // 'Go test' recompiles each package along with any files with names matching
  1156  // the file pattern "*_test.go".
  1157  // These additional files can contain test functions, benchmark functions, and
  1158  // example functions. See 'go help testfunc' for more.
  1159  // Each listed package causes the execution of a separate test binary.
  1160  // Files whose names begin with "_" (including "_test.go") or "." are ignored.
  1161  //
  1162  // Test files that declare a package with the suffix "_test" will be compiled as a
  1163  // separate package, and then linked and run with the main test binary.
  1164  //
  1165  // The go tool will ignore a directory named "testdata", making it available
  1166  // to hold ancillary data needed by the tests.
  1167  //
  1168  // As part of building a test binary, go test runs go vet on the package
  1169  // and its test source files to identify significant problems. If go vet
  1170  // finds any problems, go test reports those and does not run the test
  1171  // binary. Only a high-confidence subset of the default go vet checks are
  1172  // used. That subset is: 'atomic', 'bool', 'buildtags', 'nilfunc', and
  1173  // 'printf'. You can see the documentation for these and other vet tests
  1174  // via "go doc cmd/vet". To disable the running of go vet, use the
  1175  // -vet=off flag.
  1176  //
  1177  // All test output and summary lines are printed to the go command's
  1178  // standard output, even if the test printed them to its own standard
  1179  // error. (The go command's standard error is reserved for printing
  1180  // errors building the tests.)
  1181  //
  1182  // Go test runs in two different modes:
  1183  //
  1184  // The first, called local directory mode, occurs when go test is
  1185  // invoked with no package arguments (for example, 'go test' or 'go
  1186  // test -v'). In this mode, go test compiles the package sources and
  1187  // tests found in the current directory and then runs the resulting
  1188  // test binary. In this mode, caching (discussed below) is disabled.
  1189  // After the package test finishes, go test prints a summary line
  1190  // showing the test status ('ok' or 'FAIL'), package name, and elapsed
  1191  // time.
  1192  //
  1193  // The second, called package list mode, occurs when go test is invoked
  1194  // with explicit package arguments (for example 'go test math', 'go
  1195  // test ./...', and even 'go test .'). In this mode, go test compiles
  1196  // and tests each of the packages listed on the command line. If a
  1197  // package test passes, go test prints only the final 'ok' summary
  1198  // line. If a package test fails, go test prints the full test output.
  1199  // If invoked with the -bench or -v flag, go test prints the full
  1200  // output even for passing package tests, in order to display the
  1201  // requested benchmark results or verbose logging.
  1202  //
  1203  // In package list mode only, go test caches successful package test
  1204  // results to avoid unnecessary repeated running of tests. When the
  1205  // result of a test can be recovered from the cache, go test will
  1206  // redisplay the previous output instead of running the test binary
  1207  // again. When this happens, go test prints '(cached)' in place of the
  1208  // elapsed time in the summary line.
  1209  //
  1210  // The rule for a match in the cache is that the run involves the same
  1211  // test binary and the flags on the command line come entirely from a
  1212  // restricted set of 'cacheable' test flags, defined as -cpu, -list,
  1213  // -parallel, -run, -short, and -v. If a run of go test has any test
  1214  // or non-test flags outside this set, the result is not cached. To
  1215  // disable test caching, use any test flag or argument other than the
  1216  // cacheable flags. The idiomatic way to disable test caching explicitly
  1217  // is to use -count=1. Tests that open files within the package's source
  1218  // root (usually $GOPATH) or that consult environment variables only
  1219  // match future runs in which the files and environment variables are unchanged.
  1220  // A cached test result is treated as executing in no time at all,
  1221  // so a successful package test result will be cached and reused
  1222  // regardless of -timeout setting.
  1223  //
  1224  // In addition to the build flags, the flags handled by 'go test' itself are:
  1225  //
  1226  // 	-args
  1227  // 	    Pass the remainder of the command line (everything after -args)
  1228  // 	    to the test binary, uninterpreted and unchanged.
  1229  // 	    Because this flag consumes the remainder of the command line,
  1230  // 	    the package list (if present) must appear before this flag.
  1231  //
  1232  // 	-c
  1233  // 	    Compile the test binary to pkg.test but do not run it
  1234  // 	    (where pkg is the last element of the package's import path).
  1235  // 	    The file name can be changed with the -o flag.
  1236  //
  1237  // 	-exec xprog
  1238  // 	    Run the test binary using xprog. The behavior is the same as
  1239  // 	    in 'go run'. See 'go help run' for details.
  1240  //
  1241  // 	-i
  1242  // 	    Install packages that are dependencies of the test.
  1243  // 	    Do not run the test.
  1244  //
  1245  // 	-json
  1246  // 	    Convert test output to JSON suitable for automated processing.
  1247  // 	    See 'go doc test2json' for the encoding details.
  1248  //
  1249  // 	-o file
  1250  // 	    Compile the test binary to the named file.
  1251  // 	    The test still runs (unless -c or -i is specified).
  1252  //
  1253  // The test binary also accepts flags that control execution of the test; these
  1254  // flags are also accessible by 'go test'. See 'go help testflag' for details.
  1255  //
  1256  // For more about build flags, see 'go help build'.
  1257  // For more about specifying packages, see 'go help packages'.
  1258  //
  1259  // See also: go build, go vet.
  1260  //
  1261  //
  1262  // Run specified go tool
  1263  //
  1264  // Usage:
  1265  //
  1266  // 	go tool [-n] command [args...]
  1267  //
  1268  // Tool runs the go tool command identified by the arguments.
  1269  // With no arguments it prints the list of known tools.
  1270  //
  1271  // The -n flag causes tool to print the command that would be
  1272  // executed but not execute it.
  1273  //
  1274  // For more about each tool command, see 'go doc cmd/<command>'.
  1275  //
  1276  //
  1277  // Print Go version
  1278  //
  1279  // Usage:
  1280  //
  1281  // 	go version
  1282  //
  1283  // Version prints the Go version, as reported by runtime.Version.
  1284  //
  1285  //
  1286  // Report likely mistakes in packages
  1287  //
  1288  // Usage:
  1289  //
  1290  // 	go vet [-n] [-x] [build flags] [vet flags] [packages]
  1291  //
  1292  // Vet runs the Go vet command on the packages named by the import paths.
  1293  //
  1294  // For more about vet and its flags, see 'go doc cmd/vet'.
  1295  // For more about specifying packages, see 'go help packages'.
  1296  //
  1297  // The -n flag prints commands that would be executed.
  1298  // The -x flag prints commands as they are executed.
  1299  //
  1300  // The build flags supported by go vet are those that control package resolution
  1301  // and execution, such as -n, -x, -v, -tags, and -toolexec.
  1302  // For more about these flags, see 'go help build'.
  1303  //
  1304  // See also: go fmt, go fix.
  1305  //
  1306  //
  1307  // Build modes
  1308  //
  1309  // The 'go build' and 'go install' commands take a -buildmode argument which
  1310  // indicates which kind of object file is to be built. Currently supported values
  1311  // are:
  1312  //
  1313  // 	-buildmode=archive
  1314  // 		Build the listed non-main packages into .a files. Packages named
  1315  // 		main are ignored.
  1316  //
  1317  // 	-buildmode=c-archive
  1318  // 		Build the listed main package, plus all packages it imports,
  1319  // 		into a C archive file. The only callable symbols will be those
  1320  // 		functions exported using a cgo //export comment. Requires
  1321  // 		exactly one main package to be listed.
  1322  //
  1323  // 	-buildmode=c-shared
  1324  // 		Build the listed main package, plus all packages it imports,
  1325  // 		into a C shared library. The only callable symbols will
  1326  // 		be those functions exported using a cgo //export comment.
  1327  // 		Requires exactly one main package to be listed.
  1328  //
  1329  // 	-buildmode=default
  1330  // 		Listed main packages are built into executables and listed
  1331  // 		non-main packages are built into .a files (the default
  1332  // 		behavior).
  1333  //
  1334  // 	-buildmode=shared
  1335  // 		Combine all the listed non-main packages into a single shared
  1336  // 		library that will be used when building with the -linkshared
  1337  // 		option. Packages named main are ignored.
  1338  //
  1339  // 	-buildmode=exe
  1340  // 		Build the listed main packages and everything they import into
  1341  // 		executables. Packages not named main are ignored.
  1342  //
  1343  // 	-buildmode=pie
  1344  // 		Build the listed main packages and everything they import into
  1345  // 		position independent executables (PIE). Packages not named
  1346  // 		main are ignored.
  1347  //
  1348  // 	-buildmode=plugin
  1349  // 		Build the listed main packages, plus all packages that they
  1350  // 		import, into a Go plugin. Packages not named main are ignored.
  1351  //
  1352  //
  1353  // Calling between Go and C
  1354  //
  1355  // There are two different ways to call between Go and C/C++ code.
  1356  //
  1357  // The first is the cgo tool, which is part of the Go distribution. For
  1358  // information on how to use it see the cgo documentation (go doc cmd/cgo).
  1359  //
  1360  // The second is the SWIG program, which is a general tool for
  1361  // interfacing between languages. For information on SWIG see
  1362  // http://swig.org/. When running go build, any file with a .swig
  1363  // extension will be passed to SWIG. Any file with a .swigcxx extension
  1364  // will be passed to SWIG with the -c++ option.
  1365  //
  1366  // When either cgo or SWIG is used, go build will pass any .c, .m, .s,
  1367  // or .S files to the C compiler, and any .cc, .cpp, .cxx files to the C++
  1368  // compiler. The CC or CXX environment variables may be set to determine
  1369  // the C or C++ compiler, respectively, to use.
  1370  //
  1371  //
  1372  // Build and test caching
  1373  //
  1374  // The go command caches build outputs for reuse in future builds.
  1375  // The default location for cache data is a subdirectory named go-build
  1376  // in the standard user cache directory for the current operating system.
  1377  // Setting the GOCACHE environment variable overrides this default,
  1378  // and running 'go env GOCACHE' prints the current cache directory.
  1379  // You can set the variable to 'off' to disable the cache.
  1380  //
  1381  // The go command periodically deletes cached data that has not been
  1382  // used recently. Running 'go clean -cache' deletes all cached data.
  1383  //
  1384  // The build cache correctly accounts for changes to Go source files,
  1385  // compilers, compiler options, and so on: cleaning the cache explicitly
  1386  // should not be necessary in typical use. However, the build cache
  1387  // does not detect changes to C libraries imported with cgo.
  1388  // If you have made changes to the C libraries on your system, you
  1389  // will need to clean the cache explicitly or else use the -a build flag
  1390  // (see 'go help build') to force rebuilding of packages that
  1391  // depend on the updated C libraries.
  1392  //
  1393  // The go command also caches successful package test results.
  1394  // See 'go help test' for details. Running 'go clean -testcache' removes
  1395  // all cached test results (but not cached build results).
  1396  //
  1397  // The GODEBUG environment variable can enable printing of debugging
  1398  // information about the state of the cache:
  1399  //
  1400  // GODEBUG=gocacheverify=1 causes the go command to bypass the
  1401  // use of any cache entries and instead rebuild everything and check
  1402  // that the results match existing cache entries.
  1403  //
  1404  // GODEBUG=gocachehash=1 causes the go command to print the inputs
  1405  // for all of the content hashes it uses to construct cache lookup keys.
  1406  // The output is voluminous but can be useful for debugging the cache.
  1407  //
  1408  // GODEBUG=gocachetest=1 causes the go command to print details of its
  1409  // decisions about whether to reuse a cached test result.
  1410  //
  1411  //
  1412  // Environment variables
  1413  //
  1414  // The go command, and the tools it invokes, examine a few different
  1415  // environment variables. For many of these, you can see the default
  1416  // value of on your system by running 'go env NAME', where NAME is the
  1417  // name of the variable.
  1418  //
  1419  // General-purpose environment variables:
  1420  //
  1421  // 	GCCGO
  1422  // 		The gccgo command to run for 'go build -compiler=gccgo'.
  1423  // 	GOARCH
  1424  // 		The architecture, or processor, for which to compile code.
  1425  // 		Examples are amd64, 386, arm, ppc64.
  1426  // 	GOBIN
  1427  // 		The directory where 'go install' will install a command.
  1428  // 	GOCACHE
  1429  // 		The directory where the go command will store cached
  1430  // 		information for reuse in future builds.
  1431  // 	GOFLAGS
  1432  // 		A space-separated list of -flag=value settings to apply
  1433  // 		to go commands by default, when the given flag is known by
  1434  // 		the current command. Flags listed on the command-line
  1435  // 		are applied after this list and therefore override it.
  1436  // 	GOOS
  1437  // 		The operating system for which to compile code.
  1438  // 		Examples are linux, darwin, windows, netbsd.
  1439  // 	GOPATH
  1440  // 		For more details see: 'go help gopath'.
  1441  // 	GOPROXY
  1442  // 		URL of Go module proxy. See 'go help goproxy'.
  1443  // 	GORACE
  1444  // 		Options for the race detector.
  1445  // 		See https://golang.org/doc/articles/race_detector.html.
  1446  // 	GOROOT
  1447  // 		The root of the go tree.
  1448  // 	GOTMPDIR
  1449  // 		The directory where the go command will write
  1450  // 		temporary source files, packages, and binaries.
  1451  //
  1452  // Each entry in the GOFLAGS list must be a standalone flag.
  1453  // Because the entries are space-separated, flag values must
  1454  // not contain spaces. In some cases, you can provide multiple flag
  1455  // values instead: for example, to set '-ldflags=-s -w'
  1456  // you can use 'GOFLAGS=-ldflags=-s -ldflags=-w'.
  1457  //
  1458  // Environment variables for use with cgo:
  1459  //
  1460  // 	CC
  1461  // 		The command to use to compile C code.
  1462  // 	CGO_ENABLED
  1463  // 		Whether the cgo command is supported. Either 0 or 1.
  1464  // 	CGO_CFLAGS
  1465  // 		Flags that cgo will pass to the compiler when compiling
  1466  // 		C code.
  1467  // 	CGO_CFLAGS_ALLOW
  1468  // 		A regular expression specifying additional flags to allow
  1469  // 		to appear in #cgo CFLAGS source code directives.
  1470  // 		Does not apply to the CGO_CFLAGS environment variable.
  1471  // 	CGO_CFLAGS_DISALLOW
  1472  // 		A regular expression specifying flags that must be disallowed
  1473  // 		from appearing in #cgo CFLAGS source code directives.
  1474  // 		Does not apply to the CGO_CFLAGS environment variable.
  1475  // 	CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
  1476  // 		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
  1477  // 		but for the C preprocessor.
  1478  // 	CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
  1479  // 		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
  1480  // 		but for the C++ compiler.
  1481  // 	CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
  1482  // 		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
  1483  // 		but for the Fortran compiler.
  1484  // 	CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
  1485  // 		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
  1486  // 		but for the linker.
  1487  // 	CXX
  1488  // 		The command to use to compile C++ code.
  1489  // 	PKG_CONFIG
  1490  // 		Path to pkg-config tool.
  1491  //
  1492  // Architecture-specific environment variables:
  1493  //
  1494  // 	GOARM
  1495  // 		For GOARCH=arm, the ARM architecture for which to compile.
  1496  // 		Valid values are 5, 6, 7.
  1497  // 	GO386
  1498  // 		For GOARCH=386, the floating point instruction set.
  1499  // 		Valid values are 387, sse2.
  1500  // 	GOMIPS
  1501  // 		For GOARCH=mips{,le}, whether to use floating point instructions.
  1502  // 		Valid values are hardfloat (default), softfloat.
  1503  // 	GOMIPS64
  1504  // 		For GOARCH=mips64{,le}, whether to use floating point instructions.
  1505  // 		Valid values are hardfloat (default), softfloat.
  1506  //
  1507  // Special-purpose environment variables:
  1508  //
  1509  // 	GCCGOTOOLDIR
  1510  // 		If set, where to find gccgo tools, such as cgo.
  1511  // 		The default is based on how gccgo was configured.
  1512  // 	GOROOT_FINAL
  1513  // 		The root of the installed Go tree, when it is
  1514  // 		installed in a location other than where it is built.
  1515  // 		File names in stack traces are rewritten from GOROOT to
  1516  // 		GOROOT_FINAL.
  1517  // 	GO_EXTLINK_ENABLED
  1518  // 		Whether the linker should use external linking mode
  1519  // 		when using -linkmode=auto with code that uses cgo.
  1520  // 		Set to 0 to disable external linking mode, 1 to enable it.
  1521  // 	GIT_ALLOW_PROTOCOL
  1522  // 		Defined by Git. A colon-separated list of schemes that are allowed to be used
  1523  // 		with git fetch/clone. If set, any scheme not explicitly mentioned will be
  1524  // 		considered insecure by 'go get'.
  1525  //
  1526  // Additional information available from 'go env' but not read from the environment:
  1527  //
  1528  // 	GOEXE
  1529  // 		The executable file name suffix (".exe" on Windows, "" on other systems).
  1530  // 	GOHOSTARCH
  1531  // 		The architecture (GOARCH) of the Go toolchain binaries.
  1532  // 	GOHOSTOS
  1533  // 		The operating system (GOOS) of the Go toolchain binaries.
  1534  // 	GOMOD
  1535  // 		The absolute path to the go.mod of the main module,
  1536  // 		or the empty string if not using modules.
  1537  // 	GOTOOLDIR
  1538  // 		The directory where the go tools (compile, cover, doc, etc...) are installed.
  1539  //
  1540  //
  1541  // File types
  1542  //
  1543  // The go command examines the contents of a restricted set of files
  1544  // in each directory. It identifies which files to examine based on
  1545  // the extension of the file name. These extensions are:
  1546  //
  1547  // 	.go
  1548  // 		Go source files.
  1549  // 	.c, .h
  1550  // 		C source files.
  1551  // 		If the package uses cgo or SWIG, these will be compiled with the
  1552  // 		OS-native compiler (typically gcc); otherwise they will
  1553  // 		trigger an error.
  1554  // 	.cc, .cpp, .cxx, .hh, .hpp, .hxx
  1555  // 		C++ source files. Only useful with cgo or SWIG, and always
  1556  // 		compiled with the OS-native compiler.
  1557  // 	.m
  1558  // 		Objective-C source files. Only useful with cgo, and always
  1559  // 		compiled with the OS-native compiler.
  1560  // 	.s, .S
  1561  // 		Assembler source files.
  1562  // 		If the package uses cgo or SWIG, these will be assembled with the
  1563  // 		OS-native assembler (typically gcc (sic)); otherwise they
  1564  // 		will be assembled with the Go assembler.
  1565  // 	.swig, .swigcxx
  1566  // 		SWIG definition files.
  1567  // 	.syso
  1568  // 		System object files.
  1569  //
  1570  // Files of each of these types except .syso may contain build
  1571  // constraints, but the go command stops scanning for build constraints
  1572  // at the first item in the file that is not a blank line or //-style
  1573  // line comment. See the go/build package documentation for
  1574  // more details.
  1575  //
  1576  // Non-test Go source files can also include a //go:binary-only-package
  1577  // comment, indicating that the package sources are included
  1578  // for documentation only and must not be used to build the
  1579  // package binary. This enables distribution of Go packages in
  1580  // their compiled form alone. Even binary-only packages require
  1581  // accurate import blocks listing required dependencies, so that
  1582  // those dependencies can be supplied when linking the resulting
  1583  // command.
  1584  //
  1585  //
  1586  // The go.mod file
  1587  //
  1588  // A module version is defined by a tree of source files, with a go.mod
  1589  // file in its root. When the go command is run, it looks in the current
  1590  // directory and then successive parent directories to find the go.mod
  1591  // marking the root of the main (current) module.
  1592  //
  1593  // The go.mod file itself is line-oriented, with // comments but
  1594  // no /* */ comments. Each line holds a single directive, made up of a
  1595  // verb followed by arguments. For example:
  1596  //
  1597  // 	module my/thing
  1598  // 	require other/thing v1.0.2
  1599  // 	require new/thing v2.3.4
  1600  // 	exclude old/thing v1.2.3
  1601  // 	replace bad/thing v1.4.5 => good/thing v1.4.5
  1602  //
  1603  // The verbs are module, to define the module path; require, to require
  1604  // a particular module at a given version or later; exclude, to exclude
  1605  // a particular module version from use; and replace, to replace a module
  1606  // version with a different module version. Exclude and replace apply only
  1607  // in the main module's go.mod and are ignored in dependencies.
  1608  // See https://research.swtch.com/vgo-mvs for details.
  1609  //
  1610  // The leading verb can be factored out of adjacent lines to create a block,
  1611  // like in Go imports:
  1612  //
  1613  // 	require (
  1614  // 		new/thing v2.3.4
  1615  // 		old/thing v1.2.3
  1616  // 	)
  1617  //
  1618  // The go.mod file is designed both to be edited directly and to be
  1619  // easily updated by tools. The 'go mod edit' command can be used to
  1620  // parse and edit the go.mod file from programs and tools.
  1621  // See 'go help mod edit'.
  1622  //
  1623  // The go command automatically updates go.mod each time it uses the
  1624  // module graph, to make sure go.mod always accurately reflects reality
  1625  // and is properly formatted. For example, consider this go.mod file:
  1626  //
  1627  //         module M
  1628  //
  1629  //         require (
  1630  //                 A v1
  1631  //                 B v1.0.0
  1632  //                 C v1.0.0
  1633  //                 D v1.2.3
  1634  //                 E dev
  1635  //         )
  1636  //
  1637  //         exclude D v1.2.3
  1638  //
  1639  // The update rewrites non-canonical version identifiers to semver form,
  1640  // so A's v1 becomes v1.0.0 and E's dev becomes the pseudo-version for the
  1641  // latest commit on the dev branch, perhaps v0.0.0-20180523231146-b3f5c0f6e5f1.
  1642  //
  1643  // The update modifies requirements to respect exclusions, so the
  1644  // requirement on the excluded D v1.2.3 is updated to use the next
  1645  // available version of D, perhaps D v1.2.4 or D v1.3.0.
  1646  //
  1647  // The update removes redundant or misleading requirements.
  1648  // For example, if A v1.0.0 itself requires B v1.2.0 and C v1.0.0,
  1649  // then go.mod's requirement of B v1.0.0 is misleading (superseded by
  1650  // A's need for v1.2.0), and its requirement of C v1.0.0 is redundant
  1651  // (implied by A's need for the same version), so both will be removed.
  1652  // If module M contains packages that directly import packages from B or
  1653  // C, then the requirements will be kept but updated to the actual
  1654  // versions being used.
  1655  //
  1656  // Finally, the update reformats the go.mod in a canonical formatting, so
  1657  // that future mechanical changes will result in minimal diffs.
  1658  //
  1659  // Because the module graph defines the meaning of import statements, any
  1660  // commands that load packages also use and therefore update go.mod,
  1661  // including go build, go get, go install, go list, go test, go mod graph,
  1662  // go mod tidy, and go mod why.
  1663  //
  1664  //
  1665  // GOPATH environment variable
  1666  //
  1667  // The Go path is used to resolve import statements.
  1668  // It is implemented by and documented in the go/build package.
  1669  //
  1670  // The GOPATH environment variable lists places to look for Go code.
  1671  // On Unix, the value is a colon-separated string.
  1672  // On Windows, the value is a semicolon-separated string.
  1673  // On Plan 9, the value is a list.
  1674  //
  1675  // If the environment variable is unset, GOPATH defaults
  1676  // to a subdirectory named "go" in the user's home directory
  1677  // ($HOME/go on Unix, %USERPROFILE%\go on Windows),
  1678  // unless that directory holds a Go distribution.
  1679  // Run "go env GOPATH" to see the current GOPATH.
  1680  //
  1681  // See https://golang.org/wiki/SettingGOPATH to set a custom GOPATH.
  1682  //
  1683  // Each directory listed in GOPATH must have a prescribed structure:
  1684  //
  1685  // The src directory holds source code. The path below src
  1686  // determines the import path or executable name.
  1687  //
  1688  // The pkg directory holds installed package objects.
  1689  // As in the Go tree, each target operating system and
  1690  // architecture pair has its own subdirectory of pkg
  1691  // (pkg/GOOS_GOARCH).
  1692  //
  1693  // If DIR is a directory listed in the GOPATH, a package with
  1694  // source in DIR/src/foo/bar can be imported as "foo/bar" and
  1695  // has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a".
  1696  //
  1697  // The bin directory holds compiled commands.
  1698  // Each command is named for its source directory, but only
  1699  // the final element, not the entire path. That is, the
  1700  // command with source in DIR/src/foo/quux is installed into
  1701  // DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped
  1702  // so that you can add DIR/bin to your PATH to get at the
  1703  // installed commands. If the GOBIN environment variable is
  1704  // set, commands are installed to the directory it names instead
  1705  // of DIR/bin. GOBIN must be an absolute path.
  1706  //
  1707  // Here's an example directory layout:
  1708  //
  1709  //     GOPATH=/home/user/go
  1710  //
  1711  //     /home/user/go/
  1712  //         src/
  1713  //             foo/
  1714  //                 bar/               (go code in package bar)
  1715  //                     x.go
  1716  //                 quux/              (go code in package main)
  1717  //                     y.go
  1718  //         bin/
  1719  //             quux                   (installed command)
  1720  //         pkg/
  1721  //             linux_amd64/
  1722  //                 foo/
  1723  //                     bar.a          (installed package object)
  1724  //
  1725  // Go searches each directory listed in GOPATH to find source code,
  1726  // but new packages are always downloaded into the first directory
  1727  // in the list.
  1728  //
  1729  // See https://golang.org/doc/code.html for an example.
  1730  //
  1731  // GOPATH and Modules
  1732  //
  1733  // When using modules, GOPATH is no longer used for resolving imports.
  1734  // However, it is still used to store downloaded source code (in GOPATH/pkg/mod)
  1735  // and compiled commands (in GOPATH/bin).
  1736  //
  1737  // Internal Directories
  1738  //
  1739  // Code in or below a directory named "internal" is importable only
  1740  // by code in the directory tree rooted at the parent of "internal".
  1741  // Here's an extended version of the directory layout above:
  1742  //
  1743  //     /home/user/go/
  1744  //         src/
  1745  //             crash/
  1746  //                 bang/              (go code in package bang)
  1747  //                     b.go
  1748  //             foo/                   (go code in package foo)
  1749  //                 f.go
  1750  //                 bar/               (go code in package bar)
  1751  //                     x.go
  1752  //                 internal/
  1753  //                     baz/           (go code in package baz)
  1754  //                         z.go
  1755  //                 quux/              (go code in package main)
  1756  //                     y.go
  1757  //
  1758  //
  1759  // The code in z.go is imported as "foo/internal/baz", but that
  1760  // import statement can only appear in source files in the subtree
  1761  // rooted at foo. The source files foo/f.go, foo/bar/x.go, and
  1762  // foo/quux/y.go can all import "foo/internal/baz", but the source file
  1763  // crash/bang/b.go cannot.
  1764  //
  1765  // See https://golang.org/s/go14internal for details.
  1766  //
  1767  // Vendor Directories
  1768  //
  1769  // Go 1.6 includes support for using local copies of external dependencies
  1770  // to satisfy imports of those dependencies, often referred to as vendoring.
  1771  //
  1772  // Code below a directory named "vendor" is importable only
  1773  // by code in the directory tree rooted at the parent of "vendor",
  1774  // and only using an import path that omits the prefix up to and
  1775  // including the vendor element.
  1776  //
  1777  // Here's the example from the previous section,
  1778  // but with the "internal" directory renamed to "vendor"
  1779  // and a new foo/vendor/crash/bang directory added:
  1780  //
  1781  //     /home/user/go/
  1782  //         src/
  1783  //             crash/
  1784  //                 bang/              (go code in package bang)
  1785  //                     b.go
  1786  //             foo/                   (go code in package foo)
  1787  //                 f.go
  1788  //                 bar/               (go code in package bar)
  1789  //                     x.go
  1790  //                 vendor/
  1791  //                     crash/
  1792  //                         bang/      (go code in package bang)
  1793  //                             b.go
  1794  //                     baz/           (go code in package baz)
  1795  //                         z.go
  1796  //                 quux/              (go code in package main)
  1797  //                     y.go
  1798  //
  1799  // The same visibility rules apply as for internal, but the code
  1800  // in z.go is imported as "baz", not as "foo/vendor/baz".
  1801  //
  1802  // Code in vendor directories deeper in the source tree shadows
  1803  // code in higher directories. Within the subtree rooted at foo, an import
  1804  // of "crash/bang" resolves to "foo/vendor/crash/bang", not the
  1805  // top-level "crash/bang".
  1806  //
  1807  // Code in vendor directories is not subject to import path
  1808  // checking (see 'go help importpath').
  1809  //
  1810  // When 'go get' checks out or updates a git repository, it now also
  1811  // updates submodules.
  1812  //
  1813  // Vendor directories do not affect the placement of new repositories
  1814  // being checked out for the first time by 'go get': those are always
  1815  // placed in the main GOPATH, never in a vendor subtree.
  1816  //
  1817  // See https://golang.org/s/go15vendor for details.
  1818  //
  1819  //
  1820  // Module proxy protocol
  1821  //
  1822  // The go command by default downloads modules from version control systems
  1823  // directly, just as 'go get' always has. The GOPROXY environment variable allows
  1824  // further control over the download source. If GOPROXY is unset, is the empty string,
  1825  // or is the string "direct", downloads use the default direct connection to version
  1826  // control systems. Setting GOPROXY to "off" disallows downloading modules from
  1827  // any source. Otherwise, GOPROXY is expected to be the URL of a module proxy,
  1828  // in which case the go command will fetch all modules from that proxy.
  1829  // No matter the source of the modules, downloaded modules must match existing
  1830  // entries in go.sum (see 'go help modules' for discussion of verification).
  1831  //
  1832  // A Go module proxy is any web server that can respond to GET requests for
  1833  // URLs of a specified form. The requests have no query parameters, so even
  1834  // a site serving from a fixed file system (including a file:/// URL)
  1835  // can be a module proxy.
  1836  //
  1837  // The GET requests sent to a Go module proxy are:
  1838  //
  1839  // GET $GOPROXY/<module>/@v/list returns a list of all known versions of the
  1840  // given module, one per line.
  1841  //
  1842  // GET $GOPROXY/<module>/@v/<version>.info returns JSON-formatted metadata
  1843  // about that version of the given module.
  1844  //
  1845  // GET $GOPROXY/<module>/@v/<version>.mod returns the go.mod file
  1846  // for that version of the given module.
  1847  //
  1848  // GET $GOPROXY/<module>/@v/<version>.zip returns the zip archive
  1849  // for that version of the given module.
  1850  //
  1851  // To avoid problems when serving from case-sensitive file systems,
  1852  // the <module> and <version> elements are case-encoded, replacing every
  1853  // uppercase letter with an exclamation mark followed by the corresponding
  1854  // lower-case letter: github.com/Azure encodes as github.com/!azure.
  1855  //
  1856  // The JSON-formatted metadata about a given module corresponds to
  1857  // this Go data structure, which may be expanded in the future:
  1858  //
  1859  //     type Info struct {
  1860  //         Version string    // version string
  1861  //         Time    time.Time // commit time
  1862  //     }
  1863  //
  1864  // The zip archive for a specific version of a given module is a
  1865  // standard zip file that contains the file tree corresponding
  1866  // to the module's source code and related files. The archive uses
  1867  // slash-separated paths, and every file path in the archive must
  1868  // begin with <module>@<version>/, where the module and version are
  1869  // substituted directly, not case-encoded. The root of the module
  1870  // file tree corresponds to the <module>@<version>/ prefix in the
  1871  // archive.
  1872  //
  1873  // Even when downloading directly from version control systems,
  1874  // the go command synthesizes explicit info, mod, and zip files
  1875  // and stores them in its local cache, $GOPATH/pkg/mod/cache/download,
  1876  // the same as if it had downloaded them directly from a proxy.
  1877  // The cache layout is the same as the proxy URL space, so
  1878  // serving $GOPATH/pkg/mod/cache/download at (or copying it to)
  1879  // https://example.com/proxy would let other users access those
  1880  // cached module versions with GOPROXY=https://example.com/proxy.
  1881  //
  1882  //
  1883  // Import path syntax
  1884  //
  1885  // An import path (see 'go help packages') denotes a package stored in the local
  1886  // file system. In general, an import path denotes either a standard package (such
  1887  // as "unicode/utf8") or a package found in one of the work spaces (For more
  1888  // details see: 'go help gopath').
  1889  //
  1890  // Relative import paths
  1891  //
  1892  // An import path beginning with ./ or ../ is called a relative path.
  1893  // The toolchain supports relative import paths as a shortcut in two ways.
  1894  //
  1895  // First, a relative path can be used as a shorthand on the command line.
  1896  // If you are working in the directory containing the code imported as
  1897  // "unicode" and want to run the tests for "unicode/utf8", you can type
  1898  // "go test ./utf8" instead of needing to specify the full path.
  1899  // Similarly, in the reverse situation, "go test .." will test "unicode" from
  1900  // the "unicode/utf8" directory. Relative patterns are also allowed, like
  1901  // "go test ./..." to test all subdirectories. See 'go help packages' for details
  1902  // on the pattern syntax.
  1903  //
  1904  // Second, if you are compiling a Go program not in a work space,
  1905  // you can use a relative path in an import statement in that program
  1906  // to refer to nearby code also not in a work space.
  1907  // This makes it easy to experiment with small multipackage programs
  1908  // outside of the usual work spaces, but such programs cannot be
  1909  // installed with "go install" (there is no work space in which to install them),
  1910  // so they are rebuilt from scratch each time they are built.
  1911  // To avoid ambiguity, Go programs cannot use relative import paths
  1912  // within a work space.
  1913  //
  1914  // Remote import paths
  1915  //
  1916  // Certain import paths also
  1917  // describe how to obtain the source code for the package using
  1918  // a revision control system.
  1919  //
  1920  // A few common code hosting sites have special syntax:
  1921  //
  1922  // 	Bitbucket (Git, Mercurial)
  1923  //
  1924  // 		import "bitbucket.org/user/project"
  1925  // 		import "bitbucket.org/user/project/sub/directory"
  1926  //
  1927  // 	GitHub (Git)
  1928  //
  1929  // 		import "github.com/user/project"
  1930  // 		import "github.com/user/project/sub/directory"
  1931  //
  1932  // 	Launchpad (Bazaar)
  1933  //
  1934  // 		import "launchpad.net/project"
  1935  // 		import "launchpad.net/project/series"
  1936  // 		import "launchpad.net/project/series/sub/directory"
  1937  //
  1938  // 		import "launchpad.net/~user/project/branch"
  1939  // 		import "launchpad.net/~user/project/branch/sub/directory"
  1940  //
  1941  // 	IBM DevOps Services (Git)
  1942  //
  1943  // 		import "hub.jazz.net/git/user/project"
  1944  // 		import "hub.jazz.net/git/user/project/sub/directory"
  1945  //
  1946  // For code hosted on other servers, import paths may either be qualified
  1947  // with the version control type, or the go tool can dynamically fetch
  1948  // the import path over https/http and discover where the code resides
  1949  // from a <meta> tag in the HTML.
  1950  //
  1951  // To declare the code location, an import path of the form
  1952  //
  1953  // 	repository.vcs/path
  1954  //
  1955  // specifies the given repository, with or without the .vcs suffix,
  1956  // using the named version control system, and then the path inside
  1957  // that repository. The supported version control systems are:
  1958  //
  1959  // 	Bazaar      .bzr
  1960  // 	Fossil      .fossil
  1961  // 	Git         .git
  1962  // 	Mercurial   .hg
  1963  // 	Subversion  .svn
  1964  //
  1965  // For example,
  1966  //
  1967  // 	import "example.org/user/foo.hg"
  1968  //
  1969  // denotes the root directory of the Mercurial repository at
  1970  // example.org/user/foo or foo.hg, and
  1971  //
  1972  // 	import "example.org/repo.git/foo/bar"
  1973  //
  1974  // denotes the foo/bar directory of the Git repository at
  1975  // example.org/repo or repo.git.
  1976  //
  1977  // When a version control system supports multiple protocols,
  1978  // each is tried in turn when downloading. For example, a Git
  1979  // download tries https://, then git+ssh://.
  1980  //
  1981  // By default, downloads are restricted to known secure protocols
  1982  // (e.g. https, ssh). To override this setting for Git downloads, the
  1983  // GIT_ALLOW_PROTOCOL environment variable can be set (For more details see:
  1984  // 'go help environment').
  1985  //
  1986  // If the import path is not a known code hosting site and also lacks a
  1987  // version control qualifier, the go tool attempts to fetch the import
  1988  // over https/http and looks for a <meta> tag in the document's HTML
  1989  // <head>.
  1990  //
  1991  // The meta tag has the form:
  1992  //
  1993  // 	<meta name="go-import" content="import-prefix vcs repo-root">
  1994  //
  1995  // The import-prefix is the import path corresponding to the repository
  1996  // root. It must be a prefix or an exact match of the package being
  1997  // fetched with "go get". If it's not an exact match, another http
  1998  // request is made at the prefix to verify the <meta> tags match.
  1999  //
  2000  // The meta tag should appear as early in the file as possible.
  2001  // In particular, it should appear before any raw JavaScript or CSS,
  2002  // to avoid confusing the go command's restricted parser.
  2003  //
  2004  // The vcs is one of "bzr", "fossil", "git", "hg", "svn".
  2005  //
  2006  // The repo-root is the root of the version control system
  2007  // containing a scheme and not containing a .vcs qualifier.
  2008  //
  2009  // For example,
  2010  //
  2011  // 	import "example.org/pkg/foo"
  2012  //
  2013  // will result in the following requests:
  2014  //
  2015  // 	https://example.org/pkg/foo?go-get=1 (preferred)
  2016  // 	http://example.org/pkg/foo?go-get=1  (fallback, only with -insecure)
  2017  //
  2018  // If that page contains the meta tag
  2019  //
  2020  // 	<meta name="go-import" content="example.org git https://code.org/r/p/exproj">
  2021  //
  2022  // the go tool will verify that https://example.org/?go-get=1 contains the
  2023  // same meta tag and then git clone https://code.org/r/p/exproj into
  2024  // GOPATH/src/example.org.
  2025  //
  2026  // When using GOPATH, downloaded packages are written to the first directory
  2027  // listed in the GOPATH environment variable.
  2028  // (See 'go help gopath-get' and 'go help gopath'.)
  2029  //
  2030  // When using modules, downloaded packages are stored in the module cache.
  2031  // (See 'go help modules-get' and 'go help goproxy'.)
  2032  //
  2033  // When using modules, an additional variant of the go-import meta tag is
  2034  // recognized and is preferred over those listing version control systems.
  2035  // That variant uses "mod" as the vcs in the content value, as in:
  2036  //
  2037  // 	<meta name="go-import" content="example.org mod https://code.org/moduleproxy">
  2038  //
  2039  // This tag means to fetch modules with paths beginning with example.org
  2040  // from the module proxy available at the URL https://code.org/moduleproxy.
  2041  // See 'go help goproxy' for details about the proxy protocol.
  2042  //
  2043  // Import path checking
  2044  //
  2045  // When the custom import path feature described above redirects to a
  2046  // known code hosting site, each of the resulting packages has two possible
  2047  // import paths, using the custom domain or the known hosting site.
  2048  //
  2049  // A package statement is said to have an "import comment" if it is immediately
  2050  // followed (before the next newline) by a comment of one of these two forms:
  2051  //
  2052  // 	package math // import "path"
  2053  // 	package math /* import "path" */
  2054  //
  2055  // The go command will refuse to install a package with an import comment
  2056  // unless it is being referred to by that import path. In this way, import comments
  2057  // let package authors make sure the custom import path is used and not a
  2058  // direct path to the underlying code hosting site.
  2059  //
  2060  // Import path checking is disabled for code found within vendor trees.
  2061  // This makes it possible to copy code into alternate locations in vendor trees
  2062  // without needing to update import comments.
  2063  //
  2064  // Import path checking is also disabled when using modules.
  2065  // Import path comments are obsoleted by the go.mod file's module statement.
  2066  //
  2067  // See https://golang.org/s/go14customimport for details.
  2068  //
  2069  //
  2070  // Modules, module versions, and more
  2071  //
  2072  // A module is a collection of related Go packages.
  2073  // Modules are the unit of source code interchange and versioning.
  2074  // The go command has direct support for working with modules,
  2075  // including recording and resolving dependencies on other modules.
  2076  // Modules replace the old GOPATH-based approach to specifying
  2077  // which source files are used in a given build.
  2078  //
  2079  // Preliminary module support
  2080  //
  2081  // Go 1.11 includes preliminary support for Go modules,
  2082  // including a new module-aware 'go get' command.
  2083  // We intend to keep revising this support, while preserving compatibility,
  2084  // until it can be declared official (no longer preliminary),
  2085  // and then at a later point we may remove support for work
  2086  // in GOPATH and the old 'go get' command.
  2087  //
  2088  // The quickest way to take advantage of the new Go 1.11 module support
  2089  // is to check out your repository into a directory outside GOPATH/src,
  2090  // create a go.mod file (described in the next section) there, and run
  2091  // go commands from within that file tree.
  2092  //
  2093  // For more fine-grained control, the module support in Go 1.11 respects
  2094  // a temporary environment variable, GO111MODULE, which can be set to one
  2095  // of three string values: off, on, or auto (the default).
  2096  // If GO111MODULE=off, then the go command never uses the
  2097  // new module support. Instead it looks in vendor directories and GOPATH
  2098  // to find dependencies; we now refer to this as "GOPATH mode."
  2099  // If GO111MODULE=on, then the go command requires the use of modules,
  2100  // never consulting GOPATH. We refer to this as the command being
  2101  // module-aware or running in "module-aware mode".
  2102  // If GO111MODULE=auto or is unset, then the go command enables or
  2103  // disables module support based on the current directory.
  2104  // Module support is enabled only when the current directory is outside
  2105  // GOPATH/src and itself contains a go.mod file or is below a directory
  2106  // containing a go.mod file.
  2107  //
  2108  // In module-aware mode, GOPATH no longer defines the meaning of imports
  2109  // during a build, but it still stores downloaded dependencies (in GOPATH/pkg/mod)
  2110  // and installed commands (in GOPATH/bin, unless GOBIN is set).
  2111  //
  2112  // Defining a module
  2113  //
  2114  // A module is defined by a tree of Go source files with a go.mod file
  2115  // in the tree's root directory. The directory containing the go.mod file
  2116  // is called the module root. Typically the module root will also correspond
  2117  // to a source code repository root (but in general it need not).
  2118  // The module is the set of all Go packages in the module root and its
  2119  // subdirectories, but excluding subtrees with their own go.mod files.
  2120  //
  2121  // The "module path" is the import path prefix corresponding to the module root.
  2122  // The go.mod file defines the module path and lists the specific versions
  2123  // of other modules that should be used when resolving imports during a build,
  2124  // by giving their module paths and versions.
  2125  //
  2126  // For example, this go.mod declares that the directory containing it is the root
  2127  // of the module with path example.com/m, and it also declares that the module
  2128  // depends on specific versions of golang.org/x/text and gopkg.in/yaml.v2:
  2129  //
  2130  // 	module example.com/m
  2131  //
  2132  // 	require (
  2133  // 		golang.org/x/text v0.3.0
  2134  // 		gopkg.in/yaml.v2 v2.1.0
  2135  // 	)
  2136  //
  2137  // The go.mod file can also specify replacements and excluded versions
  2138  // that only apply when building the module directly; they are ignored
  2139  // when the module is incorporated into a larger build.
  2140  // For more about the go.mod file, see 'go help go.mod'.
  2141  //
  2142  // To start a new module, simply create a go.mod file in the root of the
  2143  // module's directory tree, containing only a module statement.
  2144  // The 'go mod init' command can be used to do this:
  2145  //
  2146  // 	go mod init example.com/m
  2147  //
  2148  // In a project already using an existing dependency management tool like
  2149  // godep, glide, or dep, 'go mod init' will also add require statements
  2150  // matching the existing configuration.
  2151  //
  2152  // Once the go.mod file exists, no additional steps are required:
  2153  // go commands like 'go build', 'go test', or even 'go list' will automatically
  2154  // add new dependencies as needed to satisfy imports.
  2155  //
  2156  // The main module and the build list
  2157  //
  2158  // The "main module" is the module containing the directory where the go command
  2159  // is run. The go command finds the module root by looking for a go.mod in the
  2160  // current directory, or else the current directory's parent directory,
  2161  // or else the parent's parent directory, and so on.
  2162  //
  2163  // The main module's go.mod file defines the precise set of packages available
  2164  // for use by the go command, through require, replace, and exclude statements.
  2165  // Dependency modules, found by following require statements, also contribute
  2166  // to the definition of that set of packages, but only through their go.mod
  2167  // files' require statements: any replace and exclude statements in dependency
  2168  // modules are ignored. The replace and exclude statements therefore allow the
  2169  // main module complete control over its own build, without also being subject
  2170  // to complete control by dependencies.
  2171  //
  2172  // The set of modules providing packages to builds is called the "build list".
  2173  // The build list initially contains only the main module. Then the go command
  2174  // adds to the list the exact module versions required by modules already
  2175  // on the list, recursively, until there is nothing left to add to the list.
  2176  // If multiple versions of a particular module are added to the list,
  2177  // then at the end only the latest version (according to semantic version
  2178  // ordering) is kept for use in the build.
  2179  //
  2180  // The 'go list' command provides information about the main module
  2181  // and the build list. For example:
  2182  //
  2183  // 	go list -m              # print path of main module
  2184  // 	go list -m -f={{.Dir}}  # print root directory of main module
  2185  // 	go list -m all          # print build list
  2186  //
  2187  // Maintaining module requirements
  2188  //
  2189  // The go.mod file is meant to be readable and editable by both
  2190  // programmers and tools. The go command itself automatically updates the go.mod file
  2191  // to maintain a standard formatting and the accuracy of require statements.
  2192  //
  2193  // Any go command that finds an unfamiliar import will look up the module
  2194  // containing that import and add the latest version of that module
  2195  // to go.mod automatically. In most cases, therefore, it suffices to
  2196  // add an import to source code and run 'go build', 'go test', or even 'go list':
  2197  // as part of analyzing the package, the go command will discover
  2198  // and resolve the import and update the go.mod file.
  2199  //
  2200  // Any go command can determine that a module requirement is
  2201  // missing and must be added, even when considering only a single
  2202  // package from the module. On the other hand, determining that a module requirement
  2203  // is no longer necessary and can be deleted requires a full view of
  2204  // all packages in the module, across all possible build configurations
  2205  // (architectures, operating systems, build tags, and so on).
  2206  // The 'go mod tidy' command builds that view and then
  2207  // adds any missing module requirements and removes unnecessary ones.
  2208  //
  2209  // As part of maintaining the require statements in go.mod, the go command
  2210  // tracks which ones provide packages imported directly by the current module
  2211  // and which ones provide packages only used indirectly by other module
  2212  // dependencies. Requirements needed only for indirect uses are marked with a
  2213  // "// indirect" comment in the go.mod file. Indirect requirements are
  2214  // automatically removed from the go.mod file once they are implied by other
  2215  // direct requirements. Indirect requirements only arise when using modules
  2216  // that fail to state some of their own dependencies or when explicitly
  2217  // upgrading a module's dependencies ahead of its own stated requirements.
  2218  //
  2219  // Because of this automatic maintenance, the information in go.mod is an
  2220  // up-to-date, readable description of the build.
  2221  //
  2222  // The 'go get' command updates go.mod to change the module versions used in a
  2223  // build. An upgrade of one module may imply upgrading others, and similarly a
  2224  // downgrade of one module may imply downgrading others. The 'go get' command
  2225  // makes these implied changes as well. If go.mod is edited directly, commands
  2226  // like 'go build' or 'go list' will assume that an upgrade is intended and
  2227  // automatically make any implied upgrades and update go.mod to reflect them.
  2228  //
  2229  // The 'go mod' command provides other functionality for use in maintaining
  2230  // and understanding modules and go.mod files. See 'go help mod'.
  2231  //
  2232  // The -mod build flag provides additional control over updating and use of go.mod.
  2233  //
  2234  // If invoked with -mod=readonly, the go command is disallowed from the implicit
  2235  // automatic updating of go.mod described above. Instead, it fails when any changes
  2236  // to go.mod are needed. This setting is most useful to check that go.mod does
  2237  // not need updates, such as in a continuous integration and testing system.
  2238  // The "go get" command remains permitted to update go.mod even with -mod=readonly,
  2239  // and the "go mod" commands do not take the -mod flag (or any other build flags).
  2240  //
  2241  // If invoked with -mod=vendor, the go command assumes that the vendor
  2242  // directory holds the correct copies of dependencies and ignores
  2243  // the dependency descriptions in go.mod.
  2244  //
  2245  // Pseudo-versions
  2246  //
  2247  // The go.mod file and the go command more generally use semantic versions as
  2248  // the standard form for describing module versions, so that versions can be
  2249  // compared to determine which should be considered earlier or later than another.
  2250  // A module version like v1.2.3 is introduced by tagging a revision in the
  2251  // underlying source repository. Untagged revisions can be referred to
  2252  // using a "pseudo-version" like v0.0.0-yyyymmddhhmmss-abcdefabcdef,
  2253  // where the time is the commit time in UTC and the final suffix is the prefix
  2254  // of the commit hash. The time portion ensures that two pseudo-versions can
  2255  // be compared to determine which happened later, the commit hash identifes
  2256  // the underlying commit, and the prefix (v0.0.0- in this example) is derived from
  2257  // the most recent tagged version in the commit graph before this commit.
  2258  //
  2259  // There are three pseudo-version forms:
  2260  //
  2261  // vX.0.0-yyyymmddhhmmss-abcdefabcdef is used when there is no earlier
  2262  // versioned commit with an appropriate major version before the target commit.
  2263  // (This was originally the only form, so some older go.mod files use this form
  2264  // even for commits that do follow tags.)
  2265  //
  2266  // vX.Y.Z-pre.0.yyyymmddhhmmss-abcdefabcdef is used when the most
  2267  // recent versioned commit before the target commit is vX.Y.Z-pre.
  2268  //
  2269  // vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdefabcdef is used when the most
  2270  // recent versioned commit before the target commit is vX.Y.Z.
  2271  //
  2272  // Pseudo-versions never need to be typed by hand: the go command will accept
  2273  // the plain commit hash and translate it into a pseudo-version (or a tagged
  2274  // version if available) automatically. This conversion is an example of a
  2275  // module query.
  2276  //
  2277  // Module queries
  2278  //
  2279  // The go command accepts a "module query" in place of a module version
  2280  // both on the command line and in the main module's go.mod file.
  2281  // (After evaluating a query found in the main module's go.mod file,
  2282  // the go command updates the file to replace the query with its result.)
  2283  //
  2284  // A fully-specified semantic version, such as "v1.2.3",
  2285  // evaluates to that specific version.
  2286  //
  2287  // A semantic version prefix, such as "v1" or "v1.2",
  2288  // evaluates to the latest available tagged version with that prefix.
  2289  //
  2290  // A semantic version comparison, such as "<v1.2.3" or ">=v1.5.6",
  2291  // evaluates to the available tagged version nearest to the comparison target
  2292  // (the latest version for < and <=, the earliest version for > and >=).
  2293  //
  2294  // The string "latest" matches the latest available tagged version,
  2295  // or else the underlying source repository's latest untagged revision.
  2296  //
  2297  // A revision identifier for the underlying source repository,
  2298  // such as a commit hash prefix, revision tag, or branch name,
  2299  // selects that specific code revision. If the revision is
  2300  // also tagged with a semantic version, the query evaluates to
  2301  // that semantic version. Otherwise the query evaluates to a
  2302  // pseudo-version for the commit.
  2303  //
  2304  // All queries prefer release versions to pre-release versions.
  2305  // For example, "<v1.2.3" will prefer to return "v1.2.2"
  2306  // instead of "v1.2.3-pre1", even though "v1.2.3-pre1" is nearer
  2307  // to the comparison target.
  2308  //
  2309  // Module versions disallowed by exclude statements in the
  2310  // main module's go.mod are considered unavailable and cannot
  2311  // be returned by queries.
  2312  //
  2313  // For example, these commands are all valid:
  2314  //
  2315  // 	go get github.com/gorilla/mux@latest    # same (@latest is default for 'go get')
  2316  // 	go get github.com/gorilla/mux@v1.6.2    # records v1.6.2
  2317  // 	go get github.com/gorilla/mux@e3702bed2 # records v1.6.2
  2318  // 	go get github.com/gorilla/mux@c856192   # records v0.0.0-20180517173623-c85619274f5d
  2319  // 	go get github.com/gorilla/mux@master    # records current meaning of master
  2320  //
  2321  // Module compatibility and semantic versioning
  2322  //
  2323  // The go command requires that modules use semantic versions and expects that
  2324  // the versions accurately describe compatibility: it assumes that v1.5.4 is a
  2325  // backwards-compatible replacement for v1.5.3, v1.4.0, and even v1.0.0.
  2326  // More generally the go command expects that packages follow the
  2327  // "import compatibility rule", which says:
  2328  //
  2329  // "If an old package and a new package have the same import path,
  2330  // the new package must be backwards compatible with the old package."
  2331  //
  2332  // Because the go command assumes the import compatibility rule,
  2333  // a module definition can only set the minimum required version of one
  2334  // of its dependencies: it cannot set a maximum or exclude selected versions.
  2335  // Still, the import compatibility rule is not a guarantee: it may be that
  2336  // v1.5.4 is buggy and not a backwards-compatible replacement for v1.5.3.
  2337  // Because of this, the go command never updates from an older version
  2338  // to a newer version of a module unasked.
  2339  //
  2340  // In semantic versioning, changing the major version number indicates a lack
  2341  // of backwards compatibility with earlier versions. To preserve import
  2342  // compatibility, the go command requires that modules with major version v2
  2343  // or later use a module path with that major version as the final element.
  2344  // For example, version v2.0.0 of example.com/m must instead use module path
  2345  // example.com/m/v2, and packages in that module would use that path as
  2346  // their import path prefix, as in example.com/m/v2/sub/pkg. Including the
  2347  // major version number in the module path and import paths in this way is
  2348  // called "semantic import versioning". Pseudo-versions for modules with major
  2349  // version v2 and later begin with that major version instead of v0, as in
  2350  // v2.0.0-20180326061214-4fc5987536ef.
  2351  //
  2352  // As a special case, module paths beginning with gopkg.in/ continue to use the
  2353  // conventions established on that system: the major version is always present,
  2354  // and it is preceded by a dot instead of a slash: gopkg.in/yaml.v1
  2355  // and gopkg.in/yaml.v2, not gopkg.in/yaml and gopkg.in/yaml/v2.
  2356  //
  2357  // The go command treats modules with different module paths as unrelated:
  2358  // it makes no connection between example.com/m and example.com/m/v2.
  2359  // Modules with different major versions can be used together in a build
  2360  // and are kept separate by the fact that their packages use different
  2361  // import paths.
  2362  //
  2363  // In semantic versioning, major version v0 is for initial development,
  2364  // indicating no expectations of stability or backwards compatibility.
  2365  // Major version v0 does not appear in the module path, because those
  2366  // versions are preparation for v1.0.0, and v1 does not appear in the
  2367  // module path either.
  2368  //
  2369  // Code written before the semantic import versioning convention
  2370  // was introduced may use major versions v2 and later to describe
  2371  // the same set of unversioned import paths as used in v0 and v1.
  2372  // To accommodate such code, if a source code repository has a
  2373  // v2.0.0 or later tag for a file tree with no go.mod, the version is
  2374  // considered to be part of the v1 module's available versions
  2375  // and is given an +incompatible suffix when converted to a module
  2376  // version, as in v2.0.0+incompatible. The +incompatible tag is also
  2377  // applied to pseudo-versions derived from such versions, as in
  2378  // v2.0.1-0.yyyymmddhhmmss-abcdefabcdef+incompatible.
  2379  //
  2380  // In general, having a dependency in the build list (as reported by 'go list -m all')
  2381  // on a v0 version, pre-release version, pseudo-version, or +incompatible version
  2382  // is an indication that problems are more likely when upgrading that
  2383  // dependency, since there is no expectation of compatibility for those.
  2384  //
  2385  // See https://research.swtch.com/vgo-import for more information about
  2386  // semantic import versioning, and see https://semver.org/ for more about
  2387  // semantic versioning.
  2388  //
  2389  // Module code layout
  2390  //
  2391  // For now, see https://research.swtch.com/vgo-module for information
  2392  // about how source code in version control systems is mapped to
  2393  // module file trees.
  2394  //
  2395  // Module downloading and verification
  2396  //
  2397  // The go command maintains, in the main module's root directory alongside
  2398  // go.mod, a file named go.sum containing the expected cryptographic checksums
  2399  // of the content of specific module versions. Each time a dependency is
  2400  // used, its checksum is added to go.sum if missing or else required to match
  2401  // the existing entry in go.sum.
  2402  //
  2403  // The go command maintains a cache of downloaded packages and computes
  2404  // and records the cryptographic checksum of each package at download time.
  2405  // In normal operation, the go command checks these pre-computed checksums
  2406  // against the main module's go.sum file, instead of recomputing them on
  2407  // each command invocation. The 'go mod verify' command checks that
  2408  // the cached copies of module downloads still match both their recorded
  2409  // checksums and the entries in go.sum.
  2410  //
  2411  // The go command can fetch modules from a proxy instead of connecting
  2412  // to source control systems directly, according to the setting of the GOPROXY
  2413  // environment variable.
  2414  //
  2415  // See 'go help goproxy' for details about the proxy and also the format of
  2416  // the cached downloaded packages.
  2417  //
  2418  // Modules and vendoring
  2419  //
  2420  // When using modules, the go command completely ignores vendor directories.
  2421  //
  2422  // By default, the go command satisfies dependencies by downloading modules
  2423  // from their sources and using those downloaded copies (after verification,
  2424  // as described in the previous section). To allow interoperation with older
  2425  // versions of Go, or to ensure that all files used for a build are stored
  2426  // together in a single file tree, 'go mod vendor' creates a directory named
  2427  // vendor in the root directory of the main module and stores there all the
  2428  // packages from dependency modules that are needed to support builds and
  2429  // tests of packages in the main module.
  2430  //
  2431  // To build using the main module's top-level vendor directory to satisfy
  2432  // dependencies (disabling use of the usual network sources and local
  2433  // caches), use 'go build -mod=vendor'. Note that only the main module's
  2434  // top-level vendor directory is used; vendor directories in other locations
  2435  // are still ignored.
  2436  //
  2437  //
  2438  // Module-aware go get
  2439  //
  2440  // The 'go get' command changes behavior depending on whether the
  2441  // go command is running in module-aware mode or legacy GOPATH mode.
  2442  // This help text, accessible as 'go help module-get' even in legacy GOPATH mode,
  2443  // describes 'go get' as it operates in module-aware mode.
  2444  //
  2445  // Usage: go get [-d] [-m] [-u] [-v] [-insecure] [build flags] [packages]
  2446  //
  2447  // Get resolves and adds dependencies to the current development module
  2448  // and then builds and installs them.
  2449  //
  2450  // The first step is to resolve which dependencies to add.
  2451  //
  2452  // For each named package or package pattern, get must decide which version of
  2453  // the corresponding module to use. By default, get chooses the latest tagged
  2454  // release version, such as v0.4.5 or v1.2.3. If there are no tagged release
  2455  // versions, get chooses the latest tagged prerelease version, such as
  2456  // v0.0.1-pre1. If there are no tagged versions at all, get chooses the latest
  2457  // known commit.
  2458  //
  2459  // This default version selection can be overridden by adding an @version
  2460  // suffix to the package argument, as in 'go get golang.org/x/text@v0.3.0'.
  2461  // For modules stored in source control repositories, the version suffix can
  2462  // also be a commit hash, branch identifier, or other syntax known to the
  2463  // source control system, as in 'go get golang.org/x/text@master'.
  2464  // The version suffix @latest explicitly requests the default behavior
  2465  // described above.
  2466  //
  2467  // If a module under consideration is already a dependency of the current
  2468  // development module, then get will update the required version.
  2469  // Specifying a version earlier than the current required version is valid and
  2470  // downgrades the dependency. The version suffix @none indicates that the
  2471  // dependency should be removed entirely.
  2472  //
  2473  // Although get defaults to using the latest version of the module containing
  2474  // a named package, it does not use the latest version of that module's
  2475  // dependencies. Instead it prefers to use the specific dependency versions
  2476  // requested by that module. For example, if the latest A requires module
  2477  // B v1.2.3, while B v1.2.4 and v1.3.1 are also available, then 'go get A'
  2478  // will use the latest A but then use B v1.2.3, as requested by A. (If there
  2479  // are competing requirements for a particular module, then 'go get' resolves
  2480  // those requirements by taking the maximum requested version.)
  2481  //
  2482  // The -u flag instructs get to update dependencies to use newer minor or
  2483  // patch releases when available. Continuing the previous example,
  2484  // 'go get -u A' will use the latest A with B v1.3.1 (not B v1.2.3).
  2485  //
  2486  // The -u=patch flag (not -u patch) instructs get to update dependencies
  2487  // to use newer patch releases when available. Continuing the previous example,
  2488  // 'go get -u=patch A' will use the latest A with B v1.2.4 (not B v1.2.3).
  2489  //
  2490  // In general, adding a new dependency may require upgrading
  2491  // existing dependencies to keep a working build, and 'go get' does
  2492  // this automatically. Similarly, downgrading one dependency may
  2493  // require downgrading other dependenceis, and 'go get' does
  2494  // this automatically as well.
  2495  //
  2496  // The -m flag instructs get to stop here, after resolving, upgrading,
  2497  // and downgrading modules and updating go.mod. When using -m,
  2498  // each specified package path must be a module path as well,
  2499  // not the import path of a package below the module root.
  2500  //
  2501  // The -insecure flag permits fetching from repositories and resolving
  2502  // custom domains using insecure schemes such as HTTP. Use with caution.
  2503  //
  2504  // The second step is to download (if needed), build, and install
  2505  // the named packages.
  2506  //
  2507  // If an argument names a module but not a package (because there is no
  2508  // Go source code in the module's root directory), then the install step
  2509  // is skipped for that argument, instead of causing a build failure.
  2510  // For example 'go get golang.org/x/perf' succeeds even though there
  2511  // is no code corresponding to that import path.
  2512  //
  2513  // Note that package patterns are allowed and are expanded after resolving
  2514  // the module versions. For example, 'go get golang.org/x/perf/cmd/...'
  2515  // adds the latest golang.org/x/perf and then installs the commands in that
  2516  // latest version.
  2517  //
  2518  // The -d flag instructs get to download the source code needed to build
  2519  // the named packages, including downloading necessary dependencies,
  2520  // but not to build and install them.
  2521  //
  2522  // With no package arguments, 'go get' applies to the main module,
  2523  // and to the Go package in the current directory, if any. In particular,
  2524  // 'go get -u' and 'go get -u=patch' update all the dependencies of the
  2525  // main module. With no package arguments and also without -u,
  2526  // 'go get' is not much more than 'go install', and 'go get -d' not much
  2527  // more than 'go list'.
  2528  //
  2529  // For more about modules, see 'go help modules'.
  2530  //
  2531  // For more about specifying packages, see 'go help packages'.
  2532  //
  2533  // This text describes the behavior of get using modules to manage source
  2534  // code and dependencies. If instead the go command is running in GOPATH
  2535  // mode, the details of get's flags and effects change, as does 'go help get'.
  2536  // See 'go help modules' and 'go help gopath-get'.
  2537  //
  2538  // See also: go build, go install, go clean, go mod.
  2539  //
  2540  //
  2541  // Package lists and patterns
  2542  //
  2543  // Many commands apply to a set of packages:
  2544  //
  2545  // 	go action [packages]
  2546  //
  2547  // Usually, [packages] is a list of import paths.
  2548  //
  2549  // An import path that is a rooted path or that begins with
  2550  // a . or .. element is interpreted as a file system path and
  2551  // denotes the package in that directory.
  2552  //
  2553  // Otherwise, the import path P denotes the package found in
  2554  // the directory DIR/src/P for some DIR listed in the GOPATH
  2555  // environment variable (For more details see: 'go help gopath').
  2556  //
  2557  // If no import paths are given, the action applies to the
  2558  // package in the current directory.
  2559  //
  2560  // There are four reserved names for paths that should not be used
  2561  // for packages to be built with the go tool:
  2562  //
  2563  // - "main" denotes the top-level package in a stand-alone executable.
  2564  //
  2565  // - "all" expands to all packages found in all the GOPATH
  2566  // trees. For example, 'go list all' lists all the packages on the local
  2567  // system. When using modules, "all" expands to all packages in
  2568  // the main module and their dependencies, including dependencies
  2569  // needed by tests of any of those.
  2570  //
  2571  // - "std" is like all but expands to just the packages in the standard
  2572  // Go library.
  2573  //
  2574  // - "cmd" expands to the Go repository's commands and their
  2575  // internal libraries.
  2576  //
  2577  // Import paths beginning with "cmd/" only match source code in
  2578  // the Go repository.
  2579  //
  2580  // An import path is a pattern if it includes one or more "..." wildcards,
  2581  // each of which can match any string, including the empty string and
  2582  // strings containing slashes. Such a pattern expands to all package
  2583  // directories found in the GOPATH trees with names matching the
  2584  // patterns.
  2585  //
  2586  // To make common patterns more convenient, there are two special cases.
  2587  // First, /... at the end of the pattern can match an empty string,
  2588  // so that net/... matches both net and packages in its subdirectories, like net/http.
  2589  // Second, any slash-separated pattern element containing a wildcard never
  2590  // participates in a match of the "vendor" element in the path of a vendored
  2591  // package, so that ./... does not match packages in subdirectories of
  2592  // ./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do.
  2593  // Note, however, that a directory named vendor that itself contains code
  2594  // is not a vendored package: cmd/vendor would be a command named vendor,
  2595  // and the pattern cmd/... matches it.
  2596  // See golang.org/s/go15vendor for more about vendoring.
  2597  //
  2598  // An import path can also name a package to be downloaded from
  2599  // a remote repository. Run 'go help importpath' for details.
  2600  //
  2601  // Every package in a program must have a unique import path.
  2602  // By convention, this is arranged by starting each path with a
  2603  // unique prefix that belongs to you. For example, paths used
  2604  // internally at Google all begin with 'google', and paths
  2605  // denoting remote repositories begin with the path to the code,
  2606  // such as 'github.com/user/repo'.
  2607  //
  2608  // Packages in a program need not have unique package names,
  2609  // but there are two reserved package names with special meaning.
  2610  // The name main indicates a command, not a library.
  2611  // Commands are built into binaries and cannot be imported.
  2612  // The name documentation indicates documentation for
  2613  // a non-Go program in the directory. Files in package documentation
  2614  // are ignored by the go command.
  2615  //
  2616  // As a special case, if the package list is a list of .go files from a
  2617  // single directory, the command is applied to a single synthesized
  2618  // package made up of exactly those files, ignoring any build constraints
  2619  // in those files and ignoring any other files in the directory.
  2620  //
  2621  // Directory and file names that begin with "." or "_" are ignored
  2622  // by the go tool, as are directories named "testdata".
  2623  //
  2624  //
  2625  // Testing flags
  2626  //
  2627  // The 'go test' command takes both flags that apply to 'go test' itself
  2628  // and flags that apply to the resulting test binary.
  2629  //
  2630  // Several of the flags control profiling and write an execution profile
  2631  // suitable for "go tool pprof"; run "go tool pprof -h" for more
  2632  // information. The --alloc_space, --alloc_objects, and --show_bytes
  2633  // options of pprof control how the information is presented.
  2634  //
  2635  // The following flags are recognized by the 'go test' command and
  2636  // control the execution of any test:
  2637  //
  2638  // 	-bench regexp
  2639  // 	    Run only those benchmarks matching a regular expression.
  2640  // 	    By default, no benchmarks are run.
  2641  // 	    To run all benchmarks, use '-bench .' or '-bench=.'.
  2642  // 	    The regular expression is split by unbracketed slash (/)
  2643  // 	    characters into a sequence of regular expressions, and each
  2644  // 	    part of a benchmark's identifier must match the corresponding
  2645  // 	    element in the sequence, if any. Possible parents of matches
  2646  // 	    are run with b.N=1 to identify sub-benchmarks. For example,
  2647  // 	    given -bench=X/Y, top-level benchmarks matching X are run
  2648  // 	    with b.N=1 to find any sub-benchmarks matching Y, which are
  2649  // 	    then run in full.
  2650  //
  2651  // 	-benchtime t
  2652  // 	    Run enough iterations of each benchmark to take t, specified
  2653  // 	    as a time.Duration (for example, -benchtime 1h30s).
  2654  // 	    The default is 1 second (1s).
  2655  //
  2656  // 	-count n
  2657  // 	    Run each test and benchmark n times (default 1).
  2658  // 	    If -cpu is set, run n times for each GOMAXPROCS value.
  2659  // 	    Examples are always run once.
  2660  //
  2661  // 	-cover
  2662  // 	    Enable coverage analysis.
  2663  // 	    Note that because coverage works by annotating the source
  2664  // 	    code before compilation, compilation and test failures with
  2665  // 	    coverage enabled may report line numbers that don't correspond
  2666  // 	    to the original sources.
  2667  //
  2668  // 	-covermode set,count,atomic
  2669  // 	    Set the mode for coverage analysis for the package[s]
  2670  // 	    being tested. The default is "set" unless -race is enabled,
  2671  // 	    in which case it is "atomic".
  2672  // 	    The values:
  2673  // 		set: bool: does this statement run?
  2674  // 		count: int: how many times does this statement run?
  2675  // 		atomic: int: count, but correct in multithreaded tests;
  2676  // 			significantly more expensive.
  2677  // 	    Sets -cover.
  2678  //
  2679  // 	-coverpkg pattern1,pattern2,pattern3
  2680  // 	    Apply coverage analysis in each test to packages matching the patterns.
  2681  // 	    The default is for each test to analyze only the package being tested.
  2682  // 	    See 'go help packages' for a description of package patterns.
  2683  // 	    Sets -cover.
  2684  //
  2685  // 	-cpu 1,2,4
  2686  // 	    Specify a list of GOMAXPROCS values for which the tests or
  2687  // 	    benchmarks should be executed. The default is the current value
  2688  // 	    of GOMAXPROCS.
  2689  //
  2690  // 	-failfast
  2691  // 	    Do not start new tests after the first test failure.
  2692  //
  2693  // 	-list regexp
  2694  // 	    List tests, benchmarks, or examples matching the regular expression.
  2695  // 	    No tests, benchmarks or examples will be run. This will only
  2696  // 	    list top-level tests. No subtest or subbenchmarks will be shown.
  2697  //
  2698  // 	-parallel n
  2699  // 	    Allow parallel execution of test functions that call t.Parallel.
  2700  // 	    The value of this flag is the maximum number of tests to run
  2701  // 	    simultaneously; by default, it is set to the value of GOMAXPROCS.
  2702  // 	    Note that -parallel only applies within a single test binary.
  2703  // 	    The 'go test' command may run tests for different packages
  2704  // 	    in parallel as well, according to the setting of the -p flag
  2705  // 	    (see 'go help build').
  2706  //
  2707  // 	-run regexp
  2708  // 	    Run only those tests and examples matching the regular expression.
  2709  // 	    For tests, the regular expression is split by unbracketed slash (/)
  2710  // 	    characters into a sequence of regular expressions, and each part
  2711  // 	    of a test's identifier must match the corresponding element in
  2712  // 	    the sequence, if any. Note that possible parents of matches are
  2713  // 	    run too, so that -run=X/Y matches and runs and reports the result
  2714  // 	    of all tests matching X, even those without sub-tests matching Y,
  2715  // 	    because it must run them to look for those sub-tests.
  2716  //
  2717  // 	-short
  2718  // 	    Tell long-running tests to shorten their run time.
  2719  // 	    It is off by default but set during all.bash so that installing
  2720  // 	    the Go tree can run a sanity check but not spend time running
  2721  // 	    exhaustive tests.
  2722  //
  2723  // 	-timeout d
  2724  // 	    If a test binary runs longer than duration d, panic.
  2725  // 	    If d is 0, the timeout is disabled.
  2726  // 	    The default is 10 minutes (10m).
  2727  //
  2728  // 	-v
  2729  // 	    Verbose output: log all tests as they are run. Also print all
  2730  // 	    text from Log and Logf calls even if the test succeeds.
  2731  //
  2732  // 	-vet list
  2733  // 	    Configure the invocation of "go vet" during "go test"
  2734  // 	    to use the comma-separated list of vet checks.
  2735  // 	    If list is empty, "go test" runs "go vet" with a curated list of
  2736  // 	    checks believed to be always worth addressing.
  2737  // 	    If list is "off", "go test" does not run "go vet" at all.
  2738  //
  2739  // The following flags are also recognized by 'go test' and can be used to
  2740  // profile the tests during execution:
  2741  //
  2742  // 	-benchmem
  2743  // 	    Print memory allocation statistics for benchmarks.
  2744  //
  2745  // 	-blockprofile block.out
  2746  // 	    Write a goroutine blocking profile to the specified file
  2747  // 	    when all tests are complete.
  2748  // 	    Writes test binary as -c would.
  2749  //
  2750  // 	-blockprofilerate n
  2751  // 	    Control the detail provided in goroutine blocking profiles by
  2752  // 	    calling runtime.SetBlockProfileRate with n.
  2753  // 	    See 'go doc runtime.SetBlockProfileRate'.
  2754  // 	    The profiler aims to sample, on average, one blocking event every
  2755  // 	    n nanoseconds the program spends blocked. By default,
  2756  // 	    if -test.blockprofile is set without this flag, all blocking events
  2757  // 	    are recorded, equivalent to -test.blockprofilerate=1.
  2758  //
  2759  // 	-coverprofile cover.out
  2760  // 	    Write a coverage profile to the file after all tests have passed.
  2761  // 	    Sets -cover.
  2762  //
  2763  // 	-cpuprofile cpu.out
  2764  // 	    Write a CPU profile to the specified file before exiting.
  2765  // 	    Writes test binary as -c would.
  2766  //
  2767  // 	-memprofile mem.out
  2768  // 	    Write an allocation profile to the file after all tests have passed.
  2769  // 	    Writes test binary as -c would.
  2770  //
  2771  // 	-memprofilerate n
  2772  // 	    Enable more precise (and expensive) memory allocation profiles by
  2773  // 	    setting runtime.MemProfileRate. See 'go doc runtime.MemProfileRate'.
  2774  // 	    To profile all memory allocations, use -test.memprofilerate=1.
  2775  //
  2776  // 	-mutexprofile mutex.out
  2777  // 	    Write a mutex contention profile to the specified file
  2778  // 	    when all tests are complete.
  2779  // 	    Writes test binary as -c would.
  2780  //
  2781  // 	-mutexprofilefraction n
  2782  // 	    Sample 1 in n stack traces of goroutines holding a
  2783  // 	    contended mutex.
  2784  //
  2785  // 	-outputdir directory
  2786  // 	    Place output files from profiling in the specified directory,
  2787  // 	    by default the directory in which "go test" is running.
  2788  //
  2789  // 	-trace trace.out
  2790  // 	    Write an execution trace to the specified file before exiting.
  2791  //
  2792  // Each of these flags is also recognized with an optional 'test.' prefix,
  2793  // as in -test.v. When invoking the generated test binary (the result of
  2794  // 'go test -c') directly, however, the prefix is mandatory.
  2795  //
  2796  // The 'go test' command rewrites or removes recognized flags,
  2797  // as appropriate, both before and after the optional package list,
  2798  // before invoking the test binary.
  2799  //
  2800  // For instance, the command
  2801  //
  2802  // 	go test -v -myflag testdata -cpuprofile=prof.out -x
  2803  //
  2804  // will compile the test binary and then run it as
  2805  //
  2806  // 	pkg.test -test.v -myflag testdata -test.cpuprofile=prof.out
  2807  //
  2808  // (The -x flag is removed because it applies only to the go command's
  2809  // execution, not to the test itself.)
  2810  //
  2811  // The test flags that generate profiles (other than for coverage) also
  2812  // leave the test binary in pkg.test for use when analyzing the profiles.
  2813  //
  2814  // When 'go test' runs a test binary, it does so from within the
  2815  // corresponding package's source code directory. Depending on the test,
  2816  // it may be necessary to do the same when invoking a generated test
  2817  // binary directly.
  2818  //
  2819  // The command-line package list, if present, must appear before any
  2820  // flag not known to the go test command. Continuing the example above,
  2821  // the package list would have to appear before -myflag, but could appear
  2822  // on either side of -v.
  2823  //
  2824  // When 'go test' runs in package list mode, 'go test' caches successful
  2825  // package test results to avoid unnecessary repeated running of tests. To
  2826  // disable test caching, use any test flag or argument other than the
  2827  // cacheable flags. The idiomatic way to disable test caching explicitly
  2828  // is to use -count=1.
  2829  //
  2830  // To keep an argument for a test binary from being interpreted as a
  2831  // known flag or a package name, use -args (see 'go help test') which
  2832  // passes the remainder of the command line through to the test binary
  2833  // uninterpreted and unaltered.
  2834  //
  2835  // For instance, the command
  2836  //
  2837  // 	go test -v -args -x -v
  2838  //
  2839  // will compile the test binary and then run it as
  2840  //
  2841  // 	pkg.test -test.v -x -v
  2842  //
  2843  // Similarly,
  2844  //
  2845  // 	go test -args math
  2846  //
  2847  // will compile the test binary and then run it as
  2848  //
  2849  // 	pkg.test math
  2850  //
  2851  // In the first example, the -x and the second -v are passed through to the
  2852  // test binary unchanged and with no effect on the go command itself.
  2853  // In the second example, the argument math is passed through to the test
  2854  // binary, instead of being interpreted as the package list.
  2855  //
  2856  //
  2857  // Testing functions
  2858  //
  2859  // The 'go test' command expects to find test, benchmark, and example functions
  2860  // in the "*_test.go" files corresponding to the package under test.
  2861  //
  2862  // A test function is one named TestXxx (where Xxx does not start with a
  2863  // lower case letter) and should have the signature,
  2864  //
  2865  // 	func TestXxx(t *testing.T) { ... }
  2866  //
  2867  // A benchmark function is one named BenchmarkXxx and should have the signature,
  2868  //
  2869  // 	func BenchmarkXxx(b *testing.B) { ... }
  2870  //
  2871  // An example function is similar to a test function but, instead of using
  2872  // *testing.T to report success or failure, prints output to os.Stdout.
  2873  // If the last comment in the function starts with "Output:" then the output
  2874  // is compared exactly against the comment (see examples below). If the last
  2875  // comment begins with "Unordered output:" then the output is compared to the
  2876  // comment, however the order of the lines is ignored. An example with no such
  2877  // comment is compiled but not executed. An example with no text after
  2878  // "Output:" is compiled, executed, and expected to produce no output.
  2879  //
  2880  // Godoc displays the body of ExampleXxx to demonstrate the use
  2881  // of the function, constant, or variable Xxx. An example of a method M with
  2882  // receiver type T or *T is named ExampleT_M. There may be multiple examples
  2883  // for a given function, constant, or variable, distinguished by a trailing _xxx,
  2884  // where xxx is a suffix not beginning with an upper case letter.
  2885  //
  2886  // Here is an example of an example:
  2887  //
  2888  // 	func ExamplePrintln() {
  2889  // 		Println("The output of\nthis example.")
  2890  // 		// Output: The output of
  2891  // 		// this example.
  2892  // 	}
  2893  //
  2894  // Here is another example where the ordering of the output is ignored:
  2895  //
  2896  // 	func ExamplePerm() {
  2897  // 		for _, value := range Perm(4) {
  2898  // 			fmt.Println(value)
  2899  // 		}
  2900  //
  2901  // 		// Unordered output: 4
  2902  // 		// 2
  2903  // 		// 1
  2904  // 		// 3
  2905  // 		// 0
  2906  // 	}
  2907  //
  2908  // The entire test file is presented as the example when it contains a single
  2909  // example function, at least one other function, type, variable, or constant
  2910  // declaration, and no test or benchmark functions.
  2911  //
  2912  // See the documentation of the testing package for more information.
  2913  //
  2914  //
  2915  package main
  2916  

View as plain text