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