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