...
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  // DO NOT EDIT THIS FILE. GENERATED BY mkalldocs.sh.
     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  // 	build       compile packages and dependencies
    17  // 	clean       remove object files and cached files
    18  // 	doc         show documentation for package or symbol
    19  // 	env         print Go environment information
    20  // 	bug         start a bug report
    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
    27  // 	run         compile and run Go program
    28  // 	test        test packages
    29  // 	tool        run specified go tool
    30  // 	version     print Go version
    31  // 	vet         report likely mistakes in packages
    32  //
    33  // Use "go help [command]" for more information about a command.
    34  //
    35  // Additional help topics:
    36  //
    37  // 	c           calling between Go and C
    38  // 	buildmode   build modes
    39  // 	cache       build and test caching
    40  // 	filetype    file types
    41  // 	gopath      GOPATH environment variable
    42  // 	environment environment variables
    43  // 	importpath  import path syntax
    44  // 	packages    package lists
    45  // 	testflag    testing flags
    46  // 	testfunc    testing functions
    47  //
    48  // Use "go help [topic]" for more information about that topic.
    49  //
    50  //
    51  // Compile packages and dependencies
    52  //
    53  // Usage:
    54  //
    55  // 	go build [-o output] [-i] [build flags] [packages]
    56  //
    57  // Build compiles the packages named by the import paths,
    58  // along with their dependencies, but it does not install the results.
    59  //
    60  // If the arguments to build are a list of .go files, build treats
    61  // them as a list of source files specifying a single package.
    62  //
    63  // When compiling a single main package, build writes
    64  // the resulting executable to an output file named after
    65  // the first source file ('go build ed.go rx.go' writes 'ed' or 'ed.exe')
    66  // or the source code directory ('go build unix/sam' writes 'sam' or 'sam.exe').
    67  // The '.exe' suffix is added when writing a Windows executable.
    68  //
    69  // When compiling multiple packages or a single non-main package,
    70  // build compiles the packages but discards the resulting object,
    71  // serving only as a check that the packages can be built.
    72  //
    73  // When compiling packages, build ignores files that end in '_test.go'.
    74  //
    75  // The -o flag, only allowed when compiling a single package,
    76  // forces build to write the resulting executable or object
    77  // to the named output file, instead of the default behavior described
    78  // in the last two paragraphs.
    79  //
    80  // The -i flag installs the packages that are dependencies of the target.
    81  //
    82  // The build flags are shared by the build, clean, get, install, list, run,
    83  // and test commands:
    84  //
    85  // 	-a
    86  // 		force rebuilding of packages that are already up-to-date.
    87  // 	-n
    88  // 		print the commands but do not run them.
    89  // 	-p n
    90  // 		the number of programs, such as build commands or
    91  // 		test binaries, that can be run in parallel.
    92  // 		The default is the number of CPUs available.
    93  // 	-race
    94  // 		enable data race detection.
    95  // 		Supported only on linux/amd64, freebsd/amd64, darwin/amd64 and windows/amd64.
    96  // 	-msan
    97  // 		enable interoperation with memory sanitizer.
    98  // 		Supported only on linux/amd64,
    99  // 		and only with Clang/LLVM as the host C compiler.
   100  // 	-v
   101  // 		print the names of packages as they are compiled.
   102  // 	-work
   103  // 		print the name of the temporary work directory and
   104  // 		do not delete it when exiting.
   105  // 	-x
   106  // 		print the commands.
   107  //
   108  // 	-asmflags '[pattern=]arg list'
   109  // 		arguments to pass on each go tool asm invocation.
   110  // 	-buildmode mode
   111  // 		build mode to use. See 'go help buildmode' for more.
   112  // 	-compiler name
   113  // 		name of compiler to use, as in runtime.Compiler (gccgo or gc).
   114  // 	-gccgoflags '[pattern=]arg list'
   115  // 		arguments to pass on each gccgo compiler/linker invocation.
   116  // 	-gcflags '[pattern=]arg list'
   117  // 		arguments to pass on each go tool compile invocation.
   118  // 	-installsuffix suffix
   119  // 		a suffix to use in the name of the package installation directory,
   120  // 		in order to keep output separate from default builds.
   121  // 		If using the -race flag, the install suffix is automatically set to race
   122  // 		or, if set explicitly, has _race appended to it. Likewise for the -msan
   123  // 		flag. Using a -buildmode option that requires non-default compile flags
   124  // 		has a similar effect.
   125  // 	-ldflags '[pattern=]arg list'
   126  // 		arguments to pass on each go tool link invocation.
   127  // 	-linkshared
   128  // 		link against shared libraries previously created with
   129  // 		-buildmode=shared.
   130  // 	-pkgdir dir
   131  // 		install and load all packages from dir instead of the usual locations.
   132  // 		For example, when building with a non-standard configuration,
   133  // 		use -pkgdir to keep generated packages in a separate location.
   134  // 	-tags 'tag list'
   135  // 		a space-separated list of build tags to consider satisfied during the
   136  // 		build. For more information about build tags, see the description of
   137  // 		build constraints in the documentation for the go/build package.
   138  // 	-toolexec 'cmd args'
   139  // 		a program to use to invoke toolchain programs like vet and asm.
   140  // 		For example, instead of running asm, the go command will run
   141  // 		'cmd args /path/to/asm <arguments for asm>'.
   142  //
   143  // The -asmflags, -gccgoflags, -gcflags, and -ldflags flags accept a
   144  // space-separated list of arguments to pass to an underlying tool
   145  // during the build. To embed spaces in an element in the list, surround
   146  // it with either single or double quotes. The argument list may be
   147  // preceded by a package pattern and an equal sign, which restricts
   148  // the use of that argument list to the building of packages matching
   149  // that pattern (see 'go help packages' for a description of package
   150  // patterns). Without a pattern, the argument list applies only to the
   151  // packages named on the command line. The flags may be repeated
   152  // with different patterns in order to specify different arguments for
   153  // different sets of packages. If a package matches patterns given in
   154  // multiple flags, the latest match on the command line wins.
   155  // For example, 'go build -gcflags=-S fmt' prints the disassembly
   156  // only for package fmt, while 'go build -gcflags=all=-S fmt'
   157  // prints the disassembly for fmt and all its dependencies.
   158  //
   159  // For more about specifying packages, see 'go help packages'.
   160  // For more about where packages and binaries are installed,
   161  // run 'go help gopath'.
   162  // For more about calling between Go and C/C++, run 'go help c'.
   163  //
   164  // Note: Build adheres to certain conventions such as those described
   165  // by 'go help gopath'. Not all projects can follow these conventions,
   166  // however. Installations that have their own conventions or that use
   167  // a separate software build system may choose to use lower-level
   168  // invocations such as 'go tool compile' and 'go tool link' to avoid
   169  // some of the overheads and design decisions of the build tool.
   170  //
   171  // See also: go install, go get, go clean.
   172  //
   173  //
   174  // Remove object files and cached files
   175  //
   176  // Usage:
   177  //
   178  // 	go clean [-i] [-r] [-n] [-x] [-cache] [-testcache] [build flags] [packages]
   179  //
   180  // Clean removes object files from package source directories.
   181  // The go command builds most objects in a temporary directory,
   182  // so go clean is mainly concerned with object files left by other
   183  // tools or by manual invocations of go build.
   184  //
   185  // Specifically, clean removes the following files from each of the
   186  // source directories corresponding to the import paths:
   187  //
   188  // 	_obj/            old object directory, left from Makefiles
   189  // 	_test/           old test directory, left from Makefiles
   190  // 	_testmain.go     old gotest file, left from Makefiles
   191  // 	test.out         old test log, left from Makefiles
   192  // 	build.out        old test log, left from Makefiles
   193  // 	*.[568ao]        object files, left from Makefiles
   194  //
   195  // 	DIR(.exe)        from go build
   196  // 	DIR.test(.exe)   from go test -c
   197  // 	MAINFILE(.exe)   from go build MAINFILE.go
   198  // 	*.so             from SWIG
   199  //
   200  // In the list, DIR represents the final path element of the
   201  // directory, and MAINFILE is the base name of any Go source
   202  // file in the directory that is not included when building
   203  // the package.
   204  //
   205  // The -i flag causes clean to remove the corresponding installed
   206  // archive or binary (what 'go install' would create).
   207  //
   208  // The -n flag causes clean to print the remove commands it would execute,
   209  // but not run them.
   210  //
   211  // The -r flag causes clean to be applied recursively to all the
   212  // dependencies of the packages named by the import paths.
   213  //
   214  // The -x flag causes clean to print remove commands as it executes them.
   215  //
   216  // The -cache flag causes clean to remove the entire go build cache.
   217  //
   218  // The -testcache flag causes clean to expire all test results in the
   219  // go build cache.
   220  //
   221  // For more about build flags, see 'go help build'.
   222  //
   223  // For more about specifying packages, see 'go help packages'.
   224  //
   225  //
   226  // Show documentation for package or symbol
   227  //
   228  // Usage:
   229  //
   230  // 	go doc [-u] [-c] [package|[package.]symbol[.methodOrField]]
   231  //
   232  // Doc prints the documentation comments associated with the item identified by its
   233  // arguments (a package, const, func, type, var, method, or struct field)
   234  // followed by a one-line summary of each of the first-level items "under"
   235  // that item (package-level declarations for a package, methods for a type,
   236  // etc.).
   237  //
   238  // Doc accepts zero, one, or two arguments.
   239  //
   240  // Given no arguments, that is, when run as
   241  //
   242  // 	go doc
   243  //
   244  // it prints the package documentation for the package in the current directory.
   245  // If the package is a command (package main), the exported symbols of the package
   246  // are elided from the presentation unless the -cmd flag is provided.
   247  //
   248  // When run with one argument, the argument is treated as a Go-syntax-like
   249  // representation of the item to be documented. What the argument selects depends
   250  // on what is installed in GOROOT and GOPATH, as well as the form of the argument,
   251  // which is schematically one of these:
   252  //
   253  // 	go doc <pkg>
   254  // 	go doc <sym>[.<methodOrField>]
   255  // 	go doc [<pkg>.]<sym>[.<methodOrField>]
   256  // 	go doc [<pkg>.][<sym>.]<methodOrField>
   257  //
   258  // The first item in this list matched by the argument is the one whose documentation
   259  // is printed. (See the examples below.) However, if the argument starts with a capital
   260  // letter it is assumed to identify a symbol or method in the current directory.
   261  //
   262  // For packages, the order of scanning is determined lexically in breadth-first order.
   263  // That is, the package presented is the one that matches the search and is nearest
   264  // the root and lexically first at its level of the hierarchy. The GOROOT tree is
   265  // always scanned in its entirety before GOPATH.
   266  //
   267  // If there is no package specified or matched, the package in the current
   268  // directory is selected, so "go doc Foo" shows the documentation for symbol Foo in
   269  // the current package.
   270  //
   271  // The package path must be either a qualified path or a proper suffix of a
   272  // path. The go tool's usual package mechanism does not apply: package path
   273  // elements like . and ... are not implemented by go doc.
   274  //
   275  // When run with two arguments, the first must be a full package path (not just a
   276  // suffix), and the second is a symbol, or symbol with method or struct field.
   277  // This is similar to the syntax accepted by godoc:
   278  //
   279  // 	go doc <pkg> <sym>[.<methodOrField>]
   280  //
   281  // In all forms, when matching symbols, lower-case letters in the argument match
   282  // either case but upper-case letters match exactly. This means that there may be
   283  // multiple matches of a lower-case argument in a package if different symbols have
   284  // different cases. If this occurs, documentation for all matches is printed.
   285  //
   286  // Examples:
   287  // 	go doc
   288  // 		Show documentation for current package.
   289  // 	go doc Foo
   290  // 		Show documentation for Foo in the current package.
   291  // 		(Foo starts with a capital letter so it cannot match
   292  // 		a package path.)
   293  // 	go doc encoding/json
   294  // 		Show documentation for the encoding/json package.
   295  // 	go doc json
   296  // 		Shorthand for encoding/json.
   297  // 	go doc json.Number (or go doc json.number)
   298  // 		Show documentation and method summary for json.Number.
   299  // 	go doc json.Number.Int64 (or go doc json.number.int64)
   300  // 		Show documentation for json.Number's Int64 method.
   301  // 	go doc cmd/doc
   302  // 		Show package docs for the doc command.
   303  // 	go doc -cmd cmd/doc
   304  // 		Show package docs and exported symbols within the doc command.
   305  // 	go doc template.new
   306  // 		Show documentation for html/template's New function.
   307  // 		(html/template is lexically before text/template)
   308  // 	go doc text/template.new # One argument
   309  // 		Show documentation for text/template's New function.
   310  // 	go doc text/template new # Two arguments
   311  // 		Show documentation for text/template's New function.
   312  //
   313  // 	At least in the current tree, these invocations all print the
   314  // 	documentation for json.Decoder's Decode method:
   315  //
   316  // 	go doc json.Decoder.Decode
   317  // 	go doc json.decoder.decode
   318  // 	go doc json.decode
   319  // 	cd go/src/encoding/json; go doc decode
   320  //
   321  // Flags:
   322  // 	-c
   323  // 		Respect case when matching symbols.
   324  // 	-cmd
   325  // 		Treat a command (package main) like a regular package.
   326  // 		Otherwise package main's exported symbols are hidden
   327  // 		when showing the package's top-level documentation.
   328  // 	-u
   329  // 		Show documentation for unexported as well as exported
   330  // 		symbols, methods, and fields.
   331  //
   332  //
   333  // Print Go environment information
   334  //
   335  // Usage:
   336  //
   337  // 	go env [-json] [var ...]
   338  //
   339  // Env prints Go environment information.
   340  //
   341  // By default env prints information as a shell script
   342  // (on Windows, a batch file). If one or more variable
   343  // names is given as arguments, env prints the value of
   344  // each named variable on its own line.
   345  //
   346  // The -json flag prints the environment in JSON format
   347  // instead of as a shell script.
   348  //
   349  // For more about environment variables, see 'go help environment'.
   350  //
   351  //
   352  // Start a bug report
   353  //
   354  // Usage:
   355  //
   356  // 	go bug
   357  //
   358  // Bug opens the default browser and starts a new bug report.
   359  // The report includes useful system information.
   360  //
   361  //
   362  // Update packages to use new APIs
   363  //
   364  // Usage:
   365  //
   366  // 	go fix [packages]
   367  //
   368  // Fix runs the Go fix command on the packages named by the import paths.
   369  //
   370  // For more about fix, see 'go doc cmd/fix'.
   371  // For more about specifying packages, see 'go help packages'.
   372  //
   373  // To run fix with specific options, run 'go tool fix'.
   374  //
   375  // See also: go fmt, go vet.
   376  //
   377  //
   378  // Gofmt (reformat) package sources
   379  //
   380  // Usage:
   381  //
   382  // 	go fmt [-n] [-x] [packages]
   383  //
   384  // Fmt runs the command 'gofmt -l -w' on the packages named
   385  // by the import paths. It prints the names of the files that are modified.
   386  //
   387  // For more about gofmt, see 'go doc cmd/gofmt'.
   388  // For more about specifying packages, see 'go help packages'.
   389  //
   390  // The -n flag prints commands that would be executed.
   391  // The -x flag prints commands as they are executed.
   392  //
   393  // To run gofmt with specific options, run gofmt itself.
   394  //
   395  // See also: go fix, go vet.
   396  //
   397  //
   398  // Generate Go files by processing source
   399  //
   400  // Usage:
   401  //
   402  // 	go generate [-run regexp] [-n] [-v] [-x] [build flags] [file.go... | packages]
   403  //
   404  // Generate runs commands described by directives within existing
   405  // files. Those commands can run any process but the intent is to
   406  // create or update Go source files.
   407  //
   408  // Go generate is never run automatically by go build, go get, go test,
   409  // and so on. It must be run explicitly.
   410  //
   411  // Go generate scans the file for directives, which are lines of
   412  // the form,
   413  //
   414  // 	//go:generate command argument...
   415  //
   416  // (note: no leading spaces and no space in "//go") where command
   417  // is the generator to be run, corresponding to an executable file
   418  // that can be run locally. It must either be in the shell path
   419  // (gofmt), a fully qualified path (/usr/you/bin/mytool), or a
   420  // command alias, described below.
   421  //
   422  // Note that go generate does not parse the file, so lines that look
   423  // like directives in comments or multiline strings will be treated
   424  // as directives.
   425  //
   426  // The arguments to the directive are space-separated tokens or
   427  // double-quoted strings passed to the generator as individual
   428  // arguments when it is run.
   429  //
   430  // Quoted strings use Go syntax and are evaluated before execution; a
   431  // quoted string appears as a single argument to the generator.
   432  //
   433  // Go generate sets several variables when it runs the generator:
   434  //
   435  // 	$GOARCH
   436  // 		The execution architecture (arm, amd64, etc.)
   437  // 	$GOOS
   438  // 		The execution operating system (linux, windows, etc.)
   439  // 	$GOFILE
   440  // 		The base name of the file.
   441  // 	$GOLINE
   442  // 		The line number of the directive in the source file.
   443  // 	$GOPACKAGE
   444  // 		The name of the package of the file containing the directive.
   445  // 	$DOLLAR
   446  // 		A dollar sign.
   447  //
   448  // Other than variable substitution and quoted-string evaluation, no
   449  // special processing such as "globbing" is performed on the command
   450  // line.
   451  //
   452  // As a last step before running the command, any invocations of any
   453  // environment variables with alphanumeric names, such as $GOFILE or
   454  // $HOME, are expanded throughout the command line. The syntax for
   455  // variable expansion is $NAME on all operating systems. Due to the
   456  // order of evaluation, variables are expanded even inside quoted
   457  // strings. If the variable NAME is not set, $NAME expands to the
   458  // empty string.
   459  //
   460  // A directive of the form,
   461  //
   462  // 	//go:generate -command xxx args...
   463  //
   464  // specifies, for the remainder of this source file only, that the
   465  // string xxx represents the command identified by the arguments. This
   466  // can be used to create aliases or to handle multiword generators.
   467  // For example,
   468  //
   469  // 	//go:generate -command foo go tool foo
   470  //
   471  // specifies that the command "foo" represents the generator
   472  // "go tool foo".
   473  //
   474  // Generate processes packages in the order given on the command line,
   475  // one at a time. If the command line lists .go files, they are treated
   476  // as a single package. Within a package, generate processes the
   477  // source files in a package in file name order, one at a time. Within
   478  // a source file, generate runs generators in the order they appear
   479  // in the file, one at a time.
   480  //
   481  // If any generator returns an error exit status, "go generate" skips
   482  // all further processing for that package.
   483  //
   484  // The generator is run in the package's source directory.
   485  //
   486  // Go generate accepts one specific flag:
   487  //
   488  // 	-run=""
   489  // 		if non-empty, specifies a regular expression to select
   490  // 		directives whose full original source text (excluding
   491  // 		any trailing spaces and final newline) matches the
   492  // 		expression.
   493  //
   494  // It also accepts the standard build flags including -v, -n, and -x.
   495  // The -v flag prints the names of packages and files as they are
   496  // processed.
   497  // The -n flag prints commands that would be executed.
   498  // The -x flag prints commands as they are executed.
   499  //
   500  // For more about build flags, see 'go help build'.
   501  //
   502  // For more about specifying packages, see 'go help packages'.
   503  //
   504  //
   505  // Download and install packages and dependencies
   506  //
   507  // Usage:
   508  //
   509  // 	go get [-d] [-f] [-fix] [-insecure] [-t] [-u] [-v] [build flags] [packages]
   510  //
   511  // Get downloads the packages named by the import paths, along with their
   512  // dependencies. It then installs the named packages, like 'go install'.
   513  //
   514  // The -d flag instructs get to stop after downloading the packages; that is,
   515  // it instructs get not to install the packages.
   516  //
   517  // The -f flag, valid only when -u is set, forces get -u not to verify that
   518  // each package has been checked out from the source control repository
   519  // implied by its import path. This can be useful if the source is a local fork
   520  // of the original.
   521  //
   522  // The -fix flag instructs get to run the fix tool on the downloaded packages
   523  // before resolving dependencies or building the code.
   524  //
   525  // The -insecure flag permits fetching from repositories and resolving
   526  // custom domains using insecure schemes such as HTTP. Use with caution.
   527  //
   528  // The -t flag instructs get to also download the packages required to build
   529  // the tests for the specified packages.
   530  //
   531  // The -u flag instructs get to use the network to update the named packages
   532  // and their dependencies. By default, get uses the network to check out
   533  // missing packages but does not use it to look for updates to existing packages.
   534  //
   535  // The -v flag enables verbose progress and debug output.
   536  //
   537  // Get also accepts build flags to control the installation. See 'go help build'.
   538  //
   539  // When checking out a new package, get creates the target directory
   540  // GOPATH/src/<import-path>. If the GOPATH contains multiple entries,
   541  // get uses the first one. For more details see: 'go help gopath'.
   542  //
   543  // When checking out or updating a package, get looks for a branch or tag
   544  // that matches the locally installed version of Go. The most important
   545  // rule is that if the local installation is running version "go1", get
   546  // searches for a branch or tag named "go1". If no such version exists
   547  // it retrieves the default branch of the package.
   548  //
   549  // When go get checks out or updates a Git repository,
   550  // it also updates any git submodules referenced by the repository.
   551  //
   552  // Get never checks out or updates code stored in vendor directories.
   553  //
   554  // For more about specifying packages, see 'go help packages'.
   555  //
   556  // For more about how 'go get' finds source code to
   557  // download, see 'go help importpath'.
   558  //
   559  // See also: go build, go install, go clean.
   560  //
   561  //
   562  // Compile and install packages and dependencies
   563  //
   564  // Usage:
   565  //
   566  // 	go install [-i] [build flags] [packages]
   567  //
   568  // Install compiles and installs the packages named by the import paths.
   569  //
   570  // The -i flag installs the dependencies of the named packages as well.
   571  //
   572  // For more about the build flags, see 'go help build'.
   573  // For more about specifying packages, see 'go help packages'.
   574  //
   575  // See also: go build, go get, go clean.
   576  //
   577  //
   578  // List packages
   579  //
   580  // Usage:
   581  //
   582  // 	go list [-e] [-f format] [-json] [build flags] [packages]
   583  //
   584  // List lists the packages named by the import paths, one per line.
   585  //
   586  // The default output shows the package import path:
   587  //
   588  //     bytes
   589  //     encoding/json
   590  //     github.com/gorilla/mux
   591  //     golang.org/x/net/html
   592  //
   593  // The -f flag specifies an alternate format for the list, using the
   594  // syntax of package template. The default output is equivalent to -f
   595  // '{{.ImportPath}}'. The struct being passed to the template is:
   596  //
   597  //     type Package struct {
   598  //         Dir           string // directory containing package sources
   599  //         ImportPath    string // import path of package in dir
   600  //         ImportComment string // path in import comment on package statement
   601  //         Name          string // package name
   602  //         Doc           string // package documentation string
   603  //         Target        string // install path
   604  //         Shlib         string // the shared library that contains this package (only set when -linkshared)
   605  //         Goroot        bool   // is this package in the Go root?
   606  //         Standard      bool   // is this package part of the standard Go library?
   607  //         Stale         bool   // would 'go install' do anything for this package?
   608  //         StaleReason   string // explanation for Stale==true
   609  //         Root          string // Go root or Go path dir containing this package
   610  //         ConflictDir   string // this directory shadows Dir in $GOPATH
   611  //         BinaryOnly    bool   // binary-only package: cannot be recompiled from sources
   612  //
   613  //         // Source files
   614  //         GoFiles        []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles)
   615  //         CgoFiles       []string // .go sources files that import "C"
   616  //         IgnoredGoFiles []string // .go sources ignored due to build constraints
   617  //         CFiles         []string // .c source files
   618  //         CXXFiles       []string // .cc, .cxx and .cpp source files
   619  //         MFiles         []string // .m source files
   620  //         HFiles         []string // .h, .hh, .hpp and .hxx source files
   621  //         FFiles         []string // .f, .F, .for and .f90 Fortran source files
   622  //         SFiles         []string // .s source files
   623  //         SwigFiles      []string // .swig files
   624  //         SwigCXXFiles   []string // .swigcxx files
   625  //         SysoFiles      []string // .syso object files to add to archive
   626  //         TestGoFiles    []string // _test.go files in package
   627  //         XTestGoFiles   []string // _test.go files outside package
   628  //
   629  //         // Cgo directives
   630  //         CgoCFLAGS    []string // cgo: flags for C compiler
   631  //         CgoCPPFLAGS  []string // cgo: flags for C preprocessor
   632  //         CgoCXXFLAGS  []string // cgo: flags for C++ compiler
   633  //         CgoFFLAGS    []string // cgo: flags for Fortran compiler
   634  //         CgoLDFLAGS   []string // cgo: flags for linker
   635  //         CgoPkgConfig []string // cgo: pkg-config names
   636  //
   637  //         // Dependency information
   638  //         Imports      []string // import paths used by this package
   639  //         Deps         []string // all (recursively) imported dependencies
   640  //         TestImports  []string // imports from TestGoFiles
   641  //         XTestImports []string // imports from XTestGoFiles
   642  //
   643  //         // Error information
   644  //         Incomplete bool            // this package or a dependency has an error
   645  //         Error      *PackageError   // error loading package
   646  //         DepsErrors []*PackageError // errors loading dependencies
   647  //     }
   648  //
   649  // Packages stored in vendor directories report an ImportPath that includes the
   650  // path to the vendor directory (for example, "d/vendor/p" instead of "p"),
   651  // so that the ImportPath uniquely identifies a given copy of a package.
   652  // The Imports, Deps, TestImports, and XTestImports lists also contain these
   653  // expanded imports paths. See golang.org/s/go15vendor for more about vendoring.
   654  //
   655  // The error information, if any, is
   656  //
   657  //     type PackageError struct {
   658  //         ImportStack   []string // shortest path from package named on command line to this one
   659  //         Pos           string   // position of error (if present, file:line:col)
   660  //         Err           string   // the error itself
   661  //     }
   662  //
   663  // The template function "join" calls strings.Join.
   664  //
   665  // The template function "context" returns the build context, defined as:
   666  //
   667  // 	type Context struct {
   668  // 		GOARCH        string   // target architecture
   669  // 		GOOS          string   // target operating system
   670  // 		GOROOT        string   // Go root
   671  // 		GOPATH        string   // Go path
   672  // 		CgoEnabled    bool     // whether cgo can be used
   673  // 		UseAllFiles   bool     // use files regardless of +build lines, file names
   674  // 		Compiler      string   // compiler to assume when computing target paths
   675  // 		BuildTags     []string // build constraints to match in +build lines
   676  // 		ReleaseTags   []string // releases the current release is compatible with
   677  // 		InstallSuffix string   // suffix to use in the name of the install dir
   678  // 	}
   679  //
   680  // For more information about the meaning of these fields see the documentation
   681  // for the go/build package's Context type.
   682  //
   683  // The -json flag causes the package data to be printed in JSON format
   684  // instead of using the template format.
   685  //
   686  // The -e flag changes the handling of erroneous packages, those that
   687  // cannot be found or are malformed. By default, the list command
   688  // prints an error to standard error for each erroneous package and
   689  // omits the packages from consideration during the usual printing.
   690  // With the -e flag, the list command never prints errors to standard
   691  // error and instead processes the erroneous packages with the usual
   692  // printing. Erroneous packages will have a non-empty ImportPath and
   693  // a non-nil Error field; other information may or may not be missing
   694  // (zeroed).
   695  //
   696  // For more about build flags, see 'go help build'.
   697  //
   698  // For more about specifying packages, see 'go help packages'.
   699  //
   700  //
   701  // Compile and run Go program
   702  //
   703  // Usage:
   704  //
   705  // 	go run [build flags] [-exec xprog] gofiles... [arguments...]
   706  //
   707  // Run compiles and runs the main package comprising the named Go source files.
   708  // A Go source file is defined to be a file ending in a literal ".go" suffix.
   709  //
   710  // By default, 'go run' runs the compiled binary directly: 'a.out arguments...'.
   711  // If the -exec flag is given, 'go run' invokes the binary using xprog:
   712  // 	'xprog a.out arguments...'.
   713  // If the -exec flag is not given, GOOS or GOARCH is different from the system
   714  // default, and a program named go_$GOOS_$GOARCH_exec can be found
   715  // on the current search path, 'go run' invokes the binary using that program,
   716  // for example 'go_nacl_386_exec a.out arguments...'. This allows execution of
   717  // cross-compiled programs when a simulator or other execution method is
   718  // available.
   719  //
   720  // For more about build flags, see 'go help build'.
   721  //
   722  // See also: go build.
   723  //
   724  //
   725  // Test packages
   726  //
   727  // Usage:
   728  //
   729  // 	go test [build/test flags] [packages] [build/test flags & test binary flags]
   730  //
   731  // 'Go test' automates testing the packages named by the import paths.
   732  // It prints a summary of the test results in the format:
   733  //
   734  // 	ok   archive/tar   0.011s
   735  // 	FAIL archive/zip   0.022s
   736  // 	ok   compress/gzip 0.033s
   737  // 	...
   738  //
   739  // followed by detailed output for each failed package.
   740  //
   741  // 'Go test' recompiles each package along with any files with names matching
   742  // the file pattern "*_test.go".
   743  // These additional files can contain test functions, benchmark functions, and
   744  // example functions. See 'go help testfunc' for more.
   745  // Each listed package causes the execution of a separate test binary.
   746  // Files whose names begin with "_" (including "_test.go") or "." are ignored.
   747  //
   748  // Test files that declare a package with the suffix "_test" will be compiled as a
   749  // separate package, and then linked and run with the main test binary.
   750  //
   751  // The go tool will ignore a directory named "testdata", making it available
   752  // to hold ancillary data needed by the tests.
   753  //
   754  // As part of building a test binary, go test runs go vet on the package
   755  // and its test source files to identify significant problems. If go vet
   756  // finds any problems, go test reports those and does not run the test binary.
   757  // Only a high-confidence subset of the default go vet checks are used.
   758  // To disable the running of go vet, use the -vet=off flag.
   759  //
   760  // All test output and summary lines are printed to the go command's
   761  // standard output, even if the test printed them to its own standard
   762  // error. (The go command's standard error is reserved for printing
   763  // errors building the tests.)
   764  //
   765  // Go test runs in two different modes:
   766  //
   767  // The first, called local directory mode, occurs when go test is
   768  // invoked with no package arguments (for example, 'go test' or 'go
   769  // test -v'). In this mode, go test compiles the package sources and
   770  // tests found in the current directory and then runs the resulting
   771  // test binary. In this mode, caching (discussed below) is disabled.
   772  // After the package test finishes, go test prints a summary line
   773  // showing the test status ('ok' or 'FAIL'), package name, and elapsed
   774  // time.
   775  //
   776  // The second, called package list mode, occurs when go test is invoked
   777  // with explicit package arguments (for example 'go test math', 'go
   778  // test ./...', and even 'go test .'). In this mode, go test compiles
   779  // and tests each of the packages listed on the command line. If a
   780  // package test passes, go test prints only the final 'ok' summary
   781  // line. If a package test fails, go test prints the full test output.
   782  // If invoked with the -bench or -v flag, go test prints the full
   783  // output even for passing package tests, in order to display the
   784  // requested benchmark results or verbose logging.
   785  //
   786  // In package list mode only, go test caches successful package test
   787  // results to avoid unnecessary repeated running of tests. When the
   788  // result of a test can be recovered from the cache, go test will
   789  // redisplay the previous output instead of running the test binary
   790  // again. When this happens, go test prints '(cached)' in place of the
   791  // elapsed time in the summary line.
   792  //
   793  // The rule for a match in the cache is that the run involves the same
   794  // test binary and the flags on the command line come entirely from a
   795  // restricted set of 'cacheable' test flags, defined as -cpu, -list,
   796  // -parallel, -run, -short, and -v. If a run of go test has any test
   797  // or non-test flags outside this set, the result is not cached. To
   798  // disable test caching, use any test flag or argument other than the
   799  // cacheable flags. The idiomatic way to disable test caching explicitly
   800  // is to use -count=1. Tests that open files within the package's source
   801  // root (usually $GOPATH) or that consult environment variables only
   802  // match future runs in which the files and environment variables are unchanged.
   803  // A cached test result is treated as executing in no time at all,
   804  // so a successful package test result will be cached and reused
   805  // regardless of -timeout setting.
   806  //
   807  // In addition to the build flags, the flags handled by 'go test' itself are:
   808  //
   809  // 	-args
   810  // 	    Pass the remainder of the command line (everything after -args)
   811  // 	    to the test binary, uninterpreted and unchanged.
   812  // 	    Because this flag consumes the remainder of the command line,
   813  // 	    the package list (if present) must appear before this flag.
   814  //
   815  // 	-c
   816  // 	    Compile the test binary to pkg.test but do not run it
   817  // 	    (where pkg is the last element of the package's import path).
   818  // 	    The file name can be changed with the -o flag.
   819  //
   820  // 	-exec xprog
   821  // 	    Run the test binary using xprog. The behavior is the same as
   822  // 	    in 'go run'. See 'go help run' for details.
   823  //
   824  // 	-i
   825  // 	    Install packages that are dependencies of the test.
   826  // 	    Do not run the test.
   827  //
   828  // 	-json
   829  // 	    Convert test output to JSON suitable for automated processing.
   830  // 	    See 'go doc test2json' for the encoding details.
   831  //
   832  // 	-o file
   833  // 	    Compile the test binary to the named file.
   834  // 	    The test still runs (unless -c or -i is specified).
   835  //
   836  // The test binary also accepts flags that control execution of the test; these
   837  // flags are also accessible by 'go test'. See 'go help testflag' for details.
   838  //
   839  // For more about build flags, see 'go help build'.
   840  // For more about specifying packages, see 'go help packages'.
   841  //
   842  // See also: go build, go vet.
   843  //
   844  //
   845  // Run specified go tool
   846  //
   847  // Usage:
   848  //
   849  // 	go tool [-n] command [args...]
   850  //
   851  // Tool runs the go tool command identified by the arguments.
   852  // With no arguments it prints the list of known tools.
   853  //
   854  // The -n flag causes tool to print the command that would be
   855  // executed but not execute it.
   856  //
   857  // For more about each tool command, see 'go doc cmd/<command>'.
   858  //
   859  //
   860  // Print Go version
   861  //
   862  // Usage:
   863  //
   864  // 	go version
   865  //
   866  // Version prints the Go version, as reported by runtime.Version.
   867  //
   868  //
   869  // Report likely mistakes in packages
   870  //
   871  // Usage:
   872  //
   873  // 	go vet [-n] [-x] [build flags] [vet flags] [packages]
   874  //
   875  // Vet runs the Go vet command on the packages named by the import paths.
   876  //
   877  // For more about vet and its flags, see 'go doc cmd/vet'.
   878  // For more about specifying packages, see 'go help packages'.
   879  //
   880  // The -n flag prints commands that would be executed.
   881  // The -x flag prints commands as they are executed.
   882  //
   883  // The build flags supported by go vet are those that control package resolution
   884  // and execution, such as -n, -x, -v, -tags, and -toolexec.
   885  // For more about these flags, see 'go help build'.
   886  //
   887  // See also: go fmt, go fix.
   888  //
   889  //
   890  // Calling between Go and C
   891  //
   892  // There are two different ways to call between Go and C/C++ code.
   893  //
   894  // The first is the cgo tool, which is part of the Go distribution. For
   895  // information on how to use it see the cgo documentation (go doc cmd/cgo).
   896  //
   897  // The second is the SWIG program, which is a general tool for
   898  // interfacing between languages. For information on SWIG see
   899  // http://swig.org/. When running go build, any file with a .swig
   900  // extension will be passed to SWIG. Any file with a .swigcxx extension
   901  // will be passed to SWIG with the -c++ option.
   902  //
   903  // When either cgo or SWIG is used, go build will pass any .c, .m, .s,
   904  // or .S files to the C compiler, and any .cc, .cpp, .cxx files to the C++
   905  // compiler. The CC or CXX environment variables may be set to determine
   906  // the C or C++ compiler, respectively, to use.
   907  //
   908  //
   909  // Build modes
   910  //
   911  // The 'go build' and 'go install' commands take a -buildmode argument which
   912  // indicates which kind of object file is to be built. Currently supported values
   913  // are:
   914  //
   915  // 	-buildmode=archive
   916  // 		Build the listed non-main packages into .a files. Packages named
   917  // 		main are ignored.
   918  //
   919  // 	-buildmode=c-archive
   920  // 		Build the listed main package, plus all packages it imports,
   921  // 		into a C archive file. The only callable symbols will be those
   922  // 		functions exported using a cgo //export comment. Requires
   923  // 		exactly one main package to be listed.
   924  //
   925  // 	-buildmode=c-shared
   926  // 		Build the listed main package, plus all packages it imports,
   927  // 		into a C shared library. The only callable symbols will
   928  // 		be those functions exported using a cgo //export comment.
   929  // 		Requires exactly one main package to be listed.
   930  //
   931  // 	-buildmode=default
   932  // 		Listed main packages are built into executables and listed
   933  // 		non-main packages are built into .a files (the default
   934  // 		behavior).
   935  //
   936  // 	-buildmode=shared
   937  // 		Combine all the listed non-main packages into a single shared
   938  // 		library that will be used when building with the -linkshared
   939  // 		option. Packages named main are ignored.
   940  //
   941  // 	-buildmode=exe
   942  // 		Build the listed main packages and everything they import into
   943  // 		executables. Packages not named main are ignored.
   944  //
   945  // 	-buildmode=pie
   946  // 		Build the listed main packages and everything they import into
   947  // 		position independent executables (PIE). Packages not named
   948  // 		main are ignored.
   949  //
   950  // 	-buildmode=plugin
   951  // 		Build the listed main packages, plus all packages that they
   952  // 		import, into a Go plugin. Packages not named main are ignored.
   953  //
   954  //
   955  // Build and test caching
   956  //
   957  // The go command caches build outputs for reuse in future builds.
   958  // The default location for cache data is a subdirectory named go-build
   959  // in the standard user cache directory for the current operating system.
   960  // Setting the GOCACHE environment variable overrides this default,
   961  // and running 'go env GOCACHE' prints the current cache directory.
   962  //
   963  // The go command periodically deletes cached data that has not been
   964  // used recently. Running 'go clean -cache' deletes all cached data.
   965  //
   966  // The build cache correctly accounts for changes to Go source files,
   967  // compilers, compiler options, and so on: cleaning the cache explicitly
   968  // should not be necessary in typical use. However, the build cache
   969  // does not detect changes to C libraries imported with cgo.
   970  // If you have made changes to the C libraries on your system, you
   971  // will need to clean the cache explicitly or else use the -a build flag
   972  // (see 'go help build') to force rebuilding of packages that
   973  // depend on the updated C libraries.
   974  //
   975  // The go command also caches successful package test results.
   976  // See 'go help test' for details. Running 'go clean -testcache' removes
   977  // all cached test results (but not cached build results).
   978  //
   979  // The GODEBUG environment variable can enable printing of debugging
   980  // information about the state of the cache:
   981  //
   982  // GODEBUG=gocacheverify=1 causes the go command to bypass the
   983  // use of any cache entries and instead rebuild everything and check
   984  // that the results match existing cache entries.
   985  //
   986  // GODEBUG=gocachehash=1 causes the go command to print the inputs
   987  // for all of the content hashes it uses to construct cache lookup keys.
   988  // The output is voluminous but can be useful for debugging the cache.
   989  //
   990  // GODEBUG=gocachetest=1 causes the go command to print details of its
   991  // decisions about whether to reuse a cached test result.
   992  //
   993  //
   994  // File types
   995  //
   996  // The go command examines the contents of a restricted set of files
   997  // in each directory. It identifies which files to examine based on
   998  // the extension of the file name. These extensions are:
   999  //
  1000  // 	.go
  1001  // 		Go source files.
  1002  // 	.c, .h
  1003  // 		C source files.
  1004  // 		If the package uses cgo or SWIG, these will be compiled with the
  1005  // 		OS-native compiler (typically gcc); otherwise they will
  1006  // 		trigger an error.
  1007  // 	.cc, .cpp, .cxx, .hh, .hpp, .hxx
  1008  // 		C++ source files. Only useful with cgo or SWIG, and always
  1009  // 		compiled with the OS-native compiler.
  1010  // 	.m
  1011  // 		Objective-C source files. Only useful with cgo, and always
  1012  // 		compiled with the OS-native compiler.
  1013  // 	.s, .S
  1014  // 		Assembler source files.
  1015  // 		If the package uses cgo or SWIG, these will be assembled with the
  1016  // 		OS-native assembler (typically gcc (sic)); otherwise they
  1017  // 		will be assembled with the Go assembler.
  1018  // 	.swig, .swigcxx
  1019  // 		SWIG definition files.
  1020  // 	.syso
  1021  // 		System object files.
  1022  //
  1023  // Files of each of these types except .syso may contain build
  1024  // constraints, but the go command stops scanning for build constraints
  1025  // at the first item in the file that is not a blank line or //-style
  1026  // line comment. See the go/build package documentation for
  1027  // more details.
  1028  //
  1029  // Non-test Go source files can also include a //go:binary-only-package
  1030  // comment, indicating that the package sources are included
  1031  // for documentation only and must not be used to build the
  1032  // package binary. This enables distribution of Go packages in
  1033  // their compiled form alone. Even binary-only packages require
  1034  // accurate import blocks listing required dependencies, so that
  1035  // those dependencies can be supplied when linking the resulting
  1036  // command.
  1037  //
  1038  //
  1039  // GOPATH environment variable
  1040  //
  1041  // The Go path is used to resolve import statements.
  1042  // It is implemented by and documented in the go/build package.
  1043  //
  1044  // The GOPATH environment variable lists places to look for Go code.
  1045  // On Unix, the value is a colon-separated string.
  1046  // On Windows, the value is a semicolon-separated string.
  1047  // On Plan 9, the value is a list.
  1048  //
  1049  // If the environment variable is unset, GOPATH defaults
  1050  // to a subdirectory named "go" in the user's home directory
  1051  // ($HOME/go on Unix, %USERPROFILE%\go on Windows),
  1052  // unless that directory holds a Go distribution.
  1053  // Run "go env GOPATH" to see the current GOPATH.
  1054  //
  1055  // See https://golang.org/wiki/SettingGOPATH to set a custom GOPATH.
  1056  //
  1057  // Each directory listed in GOPATH must have a prescribed structure:
  1058  //
  1059  // The src directory holds source code. The path below src
  1060  // determines the import path or executable name.
  1061  //
  1062  // The pkg directory holds installed package objects.
  1063  // As in the Go tree, each target operating system and
  1064  // architecture pair has its own subdirectory of pkg
  1065  // (pkg/GOOS_GOARCH).
  1066  //
  1067  // If DIR is a directory listed in the GOPATH, a package with
  1068  // source in DIR/src/foo/bar can be imported as "foo/bar" and
  1069  // has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a".
  1070  //
  1071  // The bin directory holds compiled commands.
  1072  // Each command is named for its source directory, but only
  1073  // the final element, not the entire path. That is, the
  1074  // command with source in DIR/src/foo/quux is installed into
  1075  // DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped
  1076  // so that you can add DIR/bin to your PATH to get at the
  1077  // installed commands. If the GOBIN environment variable is
  1078  // set, commands are installed to the directory it names instead
  1079  // of DIR/bin. GOBIN must be an absolute path.
  1080  //
  1081  // Here's an example directory layout:
  1082  //
  1083  //     GOPATH=/home/user/go
  1084  //
  1085  //     /home/user/go/
  1086  //         src/
  1087  //             foo/
  1088  //                 bar/               (go code in package bar)
  1089  //                     x.go
  1090  //                 quux/              (go code in package main)
  1091  //                     y.go
  1092  //         bin/
  1093  //             quux                   (installed command)
  1094  //         pkg/
  1095  //             linux_amd64/
  1096  //                 foo/
  1097  //                     bar.a          (installed package object)
  1098  //
  1099  // Go searches each directory listed in GOPATH to find source code,
  1100  // but new packages are always downloaded into the first directory
  1101  // in the list.
  1102  //
  1103  // See https://golang.org/doc/code.html for an example.
  1104  //
  1105  // Internal Directories
  1106  //
  1107  // Code in or below a directory named "internal" is importable only
  1108  // by code in the directory tree rooted at the parent of "internal".
  1109  // Here's an extended version of the directory layout above:
  1110  //
  1111  //     /home/user/go/
  1112  //         src/
  1113  //             crash/
  1114  //                 bang/              (go code in package bang)
  1115  //                     b.go
  1116  //             foo/                   (go code in package foo)
  1117  //                 f.go
  1118  //                 bar/               (go code in package bar)
  1119  //                     x.go
  1120  //                 internal/
  1121  //                     baz/           (go code in package baz)
  1122  //                         z.go
  1123  //                 quux/              (go code in package main)
  1124  //                     y.go
  1125  //
  1126  //
  1127  // The code in z.go is imported as "foo/internal/baz", but that
  1128  // import statement can only appear in source files in the subtree
  1129  // rooted at foo. The source files foo/f.go, foo/bar/x.go, and
  1130  // foo/quux/y.go can all import "foo/internal/baz", but the source file
  1131  // crash/bang/b.go cannot.
  1132  //
  1133  // See https://golang.org/s/go14internal for details.
  1134  //
  1135  // Vendor Directories
  1136  //
  1137  // Go 1.6 includes support for using local copies of external dependencies
  1138  // to satisfy imports of those dependencies, often referred to as vendoring.
  1139  //
  1140  // Code below a directory named "vendor" is importable only
  1141  // by code in the directory tree rooted at the parent of "vendor",
  1142  // and only using an import path that omits the prefix up to and
  1143  // including the vendor element.
  1144  //
  1145  // Here's the example from the previous section,
  1146  // but with the "internal" directory renamed to "vendor"
  1147  // and a new foo/vendor/crash/bang directory added:
  1148  //
  1149  //     /home/user/go/
  1150  //         src/
  1151  //             crash/
  1152  //                 bang/              (go code in package bang)
  1153  //                     b.go
  1154  //             foo/                   (go code in package foo)
  1155  //                 f.go
  1156  //                 bar/               (go code in package bar)
  1157  //                     x.go
  1158  //                 vendor/
  1159  //                     crash/
  1160  //                         bang/      (go code in package bang)
  1161  //                             b.go
  1162  //                     baz/           (go code in package baz)
  1163  //                         z.go
  1164  //                 quux/              (go code in package main)
  1165  //                     y.go
  1166  //
  1167  // The same visibility rules apply as for internal, but the code
  1168  // in z.go is imported as "baz", not as "foo/vendor/baz".
  1169  //
  1170  // Code in vendor directories deeper in the source tree shadows
  1171  // code in higher directories. Within the subtree rooted at foo, an import
  1172  // of "crash/bang" resolves to "foo/vendor/crash/bang", not the
  1173  // top-level "crash/bang".
  1174  //
  1175  // Code in vendor directories is not subject to import path
  1176  // checking (see 'go help importpath').
  1177  //
  1178  // When 'go get' checks out or updates a git repository, it now also
  1179  // updates submodules.
  1180  //
  1181  // Vendor directories do not affect the placement of new repositories
  1182  // being checked out for the first time by 'go get': those are always
  1183  // placed in the main GOPATH, never in a vendor subtree.
  1184  //
  1185  // See https://golang.org/s/go15vendor for details.
  1186  //
  1187  //
  1188  // Environment variables
  1189  //
  1190  // The go command, and the tools it invokes, examine a few different
  1191  // environment variables. For many of these, you can see the default
  1192  // value of on your system by running 'go env NAME', where NAME is the
  1193  // name of the variable.
  1194  //
  1195  // General-purpose environment variables:
  1196  //
  1197  // 	GCCGO
  1198  // 		The gccgo command to run for 'go build -compiler=gccgo'.
  1199  // 	GOARCH
  1200  // 		The architecture, or processor, for which to compile code.
  1201  // 		Examples are amd64, 386, arm, ppc64.
  1202  // 	GOBIN
  1203  // 		The directory where 'go install' will install a command.
  1204  // 	GOOS
  1205  // 		The operating system for which to compile code.
  1206  // 		Examples are linux, darwin, windows, netbsd.
  1207  // 	GOPATH
  1208  // 		For more details see: 'go help gopath'.
  1209  // 	GORACE
  1210  // 		Options for the race detector.
  1211  // 		See https://golang.org/doc/articles/race_detector.html.
  1212  // 	GOROOT
  1213  // 		The root of the go tree.
  1214  // 	GOTMPDIR
  1215  // 		The directory where the go command will write
  1216  // 		temporary source files, packages, and binaries.
  1217  // 	GOCACHE
  1218  // 		The directory where the go command will store
  1219  // 		cached information for reuse in future builds.
  1220  //
  1221  // Environment variables for use with cgo:
  1222  //
  1223  // 	CC
  1224  // 		The command to use to compile C code.
  1225  // 	CGO_ENABLED
  1226  // 		Whether the cgo command is supported. Either 0 or 1.
  1227  // 	CGO_CFLAGS
  1228  // 		Flags that cgo will pass to the compiler when compiling
  1229  // 		C code.
  1230  // 	CGO_CFLAGS_ALLOW
  1231  // 		A regular expression specifying additional flags to allow
  1232  // 		to appear in #cgo CFLAGS source code directives.
  1233  // 		Does not apply to the CGO_CFLAGS environment variable.
  1234  // 	CGO_CFLAGS_DISALLOW
  1235  // 		A regular expression specifying flags that must be disallowed
  1236  // 		from appearing in #cgo CFLAGS source code directives.
  1237  // 		Does not apply to the CGO_CFLAGS environment variable.
  1238  // 	CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
  1239  // 		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
  1240  // 		but for the C preprocessor.
  1241  // 	CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
  1242  // 		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
  1243  // 		but for the C++ compiler.
  1244  // 	CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
  1245  // 		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
  1246  // 		but for the Fortran compiler.
  1247  // 	CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
  1248  // 		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
  1249  // 		but for the linker.
  1250  // 	CXX
  1251  // 		The command to use to compile C++ code.
  1252  // 	PKG_CONFIG
  1253  // 		Path to pkg-config tool.
  1254  //
  1255  // Architecture-specific environment variables:
  1256  //
  1257  // 	GOARM
  1258  // 		For GOARCH=arm, the ARM architecture for which to compile.
  1259  // 		Valid values are 5, 6, 7.
  1260  // 	GO386
  1261  // 		For GOARCH=386, the floating point instruction set.
  1262  // 		Valid values are 387, sse2.
  1263  // 	GOMIPS
  1264  // 		For GOARCH=mips{,le}, whether to use floating point instructions.
  1265  // 		Valid values are hardfloat (default), softfloat.
  1266  //
  1267  // Special-purpose environment variables:
  1268  //
  1269  // 	GOROOT_FINAL
  1270  // 		The root of the installed Go tree, when it is
  1271  // 		installed in a location other than where it is built.
  1272  // 		File names in stack traces are rewritten from GOROOT to
  1273  // 		GOROOT_FINAL.
  1274  // 	GO_EXTLINK_ENABLED
  1275  // 		Whether the linker should use external linking mode
  1276  // 		when using -linkmode=auto with code that uses cgo.
  1277  // 		Set to 0 to disable external linking mode, 1 to enable it.
  1278  // 	GIT_ALLOW_PROTOCOL
  1279  // 		Defined by Git. A colon-separated list of schemes that are allowed to be used
  1280  // 		with git fetch/clone. If set, any scheme not explicitly mentioned will be
  1281  // 		considered insecure by 'go get'.
  1282  //
  1283  //
  1284  // Import path syntax
  1285  //
  1286  // An import path (see 'go help packages') denotes a package stored in the local
  1287  // file system. In general, an import path denotes either a standard package (such
  1288  // as "unicode/utf8") or a package found in one of the work spaces (For more
  1289  // details see: 'go help gopath').
  1290  //
  1291  // Relative import paths
  1292  //
  1293  // An import path beginning with ./ or ../ is called a relative path.
  1294  // The toolchain supports relative import paths as a shortcut in two ways.
  1295  //
  1296  // First, a relative path can be used as a shorthand on the command line.
  1297  // If you are working in the directory containing the code imported as
  1298  // "unicode" and want to run the tests for "unicode/utf8", you can type
  1299  // "go test ./utf8" instead of needing to specify the full path.
  1300  // Similarly, in the reverse situation, "go test .." will test "unicode" from
  1301  // the "unicode/utf8" directory. Relative patterns are also allowed, like
  1302  // "go test ./..." to test all subdirectories. See 'go help packages' for details
  1303  // on the pattern syntax.
  1304  //
  1305  // Second, if you are compiling a Go program not in a work space,
  1306  // you can use a relative path in an import statement in that program
  1307  // to refer to nearby code also not in a work space.
  1308  // This makes it easy to experiment with small multipackage programs
  1309  // outside of the usual work spaces, but such programs cannot be
  1310  // installed with "go install" (there is no work space in which to install them),
  1311  // so they are rebuilt from scratch each time they are built.
  1312  // To avoid ambiguity, Go programs cannot use relative import paths
  1313  // within a work space.
  1314  //
  1315  // Remote import paths
  1316  //
  1317  // Certain import paths also
  1318  // describe how to obtain the source code for the package using
  1319  // a revision control system.
  1320  //
  1321  // A few common code hosting sites have special syntax:
  1322  //
  1323  // 	Bitbucket (Git, Mercurial)
  1324  //
  1325  // 		import "bitbucket.org/user/project"
  1326  // 		import "bitbucket.org/user/project/sub/directory"
  1327  //
  1328  // 	GitHub (Git)
  1329  //
  1330  // 		import "github.com/user/project"
  1331  // 		import "github.com/user/project/sub/directory"
  1332  //
  1333  // 	Launchpad (Bazaar)
  1334  //
  1335  // 		import "launchpad.net/project"
  1336  // 		import "launchpad.net/project/series"
  1337  // 		import "launchpad.net/project/series/sub/directory"
  1338  //
  1339  // 		import "launchpad.net/~user/project/branch"
  1340  // 		import "launchpad.net/~user/project/branch/sub/directory"
  1341  //
  1342  // 	IBM DevOps Services (Git)
  1343  //
  1344  // 		import "hub.jazz.net/git/user/project"
  1345  // 		import "hub.jazz.net/git/user/project/sub/directory"
  1346  //
  1347  // For code hosted on other servers, import paths may either be qualified
  1348  // with the version control type, or the go tool can dynamically fetch
  1349  // the import path over https/http and discover where the code resides
  1350  // from a <meta> tag in the HTML.
  1351  //
  1352  // To declare the code location, an import path of the form
  1353  //
  1354  // 	repository.vcs/path
  1355  //
  1356  // specifies the given repository, with or without the .vcs suffix,
  1357  // using the named version control system, and then the path inside
  1358  // that repository. The supported version control systems are:
  1359  //
  1360  // 	Bazaar      .bzr
  1361  // 	Git         .git
  1362  // 	Mercurial   .hg
  1363  // 	Subversion  .svn
  1364  //
  1365  // For example,
  1366  //
  1367  // 	import "example.org/user/foo.hg"
  1368  //
  1369  // denotes the root directory of the Mercurial repository at
  1370  // example.org/user/foo or foo.hg, and
  1371  //
  1372  // 	import "example.org/repo.git/foo/bar"
  1373  //
  1374  // denotes the foo/bar directory of the Git repository at
  1375  // example.org/repo or repo.git.
  1376  //
  1377  // When a version control system supports multiple protocols,
  1378  // each is tried in turn when downloading. For example, a Git
  1379  // download tries https://, then git+ssh://.
  1380  //
  1381  // By default, downloads are restricted to known secure protocols
  1382  // (e.g. https, ssh). To override this setting for Git downloads, the
  1383  // GIT_ALLOW_PROTOCOL environment variable can be set (For more details see:
  1384  // 'go help environment').
  1385  //
  1386  // If the import path is not a known code hosting site and also lacks a
  1387  // version control qualifier, the go tool attempts to fetch the import
  1388  // over https/http and looks for a <meta> tag in the document's HTML
  1389  // <head>.
  1390  //
  1391  // The meta tag has the form:
  1392  //
  1393  // 	<meta name="go-import" content="import-prefix vcs repo-root">
  1394  //
  1395  // The import-prefix is the import path corresponding to the repository
  1396  // root. It must be a prefix or an exact match of the package being
  1397  // fetched with "go get". If it's not an exact match, another http
  1398  // request is made at the prefix to verify the <meta> tags match.
  1399  //
  1400  // The meta tag should appear as early in the file as possible.
  1401  // In particular, it should appear before any raw JavaScript or CSS,
  1402  // to avoid confusing the go command's restricted parser.
  1403  //
  1404  // The vcs is one of "git", "hg", "svn", etc,
  1405  //
  1406  // The repo-root is the root of the version control system
  1407  // containing a scheme and not containing a .vcs qualifier.
  1408  //
  1409  // For example,
  1410  //
  1411  // 	import "example.org/pkg/foo"
  1412  //
  1413  // will result in the following requests:
  1414  //
  1415  // 	https://example.org/pkg/foo?go-get=1 (preferred)
  1416  // 	http://example.org/pkg/foo?go-get=1  (fallback, only with -insecure)
  1417  //
  1418  // If that page contains the meta tag
  1419  //
  1420  // 	<meta name="go-import" content="example.org git https://code.org/r/p/exproj">
  1421  //
  1422  // the go tool will verify that https://example.org/?go-get=1 contains the
  1423  // same meta tag and then git clone https://code.org/r/p/exproj into
  1424  // GOPATH/src/example.org.
  1425  //
  1426  // New downloaded packages are written to the first directory listed in the GOPATH
  1427  // environment variable (For more details see: 'go help gopath').
  1428  //
  1429  // The go command attempts to download the version of the
  1430  // package appropriate for the Go release being used.
  1431  // Run 'go help get' for more.
  1432  //
  1433  // Import path checking
  1434  //
  1435  // When the custom import path feature described above redirects to a
  1436  // known code hosting site, each of the resulting packages has two possible
  1437  // import paths, using the custom domain or the known hosting site.
  1438  //
  1439  // A package statement is said to have an "import comment" if it is immediately
  1440  // followed (before the next newline) by a comment of one of these two forms:
  1441  //
  1442  // 	package math // import "path"
  1443  // 	package math /* import "path" */
  1444  //
  1445  // The go command will refuse to install a package with an import comment
  1446  // unless it is being referred to by that import path. In this way, import comments
  1447  // let package authors make sure the custom import path is used and not a
  1448  // direct path to the underlying code hosting site.
  1449  //
  1450  // Import path checking is disabled for code found within vendor trees.
  1451  // This makes it possible to copy code into alternate locations in vendor trees
  1452  // without needing to update import comments.
  1453  //
  1454  // See https://golang.org/s/go14customimport for details.
  1455  //
  1456  //
  1457  // Package lists
  1458  //
  1459  // Many commands apply to a set of packages:
  1460  //
  1461  // 	go action [packages]
  1462  //
  1463  // Usually, [packages] is a list of import paths.
  1464  //
  1465  // An import path that is a rooted path or that begins with
  1466  // a . or .. element is interpreted as a file system path and
  1467  // denotes the package in that directory.
  1468  //
  1469  // Otherwise, the import path P denotes the package found in
  1470  // the directory DIR/src/P for some DIR listed in the GOPATH
  1471  // environment variable (For more details see: 'go help gopath').
  1472  //
  1473  // If no import paths are given, the action applies to the
  1474  // package in the current directory.
  1475  //
  1476  // There are four reserved names for paths that should not be used
  1477  // for packages to be built with the go tool:
  1478  //
  1479  // - "main" denotes the top-level package in a stand-alone executable.
  1480  //
  1481  // - "all" expands to all package directories found in all the GOPATH
  1482  // trees. For example, 'go list all' lists all the packages on the local
  1483  // system.
  1484  //
  1485  // - "std" is like all but expands to just the packages in the standard
  1486  // Go library.
  1487  //
  1488  // - "cmd" expands to the Go repository's commands and their
  1489  // internal libraries.
  1490  //
  1491  // Import paths beginning with "cmd/" only match source code in
  1492  // the Go repository.
  1493  //
  1494  // An import path is a pattern if it includes one or more "..." wildcards,
  1495  // each of which can match any string, including the empty string and
  1496  // strings containing slashes. Such a pattern expands to all package
  1497  // directories found in the GOPATH trees with names matching the
  1498  // patterns.
  1499  //
  1500  // To make common patterns more convenient, there are two special cases.
  1501  // First, /... at the end of the pattern can match an empty string,
  1502  // so that net/... matches both net and packages in its subdirectories, like net/http.
  1503  // Second, any slash-separated pattern element containing a wildcard never
  1504  // participates in a match of the "vendor" element in the path of a vendored
  1505  // package, so that ./... does not match packages in subdirectories of
  1506  // ./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do.
  1507  // Note, however, that a directory named vendor that itself contains code
  1508  // is not a vendored package: cmd/vendor would be a command named vendor,
  1509  // and the pattern cmd/... matches it.
  1510  // See golang.org/s/go15vendor for more about vendoring.
  1511  //
  1512  // An import path can also name a package to be downloaded from
  1513  // a remote repository. Run 'go help importpath' for details.
  1514  //
  1515  // Every package in a program must have a unique import path.
  1516  // By convention, this is arranged by starting each path with a
  1517  // unique prefix that belongs to you. For example, paths used
  1518  // internally at Google all begin with 'google', and paths
  1519  // denoting remote repositories begin with the path to the code,
  1520  // such as 'github.com/user/repo'.
  1521  //
  1522  // Packages in a program need not have unique package names,
  1523  // but there are two reserved package names with special meaning.
  1524  // The name main indicates a command, not a library.
  1525  // Commands are built into binaries and cannot be imported.
  1526  // The name documentation indicates documentation for
  1527  // a non-Go program in the directory. Files in package documentation
  1528  // are ignored by the go command.
  1529  //
  1530  // As a special case, if the package list is a list of .go files from a
  1531  // single directory, the command is applied to a single synthesized
  1532  // package made up of exactly those files, ignoring any build constraints
  1533  // in those files and ignoring any other files in the directory.
  1534  //
  1535  // Directory and file names that begin with "." or "_" are ignored
  1536  // by the go tool, as are directories named "testdata".
  1537  //
  1538  //
  1539  // Testing flags
  1540  //
  1541  // The 'go test' command takes both flags that apply to 'go test' itself
  1542  // and flags that apply to the resulting test binary.
  1543  //
  1544  // Several of the flags control profiling and write an execution profile
  1545  // suitable for "go tool pprof"; run "go tool pprof -h" for more
  1546  // information. The --alloc_space, --alloc_objects, and --show_bytes
  1547  // options of pprof control how the information is presented.
  1548  //
  1549  // The following flags are recognized by the 'go test' command and
  1550  // control the execution of any test:
  1551  //
  1552  // 	-bench regexp
  1553  // 	    Run only those benchmarks matching a regular expression.
  1554  // 	    By default, no benchmarks are run.
  1555  // 	    To run all benchmarks, use '-bench .' or '-bench=.'.
  1556  // 	    The regular expression is split by unbracketed slash (/)
  1557  // 	    characters into a sequence of regular expressions, and each
  1558  // 	    part of a benchmark's identifier must match the corresponding
  1559  // 	    element in the sequence, if any. Possible parents of matches
  1560  // 	    are run with b.N=1 to identify sub-benchmarks. For example,
  1561  // 	    given -bench=X/Y, top-level benchmarks matching X are run
  1562  // 	    with b.N=1 to find any sub-benchmarks matching Y, which are
  1563  // 	    then run in full.
  1564  //
  1565  // 	-benchtime t
  1566  // 	    Run enough iterations of each benchmark to take t, specified
  1567  // 	    as a time.Duration (for example, -benchtime 1h30s).
  1568  // 	    The default is 1 second (1s).
  1569  //
  1570  // 	-count n
  1571  // 	    Run each test and benchmark n times (default 1).
  1572  // 	    If -cpu is set, run n times for each GOMAXPROCS value.
  1573  // 	    Examples are always run once.
  1574  //
  1575  // 	-cover
  1576  // 	    Enable coverage analysis.
  1577  // 	    Note that because coverage works by annotating the source
  1578  // 	    code before compilation, compilation and test failures with
  1579  // 	    coverage enabled may report line numbers that don't correspond
  1580  // 	    to the original sources.
  1581  //
  1582  // 	-covermode set,count,atomic
  1583  // 	    Set the mode for coverage analysis for the package[s]
  1584  // 	    being tested. The default is "set" unless -race is enabled,
  1585  // 	    in which case it is "atomic".
  1586  // 	    The values:
  1587  // 		set: bool: does this statement run?
  1588  // 		count: int: how many times does this statement run?
  1589  // 		atomic: int: count, but correct in multithreaded tests;
  1590  // 			significantly more expensive.
  1591  // 	    Sets -cover.
  1592  //
  1593  // 	-coverpkg pattern1,pattern2,pattern3
  1594  // 	    Apply coverage analysis in each test to packages matching the patterns.
  1595  // 	    The default is for each test to analyze only the package being tested.
  1596  // 	    See 'go help packages' for a description of package patterns.
  1597  // 	    Sets -cover.
  1598  //
  1599  // 	-cpu 1,2,4
  1600  // 	    Specify a list of GOMAXPROCS values for which the tests or
  1601  // 	    benchmarks should be executed. The default is the current value
  1602  // 	    of GOMAXPROCS.
  1603  //
  1604  // 	-failfast
  1605  // 	    Do not start new tests after the first test failure.
  1606  //
  1607  // 	-list regexp
  1608  // 	    List tests, benchmarks, or examples matching the regular expression.
  1609  // 	    No tests, benchmarks or examples will be run. This will only
  1610  // 	    list top-level tests. No subtest or subbenchmarks will be shown.
  1611  //
  1612  // 	-parallel n
  1613  // 	    Allow parallel execution of test functions that call t.Parallel.
  1614  // 	    The value of this flag is the maximum number of tests to run
  1615  // 	    simultaneously; by default, it is set to the value of GOMAXPROCS.
  1616  // 	    Note that -parallel only applies within a single test binary.
  1617  // 	    The 'go test' command may run tests for different packages
  1618  // 	    in parallel as well, according to the setting of the -p flag
  1619  // 	    (see 'go help build').
  1620  //
  1621  // 	-run regexp
  1622  // 	    Run only those tests and examples matching the regular expression.
  1623  // 	    For tests, the regular expression is split by unbracketed slash (/)
  1624  // 	    characters into a sequence of regular expressions, and each part
  1625  // 	    of a test's identifier must match the corresponding element in
  1626  // 	    the sequence, if any. Note that possible parents of matches are
  1627  // 	    run too, so that -run=X/Y matches and runs and reports the result
  1628  // 	    of all tests matching X, even those without sub-tests matching Y,
  1629  // 	    because it must run them to look for those sub-tests.
  1630  //
  1631  // 	-short
  1632  // 	    Tell long-running tests to shorten their run time.
  1633  // 	    It is off by default but set during all.bash so that installing
  1634  // 	    the Go tree can run a sanity check but not spend time running
  1635  // 	    exhaustive tests.
  1636  //
  1637  // 	-timeout d
  1638  // 	    If a test binary runs longer than duration d, panic.
  1639  // 	    If d is 0, the timeout is disabled.
  1640  // 	    The default is 10 minutes (10m).
  1641  //
  1642  // 	-v
  1643  // 	    Verbose output: log all tests as they are run. Also print all
  1644  // 	    text from Log and Logf calls even if the test succeeds.
  1645  //
  1646  // 	-vet list
  1647  // 	    Configure the invocation of "go vet" during "go test"
  1648  // 	    to use the comma-separated list of vet checks.
  1649  // 	    If list is empty, "go test" runs "go vet" with a curated list of
  1650  // 	    checks believed to be always worth addressing.
  1651  // 	    If list is "off", "go test" does not run "go vet" at all.
  1652  //
  1653  // The following flags are also recognized by 'go test' and can be used to
  1654  // profile the tests during execution:
  1655  //
  1656  // 	-benchmem
  1657  // 	    Print memory allocation statistics for benchmarks.
  1658  //
  1659  // 	-blockprofile block.out
  1660  // 	    Write a goroutine blocking profile to the specified file
  1661  // 	    when all tests are complete.
  1662  // 	    Writes test binary as -c would.
  1663  //
  1664  // 	-blockprofilerate n
  1665  // 	    Control the detail provided in goroutine blocking profiles by
  1666  // 	    calling runtime.SetBlockProfileRate with n.
  1667  // 	    See 'go doc runtime.SetBlockProfileRate'.
  1668  // 	    The profiler aims to sample, on average, one blocking event every
  1669  // 	    n nanoseconds the program spends blocked. By default,
  1670  // 	    if -test.blockprofile is set without this flag, all blocking events
  1671  // 	    are recorded, equivalent to -test.blockprofilerate=1.
  1672  //
  1673  // 	-coverprofile cover.out
  1674  // 	    Write a coverage profile to the file after all tests have passed.
  1675  // 	    Sets -cover.
  1676  //
  1677  // 	-cpuprofile cpu.out
  1678  // 	    Write a CPU profile to the specified file before exiting.
  1679  // 	    Writes test binary as -c would.
  1680  //
  1681  // 	-memprofile mem.out
  1682  // 	    Write a memory profile to the file after all tests have passed.
  1683  // 	    Writes test binary as -c would.
  1684  //
  1685  // 	-memprofilerate n
  1686  // 	    Enable more precise (and expensive) memory profiles by setting
  1687  // 	    runtime.MemProfileRate. See 'go doc runtime.MemProfileRate'.
  1688  // 	    To profile all memory allocations, use -test.memprofilerate=1
  1689  // 	    and pass --alloc_space flag to the pprof tool.
  1690  //
  1691  // 	-mutexprofile mutex.out
  1692  // 	    Write a mutex contention profile to the specified file
  1693  // 	    when all tests are complete.
  1694  // 	    Writes test binary as -c would.
  1695  //
  1696  // 	-mutexprofilefraction n
  1697  // 	    Sample 1 in n stack traces of goroutines holding a
  1698  // 	    contended mutex.
  1699  //
  1700  // 	-outputdir directory
  1701  // 	    Place output files from profiling in the specified directory,
  1702  // 	    by default the directory in which "go test" is running.
  1703  //
  1704  // 	-trace trace.out
  1705  // 	    Write an execution trace to the specified file before exiting.
  1706  //
  1707  // Each of these flags is also recognized with an optional 'test.' prefix,
  1708  // as in -test.v. When invoking the generated test binary (the result of
  1709  // 'go test -c') directly, however, the prefix is mandatory.
  1710  //
  1711  // The 'go test' command rewrites or removes recognized flags,
  1712  // as appropriate, both before and after the optional package list,
  1713  // before invoking the test binary.
  1714  //
  1715  // For instance, the command
  1716  //
  1717  // 	go test -v -myflag testdata -cpuprofile=prof.out -x
  1718  //
  1719  // will compile the test binary and then run it as
  1720  //
  1721  // 	pkg.test -test.v -myflag testdata -test.cpuprofile=prof.out
  1722  //
  1723  // (The -x flag is removed because it applies only to the go command's
  1724  // execution, not to the test itself.)
  1725  //
  1726  // The test flags that generate profiles (other than for coverage) also
  1727  // leave the test binary in pkg.test for use when analyzing the profiles.
  1728  //
  1729  // When 'go test' runs a test binary, it does so from within the
  1730  // corresponding package's source code directory. Depending on the test,
  1731  // it may be necessary to do the same when invoking a generated test
  1732  // binary directly.
  1733  //
  1734  // The command-line package list, if present, must appear before any
  1735  // flag not known to the go test command. Continuing the example above,
  1736  // the package list would have to appear before -myflag, but could appear
  1737  // on either side of -v.
  1738  //
  1739  // To keep an argument for a test binary from being interpreted as a
  1740  // known flag or a package name, use -args (see 'go help test') which
  1741  // passes the remainder of the command line through to the test binary
  1742  // uninterpreted and unaltered.
  1743  //
  1744  // For instance, the command
  1745  //
  1746  // 	go test -v -args -x -v
  1747  //
  1748  // will compile the test binary and then run it as
  1749  //
  1750  // 	pkg.test -test.v -x -v
  1751  //
  1752  // Similarly,
  1753  //
  1754  // 	go test -args math
  1755  //
  1756  // will compile the test binary and then run it as
  1757  //
  1758  // 	pkg.test math
  1759  //
  1760  // In the first example, the -x and the second -v are passed through to the
  1761  // test binary unchanged and with no effect on the go command itself.
  1762  // In the second example, the argument math is passed through to the test
  1763  // binary, instead of being interpreted as the package list.
  1764  //
  1765  //
  1766  // Testing functions
  1767  //
  1768  // The 'go test' command expects to find test, benchmark, and example functions
  1769  // in the "*_test.go" files corresponding to the package under test.
  1770  //
  1771  // A test function is one named TestXxx (where Xxx does not start with a
  1772  // lower case letter) and should have the signature,
  1773  //
  1774  // 	func TestXxx(t *testing.T) { ... }
  1775  //
  1776  // A benchmark function is one named BenchmarkXxx and should have the signature,
  1777  //
  1778  // 	func BenchmarkXxx(b *testing.B) { ... }
  1779  //
  1780  // An example function is similar to a test function but, instead of using
  1781  // *testing.T to report success or failure, prints output to os.Stdout.
  1782  // If the last comment in the function starts with "Output:" then the output
  1783  // is compared exactly against the comment (see examples below). If the last
  1784  // comment begins with "Unordered output:" then the output is compared to the
  1785  // comment, however the order of the lines is ignored. An example with no such
  1786  // comment is compiled but not executed. An example with no text after
  1787  // "Output:" is compiled, executed, and expected to produce no output.
  1788  //
  1789  // Godoc displays the body of ExampleXxx to demonstrate the use
  1790  // of the function, constant, or variable Xxx. An example of a method M with
  1791  // receiver type T or *T is named ExampleT_M. There may be multiple examples
  1792  // for a given function, constant, or variable, distinguished by a trailing _xxx,
  1793  // where xxx is a suffix not beginning with an upper case letter.
  1794  //
  1795  // Here is an example of an example:
  1796  //
  1797  // 	func ExamplePrintln() {
  1798  // 		Println("The output of\nthis example.")
  1799  // 		// Output: The output of
  1800  // 		// this example.
  1801  // 	}
  1802  //
  1803  // Here is another example where the ordering of the output is ignored:
  1804  //
  1805  // 	func ExamplePerm() {
  1806  // 		for _, value := range Perm(4) {
  1807  // 			fmt.Println(value)
  1808  // 		}
  1809  //
  1810  // 		// Unordered output: 4
  1811  // 		// 2
  1812  // 		// 1
  1813  // 		// 3
  1814  // 		// 0
  1815  // 	}
  1816  //
  1817  // The entire test file is presented as the example when it contains a single
  1818  // example function, at least one other function, type, variable, or constant
  1819  // declaration, and no test or benchmark functions.
  1820  //
  1821  // See the documentation of the testing package for more information.
  1822  //
  1823  //
  1824  package main
  1825  

View as plain text