Source file src/cmd/go/alldocs.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 'go test cmd/go -v -run=^TestDocsUpToDate$ -fixdocs'; DO NOT EDIT. 6 // Edit the documentation in other files and then execute 'go generate cmd/go' 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 apply fixes suggested by static checkers 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 // telemetry manage telemetry data and settings 30 // test test packages 31 // tool run specified go tool 32 // version print Go version 33 // vet report likely mistakes in packages 34 // work workspace maintenance 35 // 36 // Use "go help <command>" for more information about a command. 37 // 38 // Additional help topics: 39 // 40 // buildconstraint build constraints 41 // buildjson build -json encoding 42 // buildmode build modes 43 // c calling between Go and C 44 // cache build and test caching 45 // environment environment variables 46 // filetype file types 47 // goauth GOAUTH environment variable 48 // go.mod the go.mod file 49 // gopath GOPATH environment variable 50 // goproxy module proxy protocol 51 // importpath import path syntax 52 // modules modules, module versions, and more 53 // module-auth module authentication using go.sum 54 // packages package lists and patterns 55 // private configuration for downloading non-public code 56 // testflag testing flags 57 // testfunc testing functions 58 // vcs controlling version control with GOVCS 59 // 60 // Use "go help <topic>" for more information about that topic. 61 // 62 // # Start a bug report 63 // 64 // Usage: 65 // 66 // go bug 67 // 68 // Bug opens the default browser and starts a new bug report. 69 // The report includes useful system information. 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 the resulting 86 // executable to an output file named after the last non-major-version 87 // component of the package import path. The '.exe' suffix is added 88 // when writing a Windows executable. 89 // So 'go build example/sam' writes 'sam' or 'sam.exe'. 90 // 'go build example.com/foo/v2' writes 'foo' or 'foo.exe', not 'v2.exe'. 91 // 92 // When compiling a package from a list of .go files, the executable 93 // is named after the first source file. 94 // 'go build ed.go rx.go' writes 'ed' or 'ed.exe'. 95 // 96 // When compiling multiple packages or a single non-main package, 97 // build compiles the packages but discards the resulting object, 98 // serving only as a check that the packages can be built. 99 // 100 // The -o flag forces build to write the resulting executable or object 101 // to the named output file or directory, instead of the default behavior described 102 // in the last two paragraphs. If the named output is an existing directory or 103 // ends with a slash or backslash, then any resulting executables 104 // will be written to that directory. 105 // 106 // The build flags are shared by the build, clean, get, install, list, run, 107 // and test commands: 108 // 109 // -C dir 110 // Change to dir before running the command. 111 // Any files named on the command line are interpreted after 112 // changing directories. 113 // If used, this flag must be the first one in the command line. 114 // -a 115 // force rebuilding of packages that are already up-to-date. 116 // -n 117 // print the commands but do not run them. 118 // -p n 119 // the number of programs, such as build commands or 120 // test binaries, that can be run in parallel. 121 // The default is GOMAXPROCS, normally the number of CPUs available. 122 // -race 123 // enable data race detection. 124 // Supported only on darwin/amd64, darwin/arm64, freebsd/amd64, linux/amd64, 125 // linux/arm64 (only for 48-bit VMA), linux/ppc64le, linux/riscv64 and 126 // windows/amd64. 127 // -msan 128 // enable interoperation with memory sanitizer. 129 // Supported only on linux/amd64, linux/arm64, linux/loong64, freebsd/amd64 130 // and only with Clang/LLVM as the host C compiler. 131 // PIE build mode will be used on all platforms except linux/amd64. 132 // -asan 133 // enable interoperation with address sanitizer. 134 // Supported only on linux/arm64, linux/amd64, linux/loong64. 135 // Supported on linux/amd64 or linux/arm64 and only with GCC 7 and higher 136 // or Clang/LLVM 9 and higher. 137 // And supported on linux/loong64 only with Clang/LLVM 16 and higher. 138 // -cover 139 // enable code coverage instrumentation. 140 // -covermode set,count,atomic 141 // set the mode for coverage analysis. 142 // The default is "set" unless -race is enabled, 143 // in which case it is "atomic". 144 // The values: 145 // set: bool: does this statement run? 146 // count: int: how many times does this statement run? 147 // atomic: int: count, but correct in multithreaded tests; 148 // significantly more expensive. 149 // Sets -cover. 150 // -coverpkg pattern1,pattern2,pattern3 151 // For a build that targets package 'main' (e.g. building a Go 152 // executable), apply coverage analysis to each package whose 153 // import path matches the patterns. The default is to apply 154 // coverage analysis to packages in the main Go module. See 155 // 'go help packages' for a description of package patterns. 156 // Sets -cover. 157 // -v 158 // print the names of packages as they are compiled. 159 // -work 160 // print the name of the temporary work directory and 161 // do not delete it when exiting. 162 // -x 163 // print the commands. 164 // -asmflags '[pattern=]arg list' 165 // arguments to pass on each go tool asm invocation. 166 // -buildmode mode 167 // build mode to use. See 'go help buildmode' for more. 168 // -buildvcs 169 // Whether to stamp binaries with version control information 170 // ("true", "false", or "auto"). By default ("auto"), version control 171 // information is stamped into a binary if the main package, the main module 172 // containing it, and the current directory are all in the same repository. 173 // Use -buildvcs=false to always omit version control information, or 174 // -buildvcs=true to error out if version control information is available but 175 // cannot be included due to a missing tool or ambiguous directory structure. 176 // -compiler name 177 // name of compiler to use, as in runtime.Compiler (gccgo or gc). 178 // -gccgoflags '[pattern=]arg list' 179 // arguments to pass on each gccgo compiler/linker invocation. 180 // -gcflags '[pattern=]arg list' 181 // arguments to pass on each go tool compile invocation. 182 // -installsuffix suffix 183 // a suffix to use in the name of the package installation directory, 184 // in order to keep output separate from default builds. 185 // If using the -race flag, the install suffix is automatically set to race 186 // or, if set explicitly, has _race appended to it. Likewise for the -msan 187 // and -asan flags. Using a -buildmode option that requires non-default compile 188 // flags has a similar effect. 189 // -json 190 // Emit build output in JSON suitable for automated processing. 191 // See 'go help buildjson' for the encoding details. 192 // -ldflags '[pattern=]arg list' 193 // arguments to pass on each go tool link invocation. 194 // -linkshared 195 // build code that will be linked against shared libraries previously 196 // created with -buildmode=shared. 197 // -mod mode 198 // module download mode to use: readonly, vendor, or mod. 199 // By default, if a vendor directory is present and the go version in go.mod 200 // is 1.14 or higher, the go command acts as if -mod=vendor were set. 201 // Otherwise, the go command acts as if -mod=readonly were set. 202 // See https://go.dev/ref/mod#build-commands for details. 203 // -modcacherw 204 // leave newly-created directories in the module cache read-write 205 // instead of making them read-only. 206 // -modfile file 207 // in module aware mode, read (and possibly write) an alternate go.mod 208 // file instead of the one in the module root directory. A file named 209 // "go.mod" must still be present in order to determine the module root 210 // directory, but it is not accessed. When -modfile is specified, an 211 // alternate go.sum file is also used: its path is derived from the 212 // -modfile flag by trimming the ".mod" extension and appending ".sum". 213 // -overlay file 214 // read a JSON config file that provides an overlay for build operations. 215 // The file is a JSON object with a single field, named 'Replace', that 216 // maps each disk file path (a string) to its backing file path, so that 217 // a build will run as if the disk file path exists with the contents 218 // given by the backing file paths, or as if the disk file path does not 219 // exist if its backing file path is empty. A disk file path in 'Replace' 220 // does not need to exist on disk, so an overlay can also add new files 221 // to a build. Support for the -overlay flag has some limitations: 222 // importantly, cgo files included from outside the include path must 223 // be in the same directory as the Go package they are included from, 224 // overlays will not appear when binaries and tests are run through 225 // go run and go test respectively, and files beneath GOMODCACHE may 226 // not be replaced. 227 // -pgo file 228 // specify the file path of a profile for profile-guided optimization (PGO). 229 // When the special name "auto" is specified, for each main package in the 230 // build, the go command selects a file named "default.pgo" in the package's 231 // directory if that file exists, and applies it to the (transitive) 232 // dependencies of the main package (other packages are not affected). 233 // Special name "off" turns off PGO. The default is "auto". 234 // -pkgdir dir 235 // install and load all packages from dir instead of the usual locations. 236 // For example, when building with a non-standard configuration, 237 // use -pkgdir to keep generated packages in a separate location. 238 // -tags tag,list 239 // a comma-separated list of additional build tags to consider satisfied 240 // during the build. For more information about build tags, see 241 // 'go help buildconstraint'. (Earlier versions of Go used a 242 // space-separated list, and that form is deprecated but still recognized.) 243 // -trimpath 244 // remove all file system paths from the resulting executable. 245 // Instead of absolute file system paths, the recorded file names 246 // will begin either a module path@version (when using modules), 247 // or a plain import path (when using the standard library, or GOPATH). 248 // -toolexec 'cmd args' 249 // a program to use to invoke toolchain programs like vet and asm. 250 // For example, instead of running asm, the go command will run 251 // 'cmd args /path/to/asm <arguments for asm>'. 252 // The TOOLEXEC_IMPORTPATH environment variable will be set, 253 // matching 'go list -f {{.ImportPath}}' for the package being built. 254 // 255 // The -asmflags, -gccgoflags, -gcflags, and -ldflags flags accept a 256 // space-separated list of arguments to pass to an underlying tool 257 // during the build. To embed spaces in an element in the list, surround 258 // it with either single or double quotes. The argument list may be 259 // preceded by a package pattern and an equal sign, which restricts 260 // the use of that argument list to the building of packages matching 261 // that pattern (see 'go help packages' for a description of package 262 // patterns). Without a pattern, the argument list applies only to the 263 // packages named on the command line. The flags may be repeated 264 // with different patterns in order to specify different arguments for 265 // different sets of packages. If a package matches patterns given in 266 // multiple flags, the latest match on the command line wins. 267 // For example, 'go build -gcflags=-S fmt' prints the disassembly 268 // only for package fmt, while 'go build -gcflags=all=-S fmt' 269 // prints the disassembly for fmt and all its dependencies. 270 // 271 // For more about specifying packages, see 'go help packages'. 272 // For more about where binaries are installed, run 'go help gopath'. 273 // For more about calling between Go and C/C++, run 'go help c'. 274 // For more about project organization, run 'go help modules'. 275 // 276 // Note: go build adheres to certain conventions for organizing projects: 277 // it primarily supports go modules (see 'go help modules') while 278 // also supporting an alternative GOPATH mode (see 'go help gopath'). 279 // Not all projects can follow these conventions, 280 // however. Installations that have their own conventions or that use 281 // a separate software build system may choose to use lower-level 282 // invocations such as 'go tool compile' and 'go tool link' to avoid 283 // some of the overheads and design decisions of the build tool. 284 // 285 // See also: go install, go get, go clean. 286 // 287 // # Remove object files and cached files 288 // 289 // Usage: 290 // 291 // go clean [-i] [-r] [-cache] [-testcache] [-modcache] [-fuzzcache] [build flags] [packages] 292 // 293 // Clean removes object files from package source directories. 294 // The go command builds most objects in a temporary directory, 295 // so go clean is mainly concerned with object files left by other 296 // tools or by manual invocations of go build. 297 // 298 // If a package argument is given or the -i or -r flag is set, 299 // clean removes the following files from each of the 300 // source directories corresponding to the import paths: 301 // 302 // _obj/ old object directory, left from Makefiles 303 // _test/ old test directory, left from Makefiles 304 // _testmain.go old gotest file, left from Makefiles 305 // test.out old test log, left from Makefiles 306 // build.out old test log, left from Makefiles 307 // *.[568ao] object files, left from Makefiles 308 // 309 // DIR(.exe) from go build 310 // DIR.test(.exe) from go test -c 311 // MAINFILE(.exe) from go build MAINFILE.go 312 // *.so from SWIG 313 // 314 // In the list, DIR represents the final path element of the 315 // directory, and MAINFILE is the base name of any Go source 316 // file in the directory that is not included when building 317 // the package. 318 // 319 // The -i flag causes clean to remove the corresponding installed 320 // archive or binary (what 'go install' would create). 321 // 322 // The -n flag causes clean to print the remove commands it would execute, 323 // but not run them. 324 // 325 // The -r flag causes clean to be applied recursively to all the 326 // dependencies of the packages named by the import paths. 327 // 328 // The -x flag causes clean to print remove commands as it executes them. 329 // 330 // The -cache flag causes clean to remove the entire go build cache. 331 // 332 // The -testcache flag causes clean to expire all test results in the 333 // go build cache. 334 // 335 // The -modcache flag causes clean to remove the entire module 336 // download cache, including unpacked source code of versioned 337 // dependencies. 338 // 339 // The -fuzzcache flag causes clean to remove files stored in the Go build 340 // cache for fuzz testing. The fuzzing engine caches files that expand 341 // code coverage, so removing them may make fuzzing less effective until 342 // new inputs are found that provide the same coverage. These files are 343 // distinct from those stored in testdata directory; clean does not remove 344 // those files. 345 // 346 // For more about build flags, see 'go help build'. 347 // 348 // For more about specifying packages, see 'go help packages'. 349 // 350 // # Show documentation for package or symbol 351 // 352 // Usage: 353 // 354 // go doc [doc flags] [package|[package.]symbol[.methodOrField]] 355 // 356 // Doc prints the documentation comments associated with the item identified by its 357 // arguments (a package, const, func, type, var, method, or struct field) 358 // followed by a one-line summary of each of the first-level items "under" 359 // that item (package-level declarations for a package, methods for a type, 360 // etc.). 361 // 362 // Doc accepts zero, one, or two arguments. 363 // 364 // Given no arguments, that is, when run as 365 // 366 // go doc 367 // 368 // it prints the package documentation for the package in the current directory. 369 // If the package is a command (package main), the exported symbols of the package 370 // are elided from the presentation unless the -cmd flag is provided. 371 // 372 // When run with one argument, the argument is treated as a Go-syntax-like 373 // representation of the item to be documented. What the argument selects depends 374 // on what is installed in GOROOT and GOPATH, as well as the form of the argument, 375 // which is schematically one of these: 376 // 377 // go doc <pkg> 378 // go doc <sym>[.<methodOrField>] 379 // go doc [<pkg>.]<sym>[.<methodOrField>] 380 // go doc [<pkg>.][<sym>.]<methodOrField> 381 // 382 // The first item in this list matched by the argument is the one whose documentation 383 // is printed. (See the examples below.) However, if the argument starts with a capital 384 // letter it is assumed to identify a symbol or method in the current directory. 385 // 386 // For packages, the order of scanning is determined lexically in breadth-first order. 387 // That is, the package presented is the one that matches the search and is nearest 388 // the root and lexically first at its level of the hierarchy. The GOROOT tree is 389 // always scanned in its entirety before GOPATH. 390 // 391 // If there is no package specified or matched, the package in the current 392 // directory is selected, so "go doc Foo" shows the documentation for symbol Foo in 393 // the current package. 394 // 395 // The package path must be either a qualified path or a proper suffix of a 396 // path. The go tool's usual package mechanism does not apply: package path 397 // elements like . and ... are not implemented by go doc. 398 // 399 // When run with two arguments, the first is a package path (full path or suffix), 400 // and the second is a symbol, or symbol with method or struct field: 401 // 402 // go doc <pkg> <sym>[.<methodOrField>] 403 // 404 // In all forms, when matching symbols, lower-case letters in the argument match 405 // either case but upper-case letters match exactly. This means that there may be 406 // multiple matches of a lower-case argument in a package if different symbols have 407 // different cases. If this occurs, documentation for all matches is printed. 408 // 409 // Examples: 410 // 411 // go doc 412 // Show documentation for current package. 413 // go doc -http 414 // Serve HTML documentation over HTTP for the current package. 415 // go doc Foo 416 // Show documentation for Foo in the current package. 417 // (Foo starts with a capital letter so it cannot match 418 // a package path.) 419 // go doc encoding/json 420 // Show documentation for the encoding/json package. 421 // go doc json 422 // Shorthand for encoding/json. 423 // go doc json.Number (or go doc json.number) 424 // Show documentation and method summary for json.Number. 425 // go doc json.Number.Int64 (or go doc json.number.int64) 426 // Show documentation for json.Number's Int64 method. 427 // go doc cmd/doc 428 // Show package docs for the doc command. 429 // go doc -cmd cmd/doc 430 // Show package docs and exported symbols within the doc command. 431 // go doc template.new 432 // Show documentation for html/template's New function. 433 // (html/template is lexically before text/template) 434 // go doc text/template.new # One argument 435 // Show documentation for text/template's New function. 436 // go doc text/template new # Two arguments 437 // Show documentation for text/template's New function. 438 // 439 // At least in the current tree, these invocations all print the 440 // documentation for json.Decoder's Decode method: 441 // 442 // go doc json.Decoder.Decode 443 // go doc json.decoder.decode 444 // go doc json.decode 445 // cd go/src/encoding/json; go doc decode 446 // 447 // Flags: 448 // 449 // -all 450 // Show all the documentation for the package. 451 // -c 452 // Respect case when matching symbols. 453 // -cmd 454 // Treat a command (package main) like a regular package. 455 // Otherwise package main's exported symbols are hidden 456 // when showing the package's top-level documentation. 457 // -ex 458 // Include executable examples. 459 // -http 460 // Serve HTML docs over HTTP. 461 // -short 462 // One-line representation for each symbol. Cannot be 463 // combined with -all. 464 // -src 465 // Show the full source code for the symbol. This will 466 // display the full Go source of its declaration and 467 // definition, such as a function definition (including 468 // the body), type declaration or enclosing const 469 // block. The output may therefore include unexported 470 // details. 471 // -u 472 // Show documentation for unexported as well as exported 473 // symbols, methods, and fields. 474 // 475 // # Print Go environment information 476 // 477 // Usage: 478 // 479 // go env [-json] [-changed] [-u] [-w] [var ...] 480 // 481 // Env prints Go environment information. 482 // 483 // By default env prints information as a shell script 484 // (on Windows, a batch file). If one or more variable 485 // names is given as arguments, env prints the value of 486 // each named variable on its own line. 487 // 488 // The -json flag prints the environment in JSON format 489 // instead of as a shell script. 490 // 491 // The -u flag requires one or more arguments and unsets 492 // the default setting for the named environment variables, 493 // if one has been set with 'go env -w'. 494 // 495 // The -w flag requires one or more arguments of the 496 // form NAME=VALUE and changes the default settings 497 // of the named environment variables to the given values. 498 // 499 // The -changed flag prints only those settings whose effective 500 // value differs from the default value that would be obtained in 501 // an empty environment with no prior uses of the -w flag. 502 // 503 // For more about environment variables, see 'go help environment'. 504 // 505 // # Apply fixes suggested by static checkers 506 // 507 // Usage: 508 // 509 // go fix [build flags] [-fixtool prog] [fix flags] [packages] 510 // 511 // Fix runs the Go fix tool (cmd/fix) on the named packages 512 // and applies suggested fixes. 513 // 514 // It supports these flags: 515 // 516 // -diff 517 // instead of applying each fix, print the patch as a unified diff; 518 // exit with a non-zero status if the diff is not empty 519 // 520 // The -fixtool=prog flag selects a different analysis tool with 521 // alternative or additional fixers; see the documentation for go vet's 522 // -vettool flag for details. 523 // 524 // The default fix tool is 'go tool fix' or cmd/fix. 525 // For help on its fixers and their flags, run 'go tool fix help'. 526 // For details of a specific fixer such as 'hostport', see 'go tool fix help hostport'. 527 // 528 // For more about specifying packages, see 'go help packages'. 529 // 530 // The build flags supported by go fix are those that control package resolution 531 // and execution, such as -C, -n, -x, -v, -tags, and -toolexec. 532 // For more about these flags, see 'go help build'. 533 // 534 // See also: go fmt, go vet. 535 // 536 // # Gofmt (reformat) package sources 537 // 538 // Usage: 539 // 540 // go fmt [-n] [-x] [packages] 541 // 542 // Fmt runs the command 'gofmt -l -w' on the packages named 543 // by the import paths. It prints the names of the files that are modified. 544 // 545 // For more about gofmt, see 'go doc cmd/gofmt'. 546 // For more about specifying packages, see 'go help packages'. 547 // 548 // The -n flag prints commands that would be executed. 549 // The -x flag prints commands as they are executed. 550 // 551 // The -mod flag's value sets which module download mode 552 // to use: readonly or vendor. See 'go help modules' for more. 553 // 554 // To run gofmt with specific options, run gofmt itself. 555 // 556 // See also: go fix, go vet. 557 // 558 // # Generate Go files by processing source 559 // 560 // Usage: 561 // 562 // go generate [-run regexp] [-n] [-v] [-x] [build flags] [file.go... | packages] 563 // 564 // Generate runs commands described by directives within existing 565 // files. Those commands can run any process but the intent is to 566 // create or update Go source files. 567 // 568 // Go generate is never run automatically by go build, go test, 569 // and so on. It must be run explicitly. 570 // 571 // Go generate scans the file for directives, which are lines of 572 // the form, 573 // 574 // //go:generate command argument... 575 // 576 // (note: no leading spaces and no space in "//go") where command 577 // is the generator to be run, corresponding to an executable file 578 // that can be run locally. It must either be in the shell path 579 // (gofmt), a fully qualified path (/usr/you/bin/mytool), or a 580 // command alias, described below. 581 // 582 // Note that go generate does not parse the file, so lines that look 583 // like directives in comments or multiline strings will be treated 584 // as directives. 585 // 586 // The arguments to the directive are space-separated tokens or 587 // double-quoted strings passed to the generator as individual 588 // arguments when it is run. 589 // 590 // Quoted strings use Go syntax and are evaluated before execution; a 591 // quoted string appears as a single argument to the generator. 592 // 593 // To convey to humans and machine tools that code is generated, 594 // generated source should have a line that matches the following 595 // regular expression (in Go syntax): 596 // 597 // ^// Code generated .* DO NOT EDIT\.$ 598 // 599 // This line must appear before the first non-comment, non-blank 600 // text in the file. 601 // 602 // Go generate sets several variables when it runs the generator: 603 // 604 // $GOARCH 605 // The execution architecture (arm, amd64, etc.) 606 // $GOOS 607 // The execution operating system (linux, windows, etc.) 608 // $GOFILE 609 // The base name of the file. 610 // $GOLINE 611 // The line number of the directive in the source file. 612 // $GOPACKAGE 613 // The name of the package of the file containing the directive. 614 // $GOROOT 615 // The GOROOT directory for the 'go' command that invoked the 616 // generator, containing the Go toolchain and standard library. 617 // $DOLLAR 618 // A dollar sign. 619 // $PATH 620 // The $PATH of the parent process, with $GOROOT/bin 621 // placed at the beginning. This causes generators 622 // that execute 'go' commands to use the same 'go' 623 // as the parent 'go generate' command. 624 // 625 // Other than variable substitution and quoted-string evaluation, no 626 // special processing such as "globbing" is performed on the command 627 // line. 628 // 629 // As a last step before running the command, any invocations of any 630 // environment variables with alphanumeric names, such as $GOFILE or 631 // $HOME, are expanded throughout the command line. The syntax for 632 // variable expansion is $NAME on all operating systems. Due to the 633 // order of evaluation, variables are expanded even inside quoted 634 // strings. If the variable NAME is not set, $NAME expands to the 635 // empty string. 636 // 637 // A directive of the form, 638 // 639 // //go:generate -command xxx args... 640 // 641 // specifies, for the remainder of this source file only, that the 642 // string xxx represents the command identified by the arguments. This 643 // can be used to create aliases or to handle multiword generators. 644 // For example, 645 // 646 // //go:generate -command foo go tool foo 647 // 648 // specifies that the command "foo" represents the generator 649 // "go tool foo". 650 // 651 // Generate processes packages in the order given on the command line, 652 // one at a time. If the command line lists .go files from a single directory, 653 // they are treated as a single package. Within a package, generate processes the 654 // source files in a package in file name order, one at a time. Within 655 // a source file, generate runs generators in the order they appear 656 // in the file, one at a time. The go generate tool also sets the build 657 // tag "generate" so that files may be examined by go generate but ignored 658 // during build. 659 // 660 // For packages with invalid code, generate processes only source files with a 661 // valid package clause. 662 // 663 // If any generator returns an error exit status, "go generate" skips 664 // all further processing for that package. 665 // 666 // The generator is run in the package's source directory. 667 // 668 // Go generate accepts two specific flags: 669 // 670 // -run="" 671 // if non-empty, specifies a regular expression to select 672 // directives whose full original source text (excluding 673 // any trailing spaces and final newline) matches the 674 // expression. 675 // 676 // -skip="" 677 // if non-empty, specifies a regular expression to suppress 678 // directives whose full original source text (excluding 679 // any trailing spaces and final newline) matches the 680 // expression. If a directive matches both the -run and 681 // the -skip arguments, it is skipped. 682 // 683 // It also accepts the standard build flags including -v, -n, and -x. 684 // The -v flag prints the names of packages and files as they are 685 // processed. 686 // The -n flag prints commands that would be executed. 687 // The -x flag prints commands as they are executed. 688 // 689 // For more about build flags, see 'go help build'. 690 // 691 // For more about specifying packages, see 'go help packages'. 692 // 693 // # Add dependencies to current module and install them 694 // 695 // Usage: 696 // 697 // go get [-t] [-u] [-tool] [build flags] [packages] 698 // 699 // Get resolves its command-line arguments to packages at specific module versions, 700 // updates go.mod to require those versions, and downloads source code into the 701 // module cache. 702 // 703 // To add a dependency for a package or upgrade it to its latest version: 704 // 705 // go get example.com/pkg 706 // 707 // To upgrade or downgrade a package to a specific version: 708 // 709 // go get example.com/pkg@v1.2.3 710 // 711 // To remove a dependency on a module and downgrade modules that require it: 712 // 713 // go get example.com/mod@none 714 // 715 // To upgrade the minimum required Go version to the latest released Go version: 716 // 717 // go get go@latest 718 // 719 // To upgrade the Go toolchain to the latest patch release of the current Go toolchain: 720 // 721 // go get toolchain@patch 722 // 723 // See https://go.dev/ref/mod#go-get for details. 724 // 725 // In earlier versions of Go, 'go get' was used to build and install packages. 726 // Now, 'go get' is dedicated to adjusting dependencies in go.mod. 'go install' 727 // may be used to build and install commands instead. When a version is specified, 728 // 'go install' runs in module-aware mode and ignores the go.mod file in the 729 // current directory. For example: 730 // 731 // go install example.com/pkg@v1.2.3 732 // go install example.com/pkg@latest 733 // 734 // See 'go help install' or https://go.dev/ref/mod#go-install for details. 735 // 736 // 'go get' accepts the following flags. 737 // 738 // The -t flag instructs get to consider modules needed to build tests of 739 // packages specified on the command line. 740 // 741 // The -u flag instructs get to update modules providing dependencies 742 // of packages named on the command line to use newer minor or patch 743 // releases when available. 744 // 745 // The -u=patch flag (not -u patch) also instructs get to update dependencies, 746 // but changes the default to select patch releases. 747 // 748 // When the -t and -u flags are used together, get will update 749 // test dependencies as well. 750 // 751 // The -tool flag instructs go to add a matching tool line to go.mod for each 752 // listed package. If -tool is used with @none, the line will be removed. 753 // See 'go help tool' for more information. 754 // 755 // The -x flag prints commands as they are executed. This is useful for 756 // debugging version control commands when a module is downloaded directly 757 // from a repository. 758 // 759 // For more about build flags, see 'go help build'. 760 // 761 // For more about modules, see https://go.dev/ref/mod. 762 // 763 // For more about using 'go get' to update the minimum Go version and 764 // suggested Go toolchain, see https://go.dev/doc/toolchain. 765 // 766 // For more about specifying packages, see 'go help packages'. 767 // 768 // See also: go build, go install, go clean, go mod. 769 // 770 // # Compile and install packages and dependencies 771 // 772 // Usage: 773 // 774 // go install [build flags] [packages] 775 // 776 // Install compiles and installs the packages named by the import paths. 777 // 778 // Executables are installed in the directory named by the GOBIN environment 779 // variable, which defaults to $GOPATH/bin or $HOME/go/bin if the GOPATH 780 // environment variable is not set. Executables in $GOROOT 781 // are installed in $GOROOT/bin or $GOTOOLDIR instead of $GOBIN. 782 // Cross compiled binaries are installed in $GOOS_$GOARCH subdirectories 783 // of the above. 784 // 785 // If the arguments have version suffixes (like @latest or @v1.0.0), "go install" 786 // builds packages in module-aware mode, ignoring the go.mod file in the current 787 // directory or any parent directory, if there is one. This is useful for 788 // installing executables without affecting the dependencies of the main module. 789 // To eliminate ambiguity about which module versions are used in the build, the 790 // arguments must satisfy the following constraints: 791 // 792 // - Arguments must be package paths or package patterns (with "..." wildcards). 793 // They must not be standard packages (like fmt), meta-patterns (std, cmd, 794 // all), or relative or absolute file paths. 795 // 796 // - All arguments must have the same version suffix. Different queries are not 797 // allowed, even if they refer to the same version. 798 // 799 // - All arguments must refer to packages in the same module at the same version. 800 // 801 // - Package path arguments must refer to main packages. Pattern arguments 802 // will only match main packages. 803 // 804 // - No module is considered the "main" module. If the module containing 805 // packages named on the command line has a go.mod file, it must not contain 806 // directives (replace and exclude) that would cause it to be interpreted 807 // differently than if it were the main module. The module must not require 808 // a higher version of itself. 809 // 810 // - Vendor directories are not used in any module. (Vendor directories are not 811 // included in the module zip files downloaded by 'go install'.) 812 // 813 // If the arguments don't have version suffixes, "go install" may run in 814 // module-aware mode or GOPATH mode, depending on the GO111MODULE environment 815 // variable and the presence of a go.mod file. See 'go help modules' for details. 816 // If module-aware mode is enabled, "go install" runs in the context of the main 817 // module. 818 // 819 // When module-aware mode is disabled, non-main packages are installed in the 820 // directory $GOPATH/pkg/$GOOS_$GOARCH. When module-aware mode is enabled, 821 // non-main packages are built and cached but not installed. 822 // 823 // Before Go 1.20, the standard library was installed to 824 // $GOROOT/pkg/$GOOS_$GOARCH. 825 // Starting in Go 1.20, the standard library is built and cached but not installed. 826 // Setting GODEBUG=installgoroot=all restores the use of 827 // $GOROOT/pkg/$GOOS_$GOARCH. 828 // 829 // For more about build flags, see 'go help build'. 830 // 831 // For more about specifying packages, see 'go help packages'. 832 // 833 // See also: go build, go get, go clean. 834 // 835 // # List packages or modules 836 // 837 // Usage: 838 // 839 // go list [-f format] [-json] [-m] [list flags] [build flags] [packages] 840 // 841 // List lists the named packages, one per line. 842 // The most commonly-used flags are -f and -json, which control the form 843 // of the output printed for each package. Other list flags, documented below, 844 // control more specific details. 845 // 846 // The default output shows the package import path: 847 // 848 // bytes 849 // encoding/json 850 // github.com/gorilla/mux 851 // golang.org/x/net/html 852 // 853 // The -f flag specifies an alternate format for the list, using the 854 // syntax of package template. The default output is equivalent 855 // to -f '{{.ImportPath}}'. The struct being passed to the template is: 856 // 857 // type Package struct { 858 // Dir string // directory containing package sources 859 // ImportPath string // import path of package in dir 860 // ImportComment string // path in import comment on package statement 861 // Name string // package name 862 // Doc string // package documentation string 863 // Target string // install path 864 // Shlib string // the shared library that contains this package (only set when -linkshared) 865 // Goroot bool // is this package in the Go root? 866 // Standard bool // is this package part of the standard Go library? 867 // Stale bool // would 'go install' do anything for this package? 868 // StaleReason string // explanation for Stale==true 869 // Root string // Go root or Go path dir containing this package 870 // ConflictDir string // this directory shadows Dir in $GOPATH 871 // BinaryOnly bool // binary-only package (no longer supported) 872 // ForTest string // package is only for use in named test 873 // Export string // file containing export data (when using -export) 874 // BuildID string // build ID of the exported package (when using -export) 875 // Module *Module // info about package's containing module, if any (can be nil) 876 // Match []string // command-line patterns matching this package 877 // DepOnly bool // package is only a dependency, not explicitly listed 878 // DefaultGODEBUG string // default GODEBUG setting, for main packages 879 // 880 // // Source files 881 // GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles) 882 // CgoFiles []string // .go source files that import "C" 883 // CompiledGoFiles []string // .go files presented to compiler (when using -compiled) 884 // IgnoredGoFiles []string // .go source files ignored due to build constraints 885 // IgnoredOtherFiles []string // non-.go source files ignored due to build constraints 886 // CFiles []string // .c source files 887 // CXXFiles []string // .cc, .cxx and .cpp source files 888 // MFiles []string // .m source files 889 // HFiles []string // .h, .hh, .hpp and .hxx source files 890 // FFiles []string // .f, .F, .for and .f90 Fortran source files 891 // SFiles []string // .s source files 892 // SwigFiles []string // .swig files 893 // SwigCXXFiles []string // .swigcxx files 894 // SysoFiles []string // .syso object files to add to archive 895 // TestGoFiles []string // _test.go files in package 896 // XTestGoFiles []string // _test.go files outside package 897 // 898 // // Embedded files 899 // EmbedPatterns []string // //go:embed patterns 900 // EmbedFiles []string // files matched by EmbedPatterns 901 // TestEmbedPatterns []string // //go:embed patterns in TestGoFiles 902 // TestEmbedFiles []string // files matched by TestEmbedPatterns 903 // XTestEmbedPatterns []string // //go:embed patterns in XTestGoFiles 904 // XTestEmbedFiles []string // files matched by XTestEmbedPatterns 905 // 906 // // Cgo directives 907 // CgoCFLAGS []string // cgo: flags for C compiler 908 // CgoCPPFLAGS []string // cgo: flags for C preprocessor 909 // CgoCXXFLAGS []string // cgo: flags for C++ compiler 910 // CgoFFLAGS []string // cgo: flags for Fortran compiler 911 // CgoLDFLAGS []string // cgo: flags for linker 912 // CgoPkgConfig []string // cgo: pkg-config names 913 // 914 // // Dependency information 915 // Imports []string // import paths used by this package 916 // ImportMap map[string]string // map from source import to ImportPath (identity entries omitted) 917 // Deps []string // all (recursively) imported dependencies 918 // TestImports []string // imports from TestGoFiles 919 // XTestImports []string // imports from XTestGoFiles 920 // 921 // // Error information 922 // Incomplete bool // this package or a dependency has an error 923 // Error *PackageError // error loading package 924 // DepsErrors []*PackageError // errors loading dependencies 925 // } 926 // 927 // Packages stored in vendor directories report an ImportPath that includes the 928 // path to the vendor directory (for example, "d/vendor/p" instead of "p"), 929 // so that the ImportPath uniquely identifies a given copy of a package. 930 // The Imports, Deps, TestImports, and XTestImports lists also contain these 931 // expanded import paths. See golang.org/s/go15vendor for more about vendoring. 932 // 933 // The error information, if any, is 934 // 935 // type PackageError struct { 936 // ImportStack []string // shortest path from package named on command line to this one 937 // Pos string // position of error (if present, file:line:col) 938 // Err string // the error itself 939 // } 940 // 941 // The module information is a Module struct, defined in the discussion 942 // of list -m below. 943 // 944 // The template function "join" calls strings.Join. 945 // 946 // The template function "json" marshals its arguments to JSON. 947 // 948 // The template function "context" returns the build context, defined as: 949 // 950 // type Context struct { 951 // GOARCH string // target architecture 952 // GOOS string // target operating system 953 // GOROOT string // Go root 954 // GOPATH string // Go path 955 // CgoEnabled bool // whether cgo can be used 956 // UseAllFiles bool // use files regardless of //go:build lines, file names 957 // Compiler string // compiler to assume when computing target paths 958 // BuildTags []string // build constraints to match in //go:build lines 959 // ToolTags []string // toolchain-specific build constraints 960 // ReleaseTags []string // releases the current release is compatible with 961 // InstallSuffix string // suffix to use in the name of the install dir 962 // } 963 // 964 // The template function "module" takes a module path as a parameter, 965 // and returns information about the module, defined as the Module struct below. 966 // 967 // For more information about the meaning of these fields see the documentation 968 // for the go/build package's Context type. 969 // 970 // The -json flag causes the package data to be printed in JSON format 971 // instead of using the template format. The JSON flag can optionally be 972 // provided with a set of comma-separated required field names to be output. 973 // If so, those required fields will always appear in JSON output, but 974 // others may be omitted to save work in computing the JSON struct. 975 // 976 // The -compiled flag causes list to set CompiledGoFiles to the Go source 977 // files presented to the compiler. Typically this means that it repeats 978 // the files listed in GoFiles and then also adds the Go code generated 979 // by processing CgoFiles and SwigFiles. The Imports list contains the 980 // union of all imports from both GoFiles and CompiledGoFiles. 981 // 982 // The -deps flag causes list to iterate over not just the named packages 983 // but also all their dependencies. It visits them in a depth-first post-order 984 // traversal, so that a package is listed only after all its dependencies. 985 // Packages not explicitly listed on the command line will have the DepOnly 986 // field set to true. 987 // 988 // The -e flag changes the handling of erroneous packages, those that 989 // cannot be found or are malformed. By default, the list command 990 // prints an error to standard error for each erroneous package and 991 // omits the packages from consideration during the usual printing. 992 // With the -e flag, the list command never prints errors to standard 993 // error and instead processes the erroneous packages with the usual 994 // printing. Erroneous packages will have a non-empty ImportPath and 995 // a non-nil Error field; other information may or may not be missing 996 // (zeroed). 997 // 998 // The -export flag causes list to set the Export field to the name of a 999 // file containing up-to-date export data for the given package, 1000 // and the BuildID field to the build ID of the exported package. 1001 // The Export file encodes complete type information for the package's 1002 // public API. To decode it, use the golang.org/x/tools/go/gcexportdata 1003 // package. 1004 // 1005 // The -find flag causes list to identify the named packages but not 1006 // resolve their dependencies: the Imports and Deps lists will be empty. 1007 // With the -find flag, the -deps, -test and -export commands cannot be 1008 // used. 1009 // 1010 // The -test flag causes list to report not only the named packages 1011 // but also their test binaries (for packages with tests), to convey to 1012 // source code analysis tools exactly how test binaries are constructed. 1013 // The reported import path for a test binary is the import path of 1014 // the package followed by a ".test" suffix, as in "math/rand.test". 1015 // When building a test, it is sometimes necessary to rebuild certain 1016 // dependencies specially for that test (most commonly the tested 1017 // package itself). The reported import path of a package recompiled 1018 // for a particular test binary is followed by a space and the name of 1019 // the test binary in brackets, as in "math/rand [math/rand.test]" 1020 // or "regexp [sort.test]". The ForTest field is also set to the name 1021 // of the package being tested ("math/rand" or "sort" in the previous 1022 // examples). 1023 // 1024 // The Dir, Target, Shlib, Root, ConflictDir, and Export file paths 1025 // are all absolute paths. 1026 // 1027 // By default, the lists GoFiles, CgoFiles, and so on hold names of files in Dir 1028 // (that is, paths relative to Dir, not absolute paths). 1029 // The generated files added when using the -compiled and -test flags 1030 // are absolute paths referring to cached copies of generated Go source files. 1031 // Although they are Go source files, the paths may not end in ".go". 1032 // 1033 // The -m flag causes list to list modules instead of packages. 1034 // 1035 // When listing modules, the -f flag still specifies a format template 1036 // applied to a Go struct, but now a Module struct: 1037 // 1038 // type Module struct { 1039 // Path string // module path 1040 // Query string // version query corresponding to this version 1041 // Version string // module version 1042 // Versions []string // available module versions 1043 // Replace *Module // replaced by this module 1044 // Time *time.Time // time version was created 1045 // Update *Module // available update (with -u) 1046 // Main bool // is this the main module? 1047 // Indirect bool // module is only indirectly needed by main module 1048 // Dir string // directory holding local copy of files, if any 1049 // GoMod string // path to go.mod file describing module, if any 1050 // GoVersion string // go version used in module 1051 // Retracted []string // retraction information, if any (with -retracted or -u) 1052 // Deprecated string // deprecation message, if any (with -u) 1053 // Error *ModuleError // error loading module 1054 // Sum string // checksum for path, version (as in go.sum) 1055 // GoModSum string // checksum for go.mod (as in go.sum) 1056 // Origin any // provenance of module 1057 // Reuse bool // reuse of old module info is safe 1058 // } 1059 // 1060 // type ModuleError struct { 1061 // Err string // the error itself 1062 // } 1063 // 1064 // The file GoMod refers to may be outside the module directory if the 1065 // module is in the module cache or if the -modfile flag is used. 1066 // 1067 // The default output is to print the module path and then 1068 // information about the version and replacement if any. 1069 // For example, 'go list -m all' might print: 1070 // 1071 // my/main/module 1072 // golang.org/x/text v0.3.0 => /tmp/text 1073 // rsc.io/pdf v0.1.1 1074 // 1075 // The Module struct has a String method that formats this 1076 // line of output, so that the default format is equivalent 1077 // to -f '{{.String}}'. 1078 // 1079 // Note that when a module has been replaced, its Replace field 1080 // describes the replacement module, and its Dir field is set to 1081 // the replacement's source code, if present. (That is, if Replace 1082 // is non-nil, then Dir is set to Replace.Dir, with no access to 1083 // the replaced source code.) 1084 // 1085 // The -u flag adds information about available upgrades. 1086 // When the latest version of a given module is newer than 1087 // the current one, list -u sets the Module's Update field 1088 // to information about the newer module. list -u will also set 1089 // the module's Retracted field if the current version is retracted. 1090 // The Module's String method indicates an available upgrade by 1091 // formatting the newer version in brackets after the current version. 1092 // If a version is retracted, the string "(retracted)" will follow it. 1093 // For example, 'go list -m -u all' might print: 1094 // 1095 // my/main/module 1096 // golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text 1097 // rsc.io/pdf v0.1.1 (retracted) [v0.1.2] 1098 // 1099 // (For tools, 'go list -m -u -json all' may be more convenient to parse.) 1100 // 1101 // The -versions flag causes list to set the Module's Versions field 1102 // to a list of all known versions of that module, ordered according 1103 // to semantic versioning, earliest to latest. The flag also changes 1104 // the default output format to display the module path followed by the 1105 // space-separated version list. 1106 // 1107 // The -retracted flag causes list to report information about retracted 1108 // module versions. When -retracted is used with -f or -json, the Retracted 1109 // field explains why the version was retracted. 1110 // The strings are taken from comments on the retract directive in the 1111 // module's go.mod file. When -retracted is used with -versions, retracted 1112 // versions are listed together with unretracted versions. The -retracted 1113 // flag may be used with or without -m. 1114 // 1115 // The arguments to list -m are interpreted as a list of modules, not packages. 1116 // The main module is the module containing the current directory. 1117 // The active modules are the main module and its dependencies. 1118 // With no arguments, list -m shows the main module. 1119 // With arguments, list -m shows the modules specified by the arguments. 1120 // Any of the active modules can be specified by its module path. 1121 // The special pattern "all" specifies all the active modules, first the main 1122 // module and then dependencies sorted by module path. 1123 // A pattern containing "..." specifies the active modules whose 1124 // module paths match the pattern. 1125 // A query of the form path@version specifies the result of that query, 1126 // which is not limited to active modules. 1127 // See 'go help modules' for more about module queries. 1128 // 1129 // The template function "module" takes a single string argument 1130 // that must be a module path or query and returns the specified 1131 // module as a Module struct. If an error occurs, the result will 1132 // be a Module struct with a non-nil Error field. 1133 // 1134 // When using -m, the -reuse=old.json flag accepts the name of file containing 1135 // the JSON output of a previous 'go list -m -json' invocation with the 1136 // same set of modifier flags (such as -u, -retracted, and -versions). 1137 // The go command may use this file to determine that a module is unchanged 1138 // since the previous invocation and avoid redownloading information about it. 1139 // Modules that are not redownloaded will be marked in the new output by 1140 // setting the Reuse field to true. Normally the module cache provides this 1141 // kind of reuse automatically; the -reuse flag can be useful on systems that 1142 // do not preserve the module cache. 1143 // 1144 // For more about build flags, see 'go help build'. 1145 // 1146 // For more about specifying packages, see 'go help packages'. 1147 // 1148 // For more about modules, see https://go.dev/ref/mod. 1149 // 1150 // # Module maintenance 1151 // 1152 // Go mod provides access to operations on modules. 1153 // 1154 // Note that support for modules is built into all the go commands, 1155 // not just 'go mod'. For example, day-to-day adding, removing, upgrading, 1156 // and downgrading of dependencies should be done using 'go get'. 1157 // See 'go help modules' for an overview of module functionality. 1158 // 1159 // Usage: 1160 // 1161 // go mod <command> [arguments] 1162 // 1163 // The commands are: 1164 // 1165 // download download modules to local cache 1166 // edit edit go.mod from tools or scripts 1167 // graph print module requirement graph 1168 // init initialize new module in current directory 1169 // tidy add missing and remove unused modules 1170 // vendor make vendored copy of dependencies 1171 // verify verify dependencies have expected content 1172 // why explain why packages or modules are needed 1173 // 1174 // Use "go help mod <command>" for more information about a command. 1175 // 1176 // # Download modules to local cache 1177 // 1178 // Usage: 1179 // 1180 // go mod download [-x] [-json] [-reuse=old.json] [modules] 1181 // 1182 // Download downloads the named modules, which can be module patterns selecting 1183 // dependencies of the main module or module queries of the form path@version. 1184 // 1185 // With no arguments, download applies to the modules needed to build and test 1186 // the packages in the main module: the modules explicitly required by the main 1187 // module if it is at 'go 1.17' or higher, or all transitively-required modules 1188 // if at 'go 1.16' or lower. 1189 // 1190 // The go command will automatically download modules as needed during ordinary 1191 // execution. The "go mod download" command is useful mainly for pre-filling 1192 // the local cache or to compute the answers for a Go module proxy. 1193 // 1194 // By default, download writes nothing to standard output. It may print progress 1195 // messages and errors to standard error. 1196 // 1197 // The -json flag causes download to print a sequence of JSON objects 1198 // to standard output, describing each downloaded module (or failure), 1199 // corresponding to this Go struct: 1200 // 1201 // type Module struct { 1202 // Path string // module path 1203 // Query string // version query corresponding to this version 1204 // Version string // module version 1205 // Error string // error loading module 1206 // Info string // absolute path to cached .info file 1207 // GoMod string // absolute path to cached .mod file 1208 // Zip string // absolute path to cached .zip file 1209 // Dir string // absolute path to cached source root directory 1210 // Sum string // checksum for path, version (as in go.sum) 1211 // GoModSum string // checksum for go.mod (as in go.sum) 1212 // Origin any // provenance of module 1213 // Reuse bool // reuse of old module info is safe 1214 // } 1215 // 1216 // The -reuse flag accepts the name of file containing the JSON output of a 1217 // previous 'go mod download -json' invocation. The go command may use this 1218 // file to determine that a module is unchanged since the previous invocation 1219 // and avoid redownloading it. Modules that are not redownloaded will be marked 1220 // in the new output by setting the Reuse field to true. Normally the module 1221 // cache provides this kind of reuse automatically; the -reuse flag can be 1222 // useful on systems that do not preserve the module cache. 1223 // 1224 // The -x flag causes download to print the commands download executes. 1225 // 1226 // See https://go.dev/ref/mod#go-mod-download for more about 'go mod download'. 1227 // 1228 // See https://go.dev/ref/mod#version-queries for more about version queries. 1229 // 1230 // # Edit go.mod from tools or scripts 1231 // 1232 // Usage: 1233 // 1234 // go mod edit [editing flags] [-fmt|-print|-json] [go.mod] 1235 // 1236 // Edit provides a command-line interface for editing go.mod, 1237 // for use primarily by tools or scripts. It reads only go.mod; 1238 // it does not look up information about the modules involved. 1239 // By default, edit reads and writes the go.mod file of the main module, 1240 // but a different target file can be specified after the editing flags. 1241 // 1242 // The editing flags specify a sequence of editing operations. 1243 // 1244 // The -fmt flag reformats the go.mod file without making other changes. 1245 // This reformatting is also implied by any other modifications that use or 1246 // rewrite the go.mod file. The only time this flag is needed is if no other 1247 // flags are specified, as in 'go mod edit -fmt'. 1248 // 1249 // The -module flag changes the module's path (the go.mod file's module line). 1250 // 1251 // The -godebug=key=value flag adds a godebug key=value line, 1252 // replacing any existing godebug lines with the given key. 1253 // 1254 // The -dropgodebug=key flag drops any existing godebug lines 1255 // with the given key. 1256 // 1257 // The -require=path@version and -droprequire=path flags 1258 // add and drop a requirement on the given module path and version. 1259 // Note that -require overrides any existing requirements on path. 1260 // These flags are mainly for tools that understand the module graph. 1261 // Users should prefer 'go get path@version' or 'go get path@none', 1262 // which make other go.mod adjustments as needed to satisfy 1263 // constraints imposed by other modules. 1264 // 1265 // The -go=version flag sets the expected Go language version. 1266 // This flag is mainly for tools that understand Go version dependencies. 1267 // It takes a version like "1.26" or "1.26.2". 1268 // Using the version "none" removes the go directive. 1269 // Users should prefer 'go get go@version'. 1270 // 1271 // The -toolchain=name flag sets the Go toolchain to use. 1272 // This flag is mainly for tools that understand Go version dependencies. 1273 // It takes a toolchain name like "go1.26" or "go1.26.2". 1274 // Using the name "none" removes the toolchain directive. 1275 // Users should prefer 'go get toolchain@version'. 1276 // 1277 // The -exclude=path@version and -dropexclude=path@version flags 1278 // add and drop an exclusion for the given module path and version. 1279 // Note that -exclude=path@version is a no-op if that exclusion already exists. 1280 // 1281 // The -replace=old[@v]=new[@v] flag adds a replacement of the given 1282 // module path and version pair. If the @v in old@v is omitted, a 1283 // replacement without a version on the left side is added, which applies 1284 // to all versions of the old module path. If the @v in new@v is omitted, 1285 // the new path should be a local module root directory, not a module 1286 // path. Note that -replace overrides any redundant replacements for old[@v], 1287 // so omitting @v will drop existing replacements for specific versions. 1288 // 1289 // The -dropreplace=old[@v] flag drops a replacement of the given 1290 // module path and version pair. If the @v is omitted, a replacement without 1291 // a version on the left side is dropped. 1292 // 1293 // The -retract=version and -dropretract=version flags add and drop a 1294 // retraction on the given version. The version may be a single version 1295 // like "v1.2.3" or a closed interval like "[v1.1.0,v1.1.9]". Note that 1296 // -retract=version is a no-op if that retraction already exists. 1297 // 1298 // The -tool=path and -droptool=path flags add and drop a tool declaration 1299 // for the given path. 1300 // 1301 // The -ignore=path and -dropignore=path flags add and drop a ignore declaration 1302 // for the given path. 1303 // 1304 // The -godebug, -dropgodebug, -require, -droprequire, -exclude, -dropexclude, 1305 // -replace, -dropreplace, -retract, -dropretract, -tool, -droptool, -ignore, 1306 // and -dropignore editing flags may be repeated, and the changes are applied 1307 // in the order given. 1308 // 1309 // The -print flag prints the final go.mod in its text format instead of 1310 // writing it back to go.mod. 1311 // 1312 // The -json flag prints the final go.mod file in JSON format instead of 1313 // writing it back to go.mod. The JSON output corresponds to these Go types: 1314 // 1315 // type GoMod struct { 1316 // Module ModPath 1317 // Go string 1318 // Toolchain string 1319 // Godebug []Godebug 1320 // Require []Require 1321 // Exclude []Module 1322 // Replace []Replace 1323 // Retract []Retract 1324 // Tool []Tool 1325 // Ignore []Ignore 1326 // } 1327 // 1328 // type Module struct { 1329 // Path string 1330 // Version string 1331 // } 1332 // 1333 // type ModPath struct { 1334 // Path string 1335 // Deprecated string 1336 // } 1337 // 1338 // type Godebug struct { 1339 // Key string 1340 // Value string 1341 // } 1342 // 1343 // type Require struct { 1344 // Path string 1345 // Version string 1346 // Indirect bool 1347 // } 1348 // 1349 // type Replace struct { 1350 // Old Module 1351 // New Module 1352 // } 1353 // 1354 // type Retract struct { 1355 // Low string 1356 // High string 1357 // Rationale string 1358 // } 1359 // 1360 // type Tool struct { 1361 // Path string 1362 // } 1363 // 1364 // type Ignore struct { 1365 // Path string 1366 // } 1367 // 1368 // Retract entries representing a single version (not an interval) will have 1369 // the "Low" and "High" fields set to the same value. 1370 // 1371 // Note that this only describes the go.mod file itself, not other modules 1372 // referred to indirectly. For the full set of modules available to a build, 1373 // use 'go list -m -json all'. 1374 // 1375 // Edit also provides the -C, -n, and -x build flags. 1376 // 1377 // See https://go.dev/ref/mod#go-mod-edit for more about 'go mod edit'. 1378 // 1379 // # Print module requirement graph 1380 // 1381 // Usage: 1382 // 1383 // go mod graph [-go=version] [-x] 1384 // 1385 // Graph prints the module requirement graph (with replacements applied) 1386 // in text form. Each line in the output has two space-separated fields: a module 1387 // and one of its requirements. Each module is identified as a string of the form 1388 // path@version, except for the main module, which has no @version suffix. 1389 // 1390 // The -go flag causes graph to report the module graph as loaded by the 1391 // given Go version, instead of the version indicated by the 'go' directive 1392 // in the go.mod file. 1393 // 1394 // The -x flag causes graph to print the commands graph executes. 1395 // 1396 // See https://go.dev/ref/mod#go-mod-graph for more about 'go mod graph'. 1397 // 1398 // # Initialize new module in current directory 1399 // 1400 // Usage: 1401 // 1402 // go mod init [module-path] 1403 // 1404 // Init initializes and writes a new go.mod file in the current directory, in 1405 // effect creating a new module rooted at the current directory. The go.mod file 1406 // must not already exist. 1407 // 1408 // Init accepts one optional argument, the module path for the new module. If the 1409 // module path argument is omitted, init will attempt to infer the module path 1410 // using import comments in .go files and the current directory (if in GOPATH). 1411 // 1412 // See https://go.dev/ref/mod#go-mod-init for more about 'go mod init'. 1413 // 1414 // # Add missing and remove unused modules 1415 // 1416 // Usage: 1417 // 1418 // go mod tidy [-e] [-v] [-x] [-diff] [-go=version] [-compat=version] 1419 // 1420 // Tidy makes sure go.mod matches the source code in the module. 1421 // It adds any missing modules necessary to build the current module's 1422 // packages and dependencies, and it removes unused modules that 1423 // don't provide any relevant packages. It also adds any missing entries 1424 // to go.sum and removes any unnecessary ones. 1425 // 1426 // The -v flag causes tidy to print information about removed modules 1427 // to standard error. 1428 // 1429 // The -e flag causes tidy to attempt to proceed despite errors 1430 // encountered while loading packages. 1431 // 1432 // The -diff flag causes tidy not to modify go.mod or go.sum but 1433 // instead print the necessary changes as a unified diff. It exits 1434 // with a non-zero code if the diff is not empty. 1435 // 1436 // The -go flag causes tidy to update the 'go' directive in the go.mod 1437 // file to the given version, which may change which module dependencies 1438 // are retained as explicit requirements in the go.mod file. 1439 // (Go versions 1.17 and higher retain more requirements in order to 1440 // support lazy module loading.) 1441 // 1442 // The -compat flag preserves any additional checksums needed for the 1443 // 'go' command from the indicated major Go release to successfully load 1444 // the module graph, and causes tidy to error out if that version of the 1445 // 'go' command would load any imported package from a different module 1446 // version. By default, tidy acts as if the -compat flag were set to the 1447 // version prior to the one indicated by the 'go' directive in the go.mod 1448 // file. 1449 // 1450 // The -x flag causes tidy to print the commands download executes. 1451 // 1452 // See https://go.dev/ref/mod#go-mod-tidy for more about 'go mod tidy'. 1453 // 1454 // # Make vendored copy of dependencies 1455 // 1456 // Usage: 1457 // 1458 // go mod vendor [-e] [-v] [-o outdir] 1459 // 1460 // Vendor resets the main module's vendor directory to include all packages 1461 // needed to build and test all the main module's packages. 1462 // It does not include test code for vendored packages. 1463 // 1464 // The -v flag causes vendor to print the names of vendored 1465 // modules and packages to standard error. 1466 // 1467 // The -e flag causes vendor to attempt to proceed despite errors 1468 // encountered while loading packages. 1469 // 1470 // The -o flag causes vendor to create the vendor directory at the given 1471 // path instead of "vendor". The go command can only use a vendor directory 1472 // named "vendor" within the module root directory, so this flag is 1473 // primarily useful for other tools. 1474 // 1475 // See https://go.dev/ref/mod#go-mod-vendor for more about 'go mod vendor'. 1476 // 1477 // # Verify dependencies have expected content 1478 // 1479 // Usage: 1480 // 1481 // go mod verify 1482 // 1483 // Verify checks that the dependencies of the current module, 1484 // which are stored in a local downloaded source cache, have not been 1485 // modified since being downloaded. If all the modules are unmodified, 1486 // verify prints "all modules verified." Otherwise it reports which 1487 // modules have been changed and causes 'go mod' to exit with a 1488 // non-zero status. 1489 // 1490 // See https://go.dev/ref/mod#go-mod-verify for more about 'go mod verify'. 1491 // 1492 // # Explain why packages or modules are needed 1493 // 1494 // Usage: 1495 // 1496 // go mod why [-m] [-vendor] packages... 1497 // 1498 // Why shows a shortest path in the import graph from the main module to 1499 // each of the listed packages. If the -m flag is given, why treats the 1500 // arguments as a list of modules and finds a path to any package in each 1501 // of the modules. 1502 // 1503 // By default, why queries the graph of packages matched by "go list all", 1504 // which includes tests for reachable packages. The -vendor flag causes why 1505 // to exclude tests of dependencies. 1506 // 1507 // The output is a sequence of stanzas, one for each package or module 1508 // name on the command line, separated by blank lines. Each stanza begins 1509 // with a comment line "# package" or "# module" giving the target 1510 // package or module. Subsequent lines give a path through the import 1511 // graph, one package per line. If the package or module is not 1512 // referenced from the main module, the stanza will display a single 1513 // parenthesized note indicating that fact. 1514 // 1515 // If any of the listed packages or modules is not referenced from 1516 // the main module, why exits with a non-zero status. 1517 // 1518 // For example: 1519 // 1520 // $ go mod why golang.org/x/text/language golang.org/x/text/encoding 1521 // # golang.org/x/text/language 1522 // rsc.io/quote 1523 // rsc.io/sampler 1524 // golang.org/x/text/language 1525 // 1526 // # golang.org/x/text/encoding 1527 // (main module does not need package golang.org/x/text/encoding) 1528 // $ 1529 // 1530 // See https://go.dev/ref/mod#go-mod-why for more about 'go mod why'. 1531 // 1532 // # Compile and run Go program 1533 // 1534 // Usage: 1535 // 1536 // go run [build flags] [-exec xprog] package [arguments...] 1537 // 1538 // Run compiles and runs the named main Go package. 1539 // Typically the package is specified as a list of .go source files from a single 1540 // directory, but it may also be an import path, file system path, or pattern 1541 // matching a single known package, as in 'go run .' or 'go run my/cmd'. 1542 // 1543 // If the package argument has a version suffix (like @latest or @v1.0.0), 1544 // "go run" builds the program in module-aware mode, ignoring the go.mod file in 1545 // the current directory or any parent directory, if there is one. This is useful 1546 // for running programs without affecting the dependencies of the main module. 1547 // 1548 // If the package argument doesn't have a version suffix, "go run" may run in 1549 // module-aware mode or GOPATH mode, depending on the GO111MODULE environment 1550 // variable and the presence of a go.mod file. See 'go help modules' for details. 1551 // If module-aware mode is enabled, "go run" runs in the context of the main 1552 // module. 1553 // 1554 // By default, 'go run' runs the compiled binary directly: 'a.out arguments...'. 1555 // If the -exec flag is given, 'go run' invokes the binary using xprog: 1556 // 1557 // 'xprog a.out arguments...'. 1558 // 1559 // If the -exec flag is not given, GOOS or GOARCH is different from the system 1560 // default, and a program named go_$GOOS_$GOARCH_exec can be found 1561 // on the current search path, 'go run' invokes the binary using that program, 1562 // for example 'go_js_wasm_exec a.out arguments...'. This allows execution of 1563 // cross-compiled programs when a simulator or other execution method is 1564 // available. 1565 // 1566 // By default, 'go run' compiles the binary without generating the information 1567 // used by debuggers, to reduce build time. To include debugger information in 1568 // the binary, use 'go build'. 1569 // 1570 // The go command places $GOROOT/bin at the beginning of $PATH in the 1571 // subprocess environment, so that subprocesses that execute 'go' commands 1572 // use the same 'go' as their parent. 1573 // 1574 // The exit status of Run is not the exit status of the compiled binary. 1575 // 1576 // For more about build flags, see 'go help build'. 1577 // For more about specifying packages, see 'go help packages'. 1578 // 1579 // See also: go build. 1580 // 1581 // # Manage telemetry data and settings 1582 // 1583 // Usage: 1584 // 1585 // go telemetry [off|local|on] 1586 // 1587 // Telemetry is used to manage Go telemetry data and settings. 1588 // 1589 // Telemetry can be in one of three modes: off, local, or on. 1590 // 1591 // When telemetry is in local mode, counter data is written to the local file 1592 // system, but will not be uploaded to remote servers. 1593 // 1594 // When telemetry is off, local counter data is neither collected nor uploaded. 1595 // 1596 // When telemetry is on, telemetry data is written to the local file system 1597 // and periodically sent to https://telemetry.go.dev/. Uploaded data is used to 1598 // help improve the Go toolchain and related tools, and it will be published as 1599 // part of a public dataset. 1600 // 1601 // For more details, see https://telemetry.go.dev/privacy. 1602 // This data is collected in accordance with the Google Privacy Policy 1603 // (https://policies.google.com/privacy). 1604 // 1605 // To view the current telemetry mode, run "go telemetry". 1606 // To disable telemetry uploading, but keep local data collection, run 1607 // "go telemetry local". 1608 // To enable both collection and uploading, run “go telemetry on”. 1609 // To disable both collection and uploading, run "go telemetry off". 1610 // 1611 // The current telemetry mode is also available as the value of the 1612 // non-settable "GOTELEMETRY" go env variable. The directory in the 1613 // local file system that telemetry data is written to is available 1614 // as the value of the non-settable "GOTELEMETRYDIR" go env variable. 1615 // 1616 // See https://go.dev/doc/telemetry for more information on telemetry. 1617 // 1618 // # Test packages 1619 // 1620 // Usage: 1621 // 1622 // go test [build/test flags] [packages] [build/test flags & test binary flags] 1623 // 1624 // 'Go test' automates testing the packages named by the import paths. 1625 // It prints a summary of the test results in the format: 1626 // 1627 // ok archive/tar 0.011s 1628 // FAIL archive/zip 0.022s 1629 // ok compress/gzip 0.033s 1630 // ... 1631 // 1632 // followed by detailed output for each failed package. 1633 // 1634 // 'Go test' recompiles each package along with any files with names matching 1635 // the file pattern "*_test.go". 1636 // These additional files can contain test functions, benchmark functions, fuzz 1637 // tests and example functions. See 'go help testfunc' for more. 1638 // Each listed package causes the execution of a separate test binary. 1639 // Files whose names begin with "_" (including "_test.go") or "." are ignored. 1640 // 1641 // Test files that declare a package with the suffix "_test" will be compiled as a 1642 // separate package, and then linked and run with the main test binary. 1643 // 1644 // The go tool will ignore a directory named "testdata", making it available 1645 // to hold ancillary data needed by the tests. 1646 // 1647 // As part of building a test binary, go test runs go vet on the package 1648 // and its test source files to identify significant problems. If go vet 1649 // finds any problems, go test reports those and does not run the test 1650 // binary. Only a high-confidence subset of the default go vet checks are 1651 // used. That subset is: atomic, bools, buildtag, directive, errorsas, 1652 // ifaceassert, nilfunc, printf, stdversion, stringintconv, and tests. 1653 // You can see the documentation for these and other vet tests via 1654 // "go doc cmd/vet". To disable the running of go vet, use the -vet=off flag. 1655 // To run all checks, use the -vet=all flag. 1656 // 1657 // All test output and summary lines are printed to the go command's 1658 // standard output, even if the test printed them to its own standard 1659 // error. (The go command's standard error is reserved for printing 1660 // errors building the tests.) 1661 // 1662 // The go command places $GOROOT/bin at the beginning of $PATH 1663 // in the test's environment, so that tests that execute 1664 // 'go' commands use the same 'go' as the parent 'go test' command. 1665 // 1666 // Go test runs in two different modes: 1667 // 1668 // The first, called local directory mode, occurs when go test is 1669 // invoked with no package arguments (for example, 'go test' or 'go 1670 // test -v'). In this mode, go test compiles the package sources and 1671 // tests found in the current directory and then runs the resulting 1672 // test binary. In this mode, caching (discussed below) is disabled. 1673 // After the package test finishes, go test prints a summary line 1674 // showing the test status ('ok' or 'FAIL'), package name, and elapsed 1675 // time. 1676 // 1677 // The second, called package list mode, occurs when go test is invoked 1678 // with explicit package arguments (for example 'go test math', 'go 1679 // test ./...', and even 'go test .'). In this mode, go test compiles 1680 // and tests each of the packages listed on the command line. If a 1681 // package test passes, go test prints only the final 'ok' summary 1682 // line. If a package test fails, go test prints the full test output. 1683 // If invoked with the -bench or -v flag, go test prints the full 1684 // output even for passing package tests, in order to display the 1685 // requested benchmark results or verbose logging. After the package 1686 // tests for all of the listed packages finish, and their output is 1687 // printed, go test prints a final 'FAIL' status if any package test 1688 // has failed. 1689 // 1690 // In package list mode only, go test caches successful package test 1691 // results to avoid unnecessary repeated running of tests. When the 1692 // result of a test can be recovered from the cache, go test will 1693 // redisplay the previous output instead of running the test binary 1694 // again. When this happens, go test prints '(cached)' in place of the 1695 // elapsed time in the summary line. 1696 // 1697 // The rule for a match in the cache is that the run involves the same 1698 // test binary and the flags on the command line come entirely from a 1699 // restricted set of 'cacheable' test flags, defined as -benchtime, 1700 // -coverprofile, -cpu, -failfast, -fullpath, -list, -outputdir, -parallel, 1701 // -run, -short, -skip, -timeout and -v. 1702 // If a run of go test has any test or non-test flags outside this set, 1703 // the result is not cached. To disable test caching, use any test flag 1704 // or argument other than the cacheable flags. The idiomatic way to disable 1705 // test caching explicitly is to use -count=1. Tests that open files within 1706 // the package's module or that consult environment variables only 1707 // match future runs in which the files and environment variables are 1708 // unchanged. A cached test result is treated as executing in no time 1709 // at all, so a successful package test result will be cached and 1710 // reused regardless of -timeout setting. 1711 // 1712 // In addition to the build flags, the flags handled by 'go test' itself are: 1713 // 1714 // -args 1715 // Pass the remainder of the command line (everything after -args) 1716 // to the test binary, uninterpreted and unchanged. 1717 // Because this flag consumes the remainder of the command line, 1718 // the package list (if present) must appear before this flag. 1719 // 1720 // -c 1721 // Compile the test binary to pkg.test in the current directory but do not run it 1722 // (where pkg is the last element of the package's import path). 1723 // The file name or target directory can be changed with the -o flag. 1724 // 1725 // -exec xprog 1726 // Run the test binary using xprog. The behavior is the same as 1727 // in 'go run'. See 'go help run' for details. 1728 // 1729 // -json 1730 // Convert test output to JSON suitable for automated processing. 1731 // See 'go doc test2json' for the encoding details. 1732 // Also emits build output in JSON. See 'go help buildjson'. 1733 // 1734 // -o file 1735 // Save a copy of the test binary to the named file. 1736 // The test still runs (unless -c is specified). 1737 // If file ends in a slash or names an existing directory, 1738 // the test is written to pkg.test in that directory. 1739 // 1740 // The test binary also accepts flags that control execution of the test; these 1741 // flags are also accessible by 'go test'. See 'go help testflag' for details. 1742 // 1743 // For more about build flags, see 'go help build'. 1744 // For more about specifying packages, see 'go help packages'. 1745 // 1746 // See also: go build, go vet. 1747 // 1748 // # Run specified go tool 1749 // 1750 // Usage: 1751 // 1752 // go tool [-n] command [args...] 1753 // 1754 // Tool runs the go tool command identified by the arguments. 1755 // 1756 // Go ships with a number of builtin tools, and additional tools 1757 // may be defined in the go.mod of the current module. 'go get -tool' 1758 // can be used to define additional tools in the current module's 1759 // go.mod file. See 'go help get' for more information. 1760 // 1761 // The command can be specified using the full package path to the tool declared with 1762 // a tool directive. The default binary name of the tool, which is the last component of 1763 // the package path, excluding the major version suffix, can also be used if it is unique 1764 // among declared tools. 1765 // 1766 // With no arguments it prints the list of known tools. 1767 // 1768 // The -n flag causes tool to print the command that would be 1769 // executed but not execute it. 1770 // 1771 // The -modfile=file.mod build flag causes tool to use an alternate file 1772 // instead of the go.mod in the module root directory. 1773 // 1774 // Tool also provides the -C, -overlay, and -modcacherw build flags. 1775 // 1776 // The go command places $GOROOT/bin at the beginning of $PATH in the 1777 // environment of commands run via tool directives, so that they use the 1778 // same 'go' as the parent 'go tool'. 1779 // 1780 // For more about build flags, see 'go help build'. 1781 // 1782 // For more about each builtin tool command, see 'go doc cmd/<command>'. 1783 // 1784 // # Print Go version 1785 // 1786 // Usage: 1787 // 1788 // go version [-m] [-v] [-json] [file ...] 1789 // 1790 // Version prints the build information for Go binary files. 1791 // 1792 // Go version reports the Go version used to build each of the named files. 1793 // 1794 // If no files are named on the command line, go version prints its own 1795 // version information. 1796 // 1797 // If a directory is named, go version walks that directory, recursively, 1798 // looking for recognized Go binaries and reporting their versions. 1799 // By default, go version does not report unrecognized files found 1800 // during a directory scan. The -v flag causes it to report unrecognized files. 1801 // 1802 // The -m flag causes go version to print each file's embedded 1803 // module version information, when available. In the output, the module 1804 // information consists of multiple lines following the version line, each 1805 // indented by a leading tab character. 1806 // 1807 // The -json flag is similar to -m but outputs the runtime/debug.BuildInfo in JSON format. 1808 // If flag -json is specified without -m, go version reports an error. 1809 // 1810 // See also: go doc runtime/debug.BuildInfo. 1811 // 1812 // # Report likely mistakes in packages 1813 // 1814 // Usage: 1815 // 1816 // go vet [build flags] [-vettool prog] [vet flags] [packages] 1817 // 1818 // Vet runs the Go vet tool (cmd/vet) on the named packages 1819 // and reports diagnostics. 1820 // 1821 // It supports these flags: 1822 // 1823 // -c int 1824 // display offending line with this many lines of context (default -1) 1825 // -json 1826 // emit JSON output 1827 // -fix 1828 // instead of printing each diagnostic, apply its first fix (if any) 1829 // -diff 1830 // instead of applying each fix, print the patch as a unified diff; 1831 // exit with a non-zero status if the diff is not empty 1832 // 1833 // The -vettool=prog flag selects a different analysis tool with 1834 // alternative or additional checks. For example, the 'shadow' analyzer 1835 // can be built and run using these commands: 1836 // 1837 // go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow@latest 1838 // go vet -vettool=$(which shadow) 1839 // 1840 // Alternative vet tools should be built atop golang.org/x/tools/go/analysis/unitchecker, 1841 // which handles the interaction with go vet. 1842 // 1843 // The default vet tool is 'go tool vet' or cmd/vet. 1844 // For help on its checkers and their flags, run 'go tool vet help'. 1845 // For details of a specific checker such as 'printf', see 'go tool vet help printf'. 1846 // 1847 // For more about specifying packages, see 'go help packages'. 1848 // 1849 // The build flags supported by go vet are those that control package resolution 1850 // and execution, such as -C, -n, -x, -v, -tags, and -toolexec. 1851 // For more about these flags, see 'go help build'. 1852 // 1853 // See also: go fmt, go fix. 1854 // 1855 // # Workspace maintenance 1856 // 1857 // Work provides access to operations on workspaces. 1858 // 1859 // Note that support for workspaces is built into many other commands, not 1860 // just 'go work'. 1861 // 1862 // See 'go help modules' for information about Go's module system of which 1863 // workspaces are a part. 1864 // 1865 // See https://go.dev/ref/mod#workspaces for an in-depth reference on 1866 // workspaces. 1867 // 1868 // See https://go.dev/doc/tutorial/workspaces for an introductory 1869 // tutorial on workspaces. 1870 // 1871 // A workspace is specified by a go.work file that specifies a set of 1872 // module directories with the "use" directive. These modules are used as 1873 // root modules by the go command for builds and related operations. A 1874 // workspace that does not specify modules to be used cannot be used to do 1875 // builds from local modules. 1876 // 1877 // go.work files are line-oriented. Each line holds a single directive, 1878 // made up of a keyword followed by arguments. For example: 1879 // 1880 // go 1.18 1881 // 1882 // use ../foo/bar 1883 // use ./baz 1884 // 1885 // replace example.com/foo v1.2.3 => example.com/bar v1.4.5 1886 // 1887 // The leading keyword can be factored out of adjacent lines to create a block, 1888 // like in Go imports. 1889 // 1890 // use ( 1891 // ../foo/bar 1892 // ./baz 1893 // ) 1894 // 1895 // The use directive specifies a module to be included in the workspace's 1896 // set of main modules. The argument to the use directive is the directory 1897 // containing the module's go.mod file. The go command does not resolve 1898 // symbolic links when matching use paths to module directories, so a 1899 // symlink to a directory is not interchangeable with its target. 1900 // 1901 // The go directive specifies the version of Go the file was written at. It 1902 // is possible there may be future changes in the semantics of workspaces 1903 // that could be controlled by this version, but for now the version 1904 // specified has no effect. 1905 // 1906 // The replace directive has the same syntax as the replace directive in a 1907 // go.mod file and takes precedence over replaces in go.mod files. It is 1908 // primarily intended to override conflicting replaces in different workspace 1909 // modules. 1910 // 1911 // To determine whether the go command is operating in workspace mode, use 1912 // the "go env GOWORK" command. This will specify the workspace file being 1913 // used. 1914 // 1915 // Usage: 1916 // 1917 // go work <command> [arguments] 1918 // 1919 // The commands are: 1920 // 1921 // edit edit go.work from tools or scripts 1922 // init initialize workspace file 1923 // sync sync workspace build list to modules 1924 // use add modules to workspace file 1925 // vendor make vendored copy of dependencies 1926 // 1927 // Use "go help work <command>" for more information about a command. 1928 // 1929 // # Edit go.work from tools or scripts 1930 // 1931 // Usage: 1932 // 1933 // go work edit [editing flags] [go.work] 1934 // 1935 // Edit provides a command-line interface for editing go.work, 1936 // for use primarily by tools or scripts. It only reads go.work; 1937 // it does not look up information about the modules involved. 1938 // If no file is specified, Edit looks for a go.work file in the current 1939 // directory and its parent directories 1940 // 1941 // The editing flags specify a sequence of editing operations. 1942 // 1943 // The -fmt flag reformats the go.work file without making other changes. 1944 // This reformatting is also implied by any other modifications that use or 1945 // rewrite the go.work file. The only time this flag is needed is if no other 1946 // flags are specified, as in 'go work edit -fmt'. 1947 // 1948 // The -godebug=key=value flag adds a godebug key=value line, 1949 // replacing any existing godebug lines with the given key. 1950 // 1951 // The -dropgodebug=key flag drops any existing godebug lines 1952 // with the given key. 1953 // 1954 // The -use=path and -dropuse=path flags 1955 // add and drop a use directive from the go.work file's set of module directories. 1956 // 1957 // The -replace=old[@v]=new[@v] flag adds a replacement of the given 1958 // module path and version pair. If the @v in old@v is omitted, a 1959 // replacement without a version on the left side is added, which applies 1960 // to all versions of the old module path. If the @v in new@v is omitted, 1961 // the new path should be a local module root directory, not a module 1962 // path. Note that -replace overrides any redundant replacements for old[@v], 1963 // so omitting @v will drop existing replacements for specific versions. 1964 // 1965 // The -dropreplace=old[@v] flag drops a replacement of the given 1966 // module path and version pair. If the @v is omitted, a replacement without 1967 // a version on the left side is dropped. 1968 // 1969 // The -use, -dropuse, -replace, and -dropreplace, 1970 // editing flags may be repeated, and the changes are applied in the order given. 1971 // 1972 // The -go=version flag sets the expected Go language version. 1973 // It takes a version like "1.26" or "1.26.2". 1974 // Using "none" as the version removes the go directive. 1975 // 1976 // The -toolchain=name flag sets the Go toolchain to use. 1977 // It takes a toolchain name like "go1.26" or "go1.26.2". 1978 // Using "none" as the name removes the toolchain directive. 1979 // 1980 // The -print flag prints the final go.work in its text format instead of 1981 // writing it back to go.work. 1982 // 1983 // The -json flag prints the final go.work file in JSON format instead of 1984 // writing it back to go.work. The JSON output corresponds to these Go types: 1985 // 1986 // type GoWork struct { 1987 // Go string 1988 // Toolchain string 1989 // Godebug []Godebug 1990 // Use []Use 1991 // Replace []Replace 1992 // } 1993 // 1994 // type Godebug struct { 1995 // Key string 1996 // Value string 1997 // } 1998 // 1999 // type Use struct { 2000 // DiskPath string 2001 // ModulePath string 2002 // } 2003 // 2004 // type Replace struct { 2005 // Old Module 2006 // New Module 2007 // } 2008 // 2009 // type Module struct { 2010 // Path string 2011 // Version string 2012 // } 2013 // 2014 // See the workspaces reference at https://go.dev/ref/mod#workspaces 2015 // for more information. 2016 // 2017 // # Initialize workspace file 2018 // 2019 // Usage: 2020 // 2021 // go work init [moddirs] 2022 // 2023 // Init initializes and writes a new go.work file in the 2024 // current directory, in effect creating a new workspace at the current 2025 // directory. 2026 // 2027 // go work init optionally accepts paths to the workspace modules as 2028 // arguments. If the argument is omitted, an empty workspace with no 2029 // modules will be created. 2030 // 2031 // Each argument path is added to a use directive in the go.work file. The 2032 // current go version will also be listed in the go.work file. 2033 // 2034 // See the workspaces reference at https://go.dev/ref/mod#workspaces 2035 // for more information. 2036 // 2037 // # Sync workspace build list to modules 2038 // 2039 // Usage: 2040 // 2041 // go work sync 2042 // 2043 // Sync syncs the workspace's build list back to the 2044 // workspace's modules 2045 // 2046 // The workspace's build list is the set of versions of all the 2047 // (transitive) dependency modules used to do builds in the workspace. go 2048 // work sync generates that build list using the Minimal Version Selection 2049 // algorithm, and then syncs those versions back to each of modules 2050 // specified in the workspace (with use directives). 2051 // 2052 // The syncing is done by sequentially upgrading each of the dependency 2053 // modules specified in a workspace module to the version in the build list 2054 // if the dependency module's version is not already the same as the build 2055 // list's version. Note that Minimal Version Selection guarantees that the 2056 // build list's version of each module is always the same or higher than 2057 // that in each workspace module. 2058 // 2059 // See the workspaces reference at https://go.dev/ref/mod#workspaces 2060 // for more information. 2061 // 2062 // # Add modules to workspace file 2063 // 2064 // Usage: 2065 // 2066 // go work use [-r] [moddirs] 2067 // 2068 // Use provides a command-line interface for adding 2069 // directories, optionally recursively, to a go.work file. 2070 // 2071 // A use directive will be added to the go.work file for each argument 2072 // directory listed on the command line go.work file, if it exists, 2073 // or removed from the go.work file if it does not exist. 2074 // Use fails if any remaining use directives refer to modules that 2075 // do not exist. 2076 // 2077 // Use updates the go line in go.work to specify a version at least as 2078 // new as all the go lines in the used modules, both preexisting ones 2079 // and newly added ones. With no arguments, this update is the only 2080 // thing that go work use does. 2081 // 2082 // The -r flag searches recursively for modules in the argument 2083 // directories, and the use command operates as if each of the directories 2084 // were specified as arguments. When -r is used, symlinks to directories 2085 // within the argument tree are ignored. 2086 // 2087 // The go command matches use paths to module directories without resolving 2088 // symbolic links. A use directive that names a symlink to a directory is 2089 // not interchangeable with one that names the symlink's target. 2090 // 2091 // See the workspaces reference at https://go.dev/ref/mod#workspaces 2092 // for more information. 2093 // 2094 // # Make vendored copy of dependencies 2095 // 2096 // Usage: 2097 // 2098 // go work vendor [-e] [-v] [-o outdir] 2099 // 2100 // Vendor resets the workspace's vendor directory to include all packages 2101 // needed to build and test all the workspace's packages. 2102 // It does not include test code for vendored packages. 2103 // 2104 // The -v flag causes vendor to print the names of vendored 2105 // modules and packages to standard error. 2106 // 2107 // The -e flag causes vendor to attempt to proceed despite errors 2108 // encountered while loading packages. 2109 // 2110 // The -o flag causes vendor to create the vendor directory at the given 2111 // path instead of "vendor". The go command can only use a vendor directory 2112 // named "vendor" within the module root directory, so this flag is 2113 // primarily useful for other tools. 2114 // 2115 // # Build constraints 2116 // 2117 // A build constraint, also known as a build tag, is a condition under which a 2118 // file should be included in the package. Build constraints are given by a 2119 // line comment that begins 2120 // 2121 // //go:build 2122 // 2123 // Build constraints can also be used to downgrade the language version 2124 // used to compile a file. 2125 // 2126 // Constraints may appear in any kind of source file (not just Go), but 2127 // they must appear near the top of the file, preceded 2128 // only by blank lines and other comments. These rules mean that in Go 2129 // files a build constraint must appear before the package clause. 2130 // 2131 // To distinguish build constraints from package documentation, 2132 // a build constraint should be followed by a blank line. 2133 // 2134 // A build constraint comment is evaluated as an expression containing 2135 // build tags combined by ||, &&, and ! operators and parentheses. 2136 // Operators have the same meaning as in Go. 2137 // 2138 // For example, the following build constraint constrains a file to 2139 // build when the "linux" and "386" constraints are satisfied, or when 2140 // "darwin" is satisfied and "cgo" is not: 2141 // 2142 // //go:build (linux && 386) || (darwin && !cgo) 2143 // 2144 // It is an error for a file to have more than one //go:build line. 2145 // 2146 // During a particular build, the following build tags are satisfied: 2147 // 2148 // - the target operating system, as spelled by runtime.GOOS, set with the 2149 // GOOS environment variable. 2150 // - the target architecture, as spelled by runtime.GOARCH, set with the 2151 // GOARCH environment variable. 2152 // - any architecture features, in the form GOARCH.feature 2153 // (for example, "amd64.v2"), as detailed below. 2154 // - "unix", if GOOS is a Unix or Unix-like system. 2155 // - the compiler being used, either "gc" or "gccgo" 2156 // - "cgo", if the cgo command is supported (see CGO_ENABLED in 2157 // 'go help environment'). 2158 // - a term for each Go major release, through the current version: 2159 // "go1.1" from Go version 1.1 onward, "go1.12" from Go 1.12, and so on. 2160 // - any additional tags given by the -tags flag (see 'go help build'). 2161 // 2162 // There are no separate build tags for beta or minor releases. 2163 // 2164 // If a file's name, after stripping the extension and a possible _test suffix, 2165 // matches any of the following patterns: 2166 // 2167 // *_GOOS 2168 // *_GOARCH 2169 // *_GOOS_GOARCH 2170 // 2171 // (example: source_windows_amd64.go) where GOOS and GOARCH represent 2172 // any known operating system and architecture values respectively, then 2173 // the file is considered to have an implicit build constraint requiring 2174 // those terms (in addition to any explicit constraints in the file). 2175 // 2176 // Using GOOS=android matches build tags and files as for GOOS=linux 2177 // in addition to android tags and files. 2178 // 2179 // Using GOOS=illumos matches build tags and files as for GOOS=solaris 2180 // in addition to illumos tags and files. 2181 // 2182 // Using GOOS=ios matches build tags and files as for GOOS=darwin 2183 // in addition to ios tags and files. 2184 // 2185 // The defined architecture feature build tags are: 2186 // 2187 // - For GOARCH=386, GO386=387 and GO386=sse2 2188 // set the 386.387 and 386.sse2 build tags, respectively. 2189 // - For GOARCH=amd64, GOAMD64=v1, v2, and v3 2190 // correspond to the amd64.v1, amd64.v2, and amd64.v3 feature build tags. 2191 // - For GOARCH=arm, GOARM=5, 6, and 7 2192 // correspond to the arm.5, arm.6, and arm.7 feature build tags. 2193 // - For GOARCH=arm64, GOARM64=v8.{0-9} and v9.{0-5} 2194 // correspond to the arm64.v8.{0-9} and arm64.v9.{0-5} feature build tags. 2195 // - For GOARCH=mips or mipsle, 2196 // GOMIPS=hardfloat and softfloat 2197 // correspond to the mips.hardfloat and mips.softfloat 2198 // (or mipsle.hardfloat and mipsle.softfloat) feature build tags. 2199 // - For GOARCH=mips64 or mips64le, 2200 // GOMIPS64=hardfloat and softfloat 2201 // correspond to the mips64.hardfloat and mips64.softfloat 2202 // (or mips64le.hardfloat and mips64le.softfloat) feature build tags. 2203 // - For GOARCH=ppc64 or ppc64le, 2204 // GOPPC64=power8, power9, and power10 correspond to the 2205 // ppc64.power8, ppc64.power9, and ppc64.power10 2206 // (or ppc64le.power8, ppc64le.power9, and ppc64le.power10) 2207 // feature build tags. 2208 // - For GOARCH=riscv64, 2209 // GORISCV64=rva20u64, rva22u64 and rva23u64 correspond to the riscv64.rva20u64, 2210 // riscv64.rva22u64 and riscv64.rva23u64 build tags. 2211 // - For GOARCH=wasm, GOWASM=satconv and signext 2212 // correspond to the wasm.satconv and wasm.signext feature build tags. 2213 // 2214 // For GOARCH=amd64, arm, ppc64, ppc64le, and riscv64, a particular feature level 2215 // sets the feature build tags for all previous levels as well. 2216 // For example, GOAMD64=v2 sets the amd64.v1 and amd64.v2 feature flags. 2217 // This ensures that code making use of v2 features continues to compile 2218 // when, say, GOAMD64=v4 is introduced. 2219 // Code handling the absence of a particular feature level 2220 // should use a negation: 2221 // 2222 // //go:build !amd64.v2 2223 // 2224 // To keep a file from being considered for any build: 2225 // 2226 // //go:build ignore 2227 // 2228 // (Any other unsatisfied word will work as well, but "ignore" is conventional.) 2229 // 2230 // To build a file only when using cgo, and only on Linux and OS X: 2231 // 2232 // //go:build cgo && (linux || darwin) 2233 // 2234 // Such a file is usually paired with another file implementing the 2235 // default functionality for other systems, which in this case would 2236 // carry the constraint: 2237 // 2238 // //go:build !(cgo && (linux || darwin)) 2239 // 2240 // Naming a file dns_windows.go will cause it to be included only when 2241 // building the package for Windows; similarly, math_386.s will be included 2242 // only when building the package for 32-bit x86. 2243 // 2244 // By convention, packages with assembly implementations may provide a go-only 2245 // version under the "purego" build constraint. This does not limit the use of 2246 // cgo (use the "cgo" build constraint) or unsafe. For example: 2247 // 2248 // //go:build purego 2249 // 2250 // Go versions 1.16 and earlier used a different syntax for build constraints, 2251 // with a "// +build" prefix. The gofmt command will add an equivalent //go:build 2252 // constraint when encountering the older syntax. 2253 // 2254 // In modules with a Go version of 1.21 or later, if a file's build constraint 2255 // has a term for a Go major release, the language version used when compiling 2256 // the file will be the minimum version implied by the build constraint. 2257 // 2258 // # Build -json encoding 2259 // 2260 // The 'go build', 'go install', and 'go test' commands take a -json flag that 2261 // reports build output and failures as structured JSON output on standard 2262 // output. 2263 // 2264 // The JSON stream is a newline-separated sequence of BuildEvent objects 2265 // corresponding to the Go struct: 2266 // 2267 // type BuildEvent struct { 2268 // ImportPath string 2269 // Action string 2270 // Output string 2271 // } 2272 // 2273 // The ImportPath field gives the package ID of the package being built. 2274 // This matches the Package.ImportPath field of go list -json and the 2275 // TestEvent.FailedBuild field of go test -json. Note that it does not 2276 // match TestEvent.Package. 2277 // 2278 // The Action field is one of the following: 2279 // 2280 // build-output - The toolchain printed output 2281 // build-fail - The build failed 2282 // 2283 // The Output field is set for Action == "build-output" and is a portion of 2284 // the build's output. The concatenation of the Output fields of all output 2285 // events is the exact output of the build. A single event may contain one 2286 // or more lines of output and there may be more than one output event for 2287 // a given ImportPath. This matches the definition of the TestEvent.Output 2288 // field produced by go test -json. 2289 // 2290 // For go test -json, this struct is designed so that parsers can distinguish 2291 // interleaved TestEvents and BuildEvents by inspecting the Action field. 2292 // Furthermore, as with TestEvent, parsers can simply concatenate the Output 2293 // fields of all events to reconstruct the text format output, as it would 2294 // have appeared from go build without the -json flag. 2295 // 2296 // Note that there may also be non-JSON error text on standard error, even 2297 // with the -json flag. Typically, this indicates an early, serious error. 2298 // Consumers should be robust to this. 2299 // 2300 // # Build modes 2301 // 2302 // The 'go build' and 'go install' commands take a -buildmode argument which 2303 // indicates which kind of object file is to be built. Currently supported values 2304 // are: 2305 // 2306 // -buildmode=archive 2307 // Build the listed non-main packages into .a files. Packages named 2308 // main are ignored. 2309 // 2310 // -buildmode=c-archive 2311 // Build the listed main package, plus all packages it imports, 2312 // into a C archive file. The only callable symbols will be those 2313 // functions exported using a cgo //export comment. Requires 2314 // exactly one main package to be listed. 2315 // 2316 // -buildmode=c-shared 2317 // Build the listed main package, plus all packages it imports, 2318 // into a C shared library. The only callable symbols will 2319 // be those functions exported using a cgo //export comment. 2320 // On wasip1, this mode builds it to a WASI reactor/library, 2321 // of which the callable symbols are those functions exported 2322 // using a //go:wasmexport directive. Requires exactly one 2323 // main package to be listed. 2324 // 2325 // -buildmode=default 2326 // Listed main packages are built into executables and listed 2327 // non-main packages are built into .a files (the default 2328 // behavior). 2329 // 2330 // -buildmode=shared 2331 // Combine all the listed non-main packages into a single shared 2332 // library that will be used when building with the -linkshared 2333 // option. Packages named main are ignored. 2334 // 2335 // -buildmode=exe 2336 // Build the listed main packages and everything they import into 2337 // executables. Packages not named main are ignored. 2338 // 2339 // -buildmode=pie 2340 // Build the listed main packages and everything they import into 2341 // position independent executables (PIE). Packages not named 2342 // main are ignored. 2343 // 2344 // -buildmode=plugin 2345 // Build the listed main packages, plus all packages that they 2346 // import, into a Go plugin. Packages not named main are ignored. 2347 // 2348 // On AIX, when linking a C program that uses a Go archive built with 2349 // -buildmode=c-archive, you must pass -Wl,-bnoobjreorder to the C compiler. 2350 // 2351 // # Calling between Go and C 2352 // 2353 // There are two different ways to call between Go and C/C++ code. 2354 // 2355 // The first is the cgo tool, which is part of the Go distribution. For 2356 // information on how to use it see the cgo documentation (go doc cmd/cgo). 2357 // 2358 // The second is the SWIG program, which is a general tool for 2359 // interfacing between languages. For information on SWIG see 2360 // https://swig.org/. When running go build, any file with a .swig 2361 // extension will be passed to SWIG. Any file with a .swigcxx extension 2362 // will be passed to SWIG with the -c++ option. A package can't be just 2363 // a .swig or .swigcxx file; there must be at least one .go file, even if 2364 // it has just a package clause. 2365 // 2366 // When either cgo or SWIG is used, go build will pass any .c, .m, .s, .S 2367 // or .sx files to the C compiler, and any .cc, .cpp, .cxx files to the C++ 2368 // compiler. The CC or CXX environment variables may be set to determine 2369 // the C or C++ compiler, respectively, to use. 2370 // 2371 // # Build and test caching 2372 // 2373 // The go command caches build outputs for reuse in future builds. 2374 // The default location for cache data is a subdirectory named go-build 2375 // in the standard user cache directory for the current operating system. 2376 // The cache is safe for concurrent invocations of the go command. 2377 // Setting the GOCACHE environment variable overrides this default, 2378 // and running 'go env GOCACHE' prints the current cache directory. 2379 // 2380 // The go command periodically deletes cached data that has not been 2381 // used recently. Running 'go clean -cache' deletes all cached data. 2382 // 2383 // The build cache correctly accounts for changes to Go source files, 2384 // compilers, compiler options, and so on: cleaning the cache explicitly 2385 // should not be necessary in typical use. However, the build cache 2386 // does not detect changes to C libraries imported with cgo. 2387 // If you have made changes to the C libraries on your system, you 2388 // will need to clean the cache explicitly or else use the -a build flag 2389 // (see 'go help build') to force rebuilding of packages that 2390 // depend on the updated C libraries. 2391 // 2392 // The go command also caches successful package test results. 2393 // See 'go help test' for details. Running 'go clean -testcache' removes 2394 // all cached test results (but not cached build results). 2395 // 2396 // The go command also caches values used in fuzzing with 'go test -fuzz', 2397 // specifically, values that expanded code coverage when passed to a 2398 // fuzz function. These values are not used for regular building and 2399 // testing, but they're stored in a subdirectory of the build cache. 2400 // Running 'go clean -fuzzcache' removes all cached fuzzing values. 2401 // This may make fuzzing less effective, temporarily. 2402 // 2403 // The GODEBUG environment variable can enable printing of debugging 2404 // information about the state of the cache: 2405 // 2406 // GODEBUG=gocacheverify=1 causes the go command to bypass the 2407 // use of any cache entries and instead rebuild everything and check 2408 // that the results match existing cache entries. 2409 // 2410 // GODEBUG=gocachehash=1 causes the go command to print the inputs 2411 // for all of the content hashes it uses to construct cache lookup keys. 2412 // The output is voluminous but can be useful for debugging the cache. 2413 // 2414 // GODEBUG=gocachetest=1 causes the go command to print details of its 2415 // decisions about whether to reuse a cached test result. 2416 // 2417 // The GOCACHEPROG environment variable can be used to provide an 2418 // externally managed build cache. For details see: 2419 // "go doc cmd/go/internal/cacheprog". 2420 // 2421 // # Environment variables 2422 // 2423 // The go command and the tools it invokes consult environment variables 2424 // for configuration. If an environment variable is unset or empty, the go 2425 // command uses a sensible default setting. To see the effective setting of 2426 // the variable <NAME>, run 'go env <NAME>'. To change the default setting, 2427 // run 'go env -w <NAME>=<VALUE>'. Defaults changed using 'go env -w' 2428 // are recorded in a Go environment configuration file stored in the 2429 // per-user configuration directory, as reported by os.UserConfigDir. 2430 // The location of the configuration file can be changed by setting 2431 // the environment variable GOENV, and 'go env GOENV' prints the 2432 // effective location, but 'go env -w' cannot change the default location. 2433 // See 'go help env' for details. 2434 // 2435 // General-purpose environment variables: 2436 // 2437 // GCCGO 2438 // The gccgo command to run for 'go build -compiler=gccgo'. 2439 // GO111MODULE 2440 // Controls whether the go command runs in module-aware mode or GOPATH mode. 2441 // May be "off", "on", or "auto". 2442 // See https://go.dev/ref/mod#mod-commands. 2443 // GOARCH 2444 // The architecture, or processor, for which to compile code. 2445 // Examples are amd64, 386, arm, ppc64. 2446 // GOAUTH 2447 // Controls authentication for go-import and HTTPS module mirror interactions. 2448 // See 'go help goauth'. 2449 // GOBIN 2450 // The directory where 'go install' will install a command. 2451 // GOCACHE 2452 // The directory where the go command will store cached 2453 // information for reuse in future builds. Must be an absolute path. 2454 // GOCACHEPROG 2455 // A command (with optional space-separated flags) that implements an 2456 // external go command build cache. 2457 // See 'go doc cmd/go/internal/cacheprog'. 2458 // GODEBUG 2459 // Enable various debugging facilities for programs built with Go, 2460 // including the go command. Cannot be set using 'go env -w'. 2461 // See https://go.dev/doc/godebug for details. 2462 // GOENV 2463 // The location of the Go environment configuration file. 2464 // Cannot be set using 'go env -w'. 2465 // Setting GOENV=off in the environment disables the use of the 2466 // default configuration file. 2467 // GOFLAGS 2468 // A space-separated list of -flag=value settings to apply 2469 // to go commands by default, when the given flag is known by 2470 // the current command. Each entry must be a standalone flag. 2471 // Because the entries are space-separated, flag values must 2472 // not contain spaces. Flags listed on the command line 2473 // are applied after this list and therefore override it. 2474 // GOINSECURE 2475 // Comma-separated list of glob patterns (in the syntax of Go's path.Match) 2476 // of module path prefixes that should always be fetched in an insecure 2477 // manner. Only applies to dependencies that are being fetched directly. 2478 // GOINSECURE does not disable checksum database validation. GOPRIVATE or 2479 // GONOSUMDB may be used to achieve that. 2480 // GOMODCACHE 2481 // The directory where the go command will store downloaded modules. 2482 // GOOS 2483 // The operating system for which to compile code. 2484 // Examples are linux, darwin, windows, netbsd. 2485 // GOPATH 2486 // Controls where various files are stored. See: 'go help gopath'. 2487 // GOPRIVATE, GONOPROXY, GONOSUMDB 2488 // Comma-separated list of glob patterns (in the syntax of Go's path.Match) 2489 // of module path prefixes that should always be fetched directly 2490 // or that should not be compared against the checksum database. 2491 // See https://go.dev/ref/mod#private-modules. 2492 // GOPROXY 2493 // URL of Go module proxy. See https://go.dev/ref/mod#environment-variables 2494 // and https://go.dev/ref/mod#module-proxy for details. 2495 // GOROOT 2496 // The root of the go tree. 2497 // GOSUMDB 2498 // The name of checksum database to use and optionally its public key and 2499 // URL. See https://go.dev/ref/mod#authenticating. 2500 // GOTMPDIR 2501 // Temporary directory used by the go command and testing package. 2502 // Overrides the platform-specific temporary directory such as "/tmp". 2503 // The go command and testing package will write temporary source files, 2504 // packages, and binaries here. 2505 // GOTOOLCHAIN 2506 // Controls which Go toolchain is used. See https://go.dev/doc/toolchain. 2507 // GOVCS 2508 // Lists version control commands that may be used with matching servers. 2509 // See 'go help vcs'. 2510 // GOWORK 2511 // In module aware mode, use the given go.work file as a workspace file. 2512 // By default or when GOWORK is "auto", the go command searches for a 2513 // file named go.work in the current directory and then containing directories 2514 // until one is found. If a valid go.work file is found, the modules 2515 // specified will collectively be used as the main modules. If GOWORK 2516 // is "off", or a go.work file is not found in "auto" mode, workspace 2517 // mode is disabled. 2518 // 2519 // Environment variables for use with cgo: 2520 // 2521 // AR 2522 // The command to use to manipulate library archives when 2523 // building with the gccgo compiler. 2524 // The default is 'ar'. 2525 // CC 2526 // The command to use to compile C code. 2527 // CGO_CFLAGS 2528 // Flags that cgo will pass to the compiler when compiling 2529 // C code. 2530 // CGO_CFLAGS_ALLOW 2531 // A regular expression specifying additional flags to allow 2532 // to appear in #cgo CFLAGS source code directives. 2533 // Does not apply to the CGO_CFLAGS environment variable. 2534 // CGO_CFLAGS_DISALLOW 2535 // A regular expression specifying flags that must be disallowed 2536 // from appearing in #cgo CFLAGS source code directives. 2537 // Does not apply to the CGO_CFLAGS environment variable. 2538 // CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW 2539 // Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW, 2540 // but for the C preprocessor. 2541 // CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW 2542 // Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW, 2543 // but for the C++ compiler. 2544 // CGO_ENABLED 2545 // Whether the cgo command is supported. Either 0 or 1. 2546 // CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW 2547 // Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW, 2548 // but for the Fortran compiler. 2549 // CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW 2550 // Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW, 2551 // but for the linker. 2552 // CXX 2553 // The command to use to compile C++ code. 2554 // FC 2555 // The command to use to compile Fortran code. 2556 // PKG_CONFIG 2557 // Path to pkg-config tool. 2558 // 2559 // Architecture-specific environment variables: 2560 // 2561 // GO386 2562 // For GOARCH=386, how to implement floating point instructions. 2563 // Valid values are sse2 (default), softfloat. 2564 // GOAMD64 2565 // For GOARCH=amd64, the microarchitecture level for which to compile. 2566 // Valid values are v1 (default), v2, v3, v4. 2567 // See https://go.dev/wiki/MinimumRequirements#amd64 2568 // GOARM 2569 // For GOARCH=arm, the ARM architecture for which to compile. 2570 // Valid values are 5, 6, 7. 2571 // When the Go tools are built on an arm system, 2572 // the default value is set based on what the build system supports. 2573 // When the Go tools are not built on an arm system 2574 // (that is, when building a cross-compiler), 2575 // the default value is 7. 2576 // The value can be followed by an option specifying how to implement floating point instructions. 2577 // Valid options are ,softfloat (default for 5) and ,hardfloat (default for 6 and 7). 2578 // GOARM64 2579 // For GOARCH=arm64, the ARM64 architecture for which to compile. 2580 // Valid values are v8.0 (default), v8.{1-9}, v9.{0-5}. 2581 // The value can be followed by an option specifying extensions implemented by target hardware. 2582 // Valid options are ,lse and ,crypto. 2583 // Note that some extensions are enabled by default starting from a certain GOARM64 version; 2584 // for example, lse is enabled by default starting from v8.1. 2585 // GOMIPS 2586 // For GOARCH=mips{,le}, whether to use floating point instructions. 2587 // Valid values are hardfloat (default), softfloat. 2588 // GOMIPS64 2589 // For GOARCH=mips64{,le}, whether to use floating point instructions. 2590 // Valid values are hardfloat (default), softfloat. 2591 // GOPPC64 2592 // For GOARCH=ppc64{,le}, the target ISA (Instruction Set Architecture). 2593 // Valid values are power8 (default), power9, power10. 2594 // GORISCV64 2595 // For GOARCH=riscv64, the RISC-V user-mode application profile for which 2596 // to compile. Valid values are rva20u64 (default), rva22u64, rva23u64. 2597 // See https://github.com/riscv/riscv-profiles/blob/main/src/profiles.adoc 2598 // and https://github.com/riscv/riscv-profiles/blob/main/src/rva23-profile.adoc 2599 // GOWASM 2600 // For GOARCH=wasm, comma-separated list of experimental WebAssembly features to use. 2601 // Valid values are satconv, signext. 2602 // 2603 // Environment variables for use with code coverage: 2604 // 2605 // GOCOVERDIR 2606 // Directory into which to write code coverage data files 2607 // generated by running a "go build -cover" binary. 2608 // 2609 // Special-purpose environment variables: 2610 // 2611 // GCCGOTOOLDIR 2612 // If set, where to find gccgo tools, such as cgo. 2613 // The default is based on how gccgo was configured. 2614 // GOEXPERIMENT 2615 // Comma-separated list of toolchain experiments to enable or disable. 2616 // The list of available experiments may change arbitrarily over time. 2617 // See GOROOT/src/internal/goexperiment/flags.go for currently valid values. 2618 // Warning: This variable is provided for the development and testing 2619 // of the Go toolchain itself. Use beyond that purpose is unsupported. 2620 // GOFIPS140 2621 // The FIPS-140 cryptography mode to use when building binaries. 2622 // The default is GOFIPS140=off, which makes no FIPS-140 changes at all. 2623 // Other values enable FIPS-140 compliance measures and select alternate 2624 // versions of the cryptography source code. 2625 // See https://go.dev/doc/security/fips140 for details. 2626 // GO_EXTLINK_ENABLED 2627 // Whether the linker should use external linking mode 2628 // when using -linkmode=auto with code that uses cgo. 2629 // Set to 0 to disable external linking mode, 1 to enable it. 2630 // GIT_ALLOW_PROTOCOL 2631 // Defined by Git. A colon-separated list of schemes that are allowed 2632 // to be used with git fetch/clone. If set, any scheme not explicitly 2633 // mentioned will be considered insecure by 'go get'. 2634 // Because the variable is defined by Git, the default value cannot 2635 // be set using 'go env -w'. 2636 // 2637 // Additional information available from 'go env' but not read from the environment: 2638 // 2639 // GOEXE 2640 // The executable file name suffix (".exe" on Windows, "" on other systems). 2641 // GOGCCFLAGS 2642 // A space-separated list of arguments supplied to the CC command. 2643 // GOHOSTARCH 2644 // The architecture (GOARCH) of the Go toolchain binaries. 2645 // GOHOSTOS 2646 // The operating system (GOOS) of the Go toolchain binaries. 2647 // GOMOD 2648 // The absolute path to the go.mod of the main module. 2649 // If module-aware mode is enabled, but there is no go.mod, GOMOD will be 2650 // os.DevNull ("/dev/null" on Unix-like systems, "NUL" on Windows). 2651 // If module-aware mode is disabled, GOMOD will be the empty string. 2652 // GOTELEMETRY 2653 // The current Go telemetry mode ("off", "local", or "on"). 2654 // See "go help telemetry" for more information. 2655 // GOTELEMETRYDIR 2656 // The directory Go telemetry data is written is written to. 2657 // GOTOOLDIR 2658 // The directory where the go tools (compile, cover, doc, etc...) are installed. 2659 // GOVERSION 2660 // The version of the installed Go tree, as reported by runtime.Version. 2661 // 2662 // # File types 2663 // 2664 // The go command examines the contents of a restricted set of files 2665 // in each directory. It identifies which files to examine based on 2666 // the extension of the file name. These extensions are: 2667 // 2668 // .go 2669 // Go source files. 2670 // .c, .h 2671 // C source files. 2672 // If the package uses cgo or SWIG, these will be compiled with the 2673 // OS-native compiler (typically gcc); otherwise they will 2674 // trigger an error. 2675 // .cc, .cpp, .cxx, .hh, .hpp, .hxx 2676 // C++ source files. Only useful with cgo or SWIG, and always 2677 // compiled with the OS-native compiler. 2678 // .m 2679 // Objective-C source files. Only useful with cgo, and always 2680 // compiled with the OS-native compiler. 2681 // .s, .S, .sx 2682 // Assembler source files. 2683 // If the package uses cgo or SWIG, these will be assembled with the 2684 // OS-native assembler (typically gcc (sic)); otherwise they 2685 // will be assembled with the Go assembler. 2686 // .swig, .swigcxx 2687 // SWIG definition files. 2688 // .syso 2689 // System object files. 2690 // 2691 // Files of each of these types except .syso may contain build 2692 // constraints, but the go command stops scanning for build constraints 2693 // at the first item in the file that is not a blank line or //-style 2694 // line comment. See the go/build package documentation for 2695 // more details. 2696 // 2697 // # GOAUTH environment variable 2698 // 2699 // GOAUTH is a semicolon-separated list of authentication commands for go-import and 2700 // HTTPS module mirror interactions. The default is netrc. 2701 // 2702 // The supported authentication commands are: 2703 // 2704 // off 2705 // 2706 // Disables authentication. 2707 // 2708 // netrc 2709 // 2710 // Uses credentials from NETRC or the .netrc file in your home directory. 2711 // 2712 // git dir 2713 // 2714 // Runs 'git credential fill' in dir and uses its credentials. The 2715 // go command will run 'git credential approve/reject' to update 2716 // the credential helper's cache. 2717 // 2718 // command 2719 // 2720 // Executes the given command (a space-separated argument list) and attaches 2721 // the provided headers to HTTPS requests. 2722 // The command must produce output in the following format: 2723 // Response = { CredentialSet } . 2724 // CredentialSet = URLLine { URLLine } BlankLine { HeaderLine } BlankLine . 2725 // URLLine = /* URL that starts with "https://" */ '\n' . 2726 // HeaderLine = /* HTTP Request header */ '\n' . 2727 // BlankLine = '\n' . 2728 // 2729 // Example: 2730 // https://example.com 2731 // https://example.net/api/ 2732 // 2733 // Authorization: Basic <token> 2734 // 2735 // https://another-example.org/ 2736 // 2737 // Example: Data 2738 // 2739 // If the server responds with any 4xx code, the go command will write the 2740 // following to the program's stdin: 2741 // Response = StatusLine { HeaderLine } BlankLine . 2742 // StatusLine = Protocol Space Status '\n' . 2743 // Protocol = /* HTTP protocol */ . 2744 // Space = ' ' . 2745 // Status = /* HTTP status code */ . 2746 // BlankLine = '\n' . 2747 // HeaderLine = /* HTTP Response's header */ '\n' . 2748 // 2749 // Example: 2750 // HTTP/1.1 401 Unauthorized 2751 // Content-Length: 19 2752 // Content-Type: text/plain; charset=utf-8 2753 // Date: Thu, 07 Nov 2024 18:43:09 GMT 2754 // 2755 // Note: it is safe to use net/http.ReadResponse to parse this input. 2756 // 2757 // Before the first HTTPS fetch, the go command will invoke each GOAUTH 2758 // command in the list with no additional arguments and no input. 2759 // If the server responds with any 4xx code, the go command will invoke the 2760 // GOAUTH commands again with the URL as an additional command-line argument 2761 // and the HTTP Response to the program's stdin. 2762 // If the server responds with an error again, the fetch fails: a URL-specific 2763 // GOAUTH will only be attempted once per fetch. 2764 // 2765 // # The go.mod file 2766 // 2767 // A module version is defined by a tree of source files, with a go.mod 2768 // file in its root. When the go command is run, it looks in the current 2769 // directory and then successive parent directories to find the go.mod 2770 // marking the root of the main (current) module. 2771 // 2772 // The go.mod file format is described in detail at 2773 // https://go.dev/ref/mod#go-mod-file. 2774 // 2775 // To create a new go.mod file, use 'go mod init'. For details see 2776 // 'go help mod init' or https://go.dev/ref/mod#go-mod-init. 2777 // 2778 // To add missing module requirements or remove unneeded requirements, 2779 // use 'go mod tidy'. For details, see 'go help mod tidy' or 2780 // https://go.dev/ref/mod#go-mod-tidy. 2781 // 2782 // To add, upgrade, downgrade, or remove a specific module requirement, use 2783 // 'go get'. For details, see 'go help module-get' or 2784 // https://go.dev/ref/mod#go-get. 2785 // 2786 // To make other changes or to parse go.mod as JSON for use by other tools, 2787 // use 'go mod edit'. See 'go help mod edit' or 2788 // https://go.dev/ref/mod#go-mod-edit. 2789 // 2790 // # GOPATH environment variable 2791 // 2792 // The GOPATH environment variable is used to change the default 2793 // location to store the module cache and installed binaries, if 2794 // not overridden by GOMODCACHE and GOBIN respectively. 2795 // 2796 // Most users don't need to explicitly set GOPATH. 2797 // If the environment variable is unset, GOPATH defaults 2798 // to a subdirectory named "go" in the user's home directory 2799 // ($HOME/go on Unix, %USERPROFILE%\go on Windows), 2800 // unless that directory holds a Go distribution. 2801 // Run "go env GOPATH" to see the current GOPATH. 2802 // 2803 // The module cache is stored in the directory specified by 2804 // GOPATH/pkg/mod. If GOMODCACHE is set, it will be used 2805 // as the directory to store the module cache instead. 2806 // 2807 // Executables installed using 'go install' are placed in the 2808 // directory specified by GOPATH/bin or, if GOBIN is set, by GOBIN. 2809 // 2810 // # GOPATH mode 2811 // 2812 // The GOPATH environment variable is also used by a legacy behavior of the 2813 // toolchain called GOPATH mode that allows some older projects, created before 2814 // modules were introduced in Go 1.11 and never updated to use modules, 2815 // to continue to build. 2816 // 2817 // GOPATH mode is enabled when modules are disabled, either when GO111MODULE=off, 2818 // or when GO111MODULE=auto, and the working directory is not in a module or workspace. 2819 // 2820 // In GOPATH mode, packages are located using the GOPATH environment variable, 2821 // which specifies a list of paths to search: 2822 // On Unix, the value is a colon-separated string. 2823 // On Windows, the value is a semicolon-separated string. 2824 // On Plan 9, the value is a list. 2825 // The first element of this list is used to set the default module cache and 2826 // binary install directory locations as described above. 2827 // 2828 // See https://go.dev/wiki/SettingGOPATH to set a custom GOPATH. 2829 // 2830 // Each directory listed in GOPATH must have a prescribed structure: 2831 // 2832 // The src directory holds source code. The path below src 2833 // determines the import path or executable name. 2834 // 2835 // The pkg directory holds installed package objects. 2836 // As in the Go tree, each target operating system and 2837 // architecture pair has its own subdirectory of pkg 2838 // (pkg/GOOS_GOARCH). 2839 // 2840 // If DIR is a directory listed in the GOPATH, a package with 2841 // source in DIR/src/foo/bar can be imported as "foo/bar" and 2842 // has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a". 2843 // 2844 // The bin directory holds compiled commands. 2845 // Each command is named for its source directory, but only 2846 // the final element, not the entire path. That is, the 2847 // command with source in DIR/src/foo/quux is installed into 2848 // DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped 2849 // so that you can add DIR/bin to your PATH to get at the 2850 // installed commands. If the GOBIN environment variable is 2851 // set, commands are installed to the directory it names instead 2852 // of DIR/bin. GOBIN must be an absolute path. 2853 // 2854 // Here's an example directory layout: 2855 // 2856 // GOPATH=/home/user/go 2857 // 2858 // /home/user/go/ 2859 // src/ 2860 // foo/ 2861 // bar/ (go code in package bar) 2862 // x.go 2863 // quux/ (go code in package main) 2864 // y.go 2865 // bin/ 2866 // quux (installed command) 2867 // pkg/ 2868 // linux_amd64/ 2869 // foo/ 2870 // bar.a (installed package object) 2871 // 2872 // Go searches each directory listed in GOPATH to find source code, 2873 // but new packages are always downloaded into the first directory 2874 // in the list. 2875 // 2876 // See https://go.dev/doc/code.html for an example. 2877 // 2878 // # GOPATH mode vendor directories 2879 // 2880 // In GOPATH mode, code below a directory named "vendor" is importable only 2881 // by code in the directory tree rooted at the parent of "vendor", 2882 // and only using an import path that omits the prefix up to and 2883 // including the vendor element. 2884 // 2885 // Here's the example from the previous section, 2886 // but with the "internal" directory renamed to "vendor" 2887 // and a new foo/vendor/crash/bang directory added: 2888 // 2889 // /home/user/go/ 2890 // src/ 2891 // crash/ 2892 // bang/ (go code in package bang) 2893 // b.go 2894 // foo/ (go code in package foo) 2895 // f.go 2896 // bar/ (go code in package bar) 2897 // x.go 2898 // vendor/ 2899 // crash/ 2900 // bang/ (go code in package bang) 2901 // b.go 2902 // baz/ (go code in package baz) 2903 // z.go 2904 // quux/ (go code in package main) 2905 // y.go 2906 // 2907 // The same visibility rules apply as for internal, but the code 2908 // in z.go is imported as "baz", not as "foo/vendor/baz". 2909 // 2910 // Code in GOPATH mode vendor directories deeper in the source tree shadows 2911 // code in higher directories. Within the subtree rooted at foo, an import 2912 // of "crash/bang" resolves to "foo/vendor/crash/bang", not the 2913 // top-level "crash/bang". 2914 // 2915 // Code in GOPATH mode vendor directories is not subject to 2916 // GOPATH mode import path checking (see 'go help importpath'). 2917 // 2918 // In GOPATH mode, the default GODEBUG values built into a binary 2919 // will be the same GODEBUG values as when a module specifies 2920 // "godebug default=go1.20". To use different GODEBUG settings, the 2921 // GODEBUG environment variable must be set to override those values. 2922 // This also means that the standard library tests will not run 2923 // properly with GO111MODULE=off. 2924 // 2925 // See https://go.dev/s/go15vendor for details. 2926 // 2927 // See https://go.dev/ref/mod#vendoring for details about vendoring in 2928 // module mode. 2929 // 2930 // # Module proxy protocol 2931 // 2932 // A Go module proxy is any web server that can respond to GET requests for 2933 // URLs of a specified form. The requests have no query parameters, so even 2934 // a site serving from a fixed file system (including a file:/// URL) 2935 // can be a module proxy. 2936 // 2937 // For details on the GOPROXY protocol, see 2938 // https://go.dev/ref/mod#goproxy-protocol. 2939 // 2940 // # Import path syntax 2941 // 2942 // An import path is used to uniquely identify and locate a package. 2943 // In general, an import path denotes either a standard library package 2944 // (such as "unicode/utf8") or a package found in a module (for more 2945 // details see: 'go help modules'). 2946 // 2947 // The standard library reserves all import paths without a dot in the 2948 // first element for its packages. See "Fully-qualified import paths" 2949 // below for choosing an import path for your module. 2950 // The following names are reserved to be used as short module names 2951 // when working locally, and in tutorials, examples, and test code. 2952 // 2953 // - "test" 2954 // - "example" 2955 // 2956 // # Internal packages 2957 // 2958 // Code in or below a directory named "internal" is importable only 2959 // by code that shares the same import path above the internal directory. 2960 // Here's an example directory layout of a module example.com/m: 2961 // 2962 // /home/user/modules/m/ 2963 // go.mod (declares module example.com/m) 2964 // crash/ 2965 // bang/ (go code in package bang) 2966 // b.go 2967 // foo/ (go code in package foo) 2968 // f.go 2969 // bar/ (go code in package bar) 2970 // x.go 2971 // internal/ 2972 // baz/ (go code in package baz) 2973 // z.go 2974 // quux/ (go code in package quux) 2975 // y.go 2976 // 2977 // The code in z.go is imported as "example.com/m/foo/internal/baz", but that 2978 // import statement can only appear in packages with the import path prefix 2979 // "example.com/m/foo". The packages "example.com/m/foo", "example.com/m/foo/bar", and 2980 // "example.com/m/foo/quux" can all import "foo/internal/baz", but the package 2981 // "example.com/m/crash/bang" cannot. 2982 // 2983 // See https://go.dev/s/go14internal for details. 2984 // 2985 // # Fully-qualified import paths 2986 // 2987 // A fully-qualified import path for a package not belonging to the standard library 2988 // starts with the path of the module the package to which the package belongs. 2989 // The module's path specifies where to obtain the source code for the module. 2990 // The complete import path is formed by joining the module path with the 2991 // relative directory path of a package within the module. Example: 2992 // 2993 // /home/user/modules/m/ 2994 // go.mod (declares "module example.com/m") 2995 // crash/ 2996 // bang/ (importable as "example.com/m/crash/bang") 2997 // b.go 2998 // foo/ (importable as "example.com/m/foo") 2999 // f.go 3000 // bar/ (importable as "example.com/m/foo/bar") 3001 // x.go 3002 // 3003 // As import paths without a dot in the first element are reserved by the standard library, 3004 // module paths (which form the prefix of all import paths) should start with an element 3005 // containing a dot, e.g. "github.com/user/repo", or "example.com/project". 3006 // A module path may point directly to a code hosting service, 3007 // or to a custom address that points to the code hosting service in a html meta tags. 3008 // Modules may also use the reserved names "example" for documentation 3009 // and "test" for testing. These modules cannot be fetched by the go command. 3010 // 3011 // Import paths belonging to modules hosted on common code hosting sites have special syntax: 3012 // 3013 // Bitbucket (Git, Mercurial) 3014 // 3015 // import "bitbucket.org/user/project" 3016 // import "bitbucket.org/user/project/sub/directory" 3017 // 3018 // GitHub (Git) 3019 // 3020 // import "github.com/user/project" 3021 // import "github.com/user/project/sub/directory" 3022 // 3023 // Launchpad (Bazaar) 3024 // 3025 // import "launchpad.net/project" 3026 // import "launchpad.net/project/series" 3027 // import "launchpad.net/project/series/sub/directory" 3028 // 3029 // import "launchpad.net/~user/project/branch" 3030 // import "launchpad.net/~user/project/branch/sub/directory" 3031 // 3032 // IBM DevOps Services (Git) 3033 // 3034 // import "hub.jazz.net/git/user/project" 3035 // import "hub.jazz.net/git/user/project/sub/directory" 3036 // 3037 // For modules hosted on other servers, import paths may either be qualified 3038 // with the version control type, or the go tool can dynamically fetch 3039 // the import path over https/http and discover where the code resides 3040 // from a <meta> tag in the HTML. 3041 // 3042 // To declare the code location, an import path of the form 3043 // 3044 // repository.vcs/path 3045 // 3046 // specifies the given repository, with or without the .vcs suffix, 3047 // using the named version control system, and then the path inside 3048 // that repository. The supported version control systems are: 3049 // 3050 // Fossil .fossil 3051 // Git .git 3052 // Mercurial .hg 3053 // Subversion .svn 3054 // 3055 // For example, 3056 // 3057 // import "example.org/user/foo.hg" 3058 // 3059 // denotes the root directory of the Mercurial repository at 3060 // example.org/user/foo, and 3061 // 3062 // import "example.org/repo.git/foo/bar" 3063 // 3064 // denotes the foo/bar directory of the Git repository at 3065 // example.org/repo. 3066 // 3067 // When a version control system supports multiple protocols, 3068 // each is tried in turn when downloading. For example, a Git 3069 // download tries https://, then git+ssh://. 3070 // 3071 // By default, downloads are restricted to known secure protocols 3072 // (e.g. https, ssh). To override this setting for Git downloads, the 3073 // GIT_ALLOW_PROTOCOL environment variable can be set (For more details see: 3074 // 'go help environment'). 3075 // 3076 // If the import path is not a known code hosting site and also lacks a 3077 // version control qualifier, the go tool attempts to fetch the import 3078 // over https/http and looks for a <meta> tag in the document's HTML 3079 // <head>. 3080 // 3081 // The meta tag has the form: 3082 // 3083 // <meta name="go-import" content="import-prefix vcs repo-root"> 3084 // 3085 // Starting in Go 1.25, an optional subdirectory will be recognized by the 3086 // go command: 3087 // 3088 // <meta name="go-import" content="import-prefix vcs repo-root subdir"> 3089 // 3090 // The import-prefix is the import path corresponding to the repository 3091 // root. It must be a prefix or an exact match of the package being 3092 // fetched with "go get". If it's not an exact match, another http 3093 // request is made at the prefix to verify the <meta> tags match. 3094 // 3095 // The meta tag should appear as early in the file as possible. 3096 // In particular, it should appear before any raw JavaScript or CSS, 3097 // to avoid confusing the go command's restricted parser. 3098 // 3099 // The vcs is one of "fossil", "git", "hg", "svn". 3100 // 3101 // The repo-root is the root of the version control system 3102 // containing a scheme and not containing a .vcs qualifier. 3103 // 3104 // The subdir specifies the directory within the repo-root where the 3105 // Go module's root (including its go.mod file) is located. It allows 3106 // you to organize your repository with the Go module code in a subdirectory 3107 // rather than directly at the repository's root. 3108 // If set, all vcs tags must be prefixed with "subdir". i.e. "subdir/v1.2.3" 3109 // 3110 // For example, 3111 // 3112 // import "example.org/pkg/foo" 3113 // 3114 // will result in the following requests: 3115 // 3116 // https://example.org/pkg/foo?go-get=1 (preferred) 3117 // http://example.org/pkg/foo?go-get=1 (fallback, only with use of correctly set GOINSECURE) 3118 // 3119 // If that page contains the meta tag 3120 // 3121 // <meta name="go-import" content="example.org git https://code.org/r/p/exproj"> 3122 // 3123 // the go tool will verify that https://example.org/?go-get=1 contains the 3124 // same meta tag and then download the code from the Git repository at https://code.org/r/p/exproj 3125 // 3126 // If that page contains the meta tag 3127 // 3128 // <meta name="go-import" content="example.org git https://code.org/r/p/exproj foo/subdir"> 3129 // 3130 // the go tool will verify that https://example.org/?go-get=1 contains the same meta 3131 // tag and then download the code from the "foo/subdir" subdirectory within the Git repository 3132 // at https://code.org/r/p/exproj 3133 // 3134 // Downloaded modules are stored in the module cache. 3135 // See https://go.dev/ref/mod#module-cache. 3136 // 3137 // An additional variant of the go-import meta tag is 3138 // recognized and is preferred over those listing version control systems. 3139 // That variant uses "mod" as the vcs in the content value, as in: 3140 // 3141 // <meta name="go-import" content="example.org mod https://code.org/moduleproxy"> 3142 // 3143 // This tag means to fetch modules with paths beginning with example.org 3144 // from the module proxy available at the URL https://code.org/moduleproxy. 3145 // See https://go.dev/ref/mod#goproxy-protocol for details about the 3146 // proxy protocol. 3147 // 3148 // # Modules, module versions, and more 3149 // 3150 // Modules are how Go manages dependencies. 3151 // 3152 // A module is a collection of packages that are released, versioned, and 3153 // distributed together. Modules may be downloaded directly from version control 3154 // repositories or from module proxy servers. 3155 // 3156 // For a series of tutorials on modules, see 3157 // https://go.dev/doc/tutorial/create-module. 3158 // 3159 // For a detailed reference on modules, see https://go.dev/ref/mod. 3160 // 3161 // By default, the go command may download modules from https://proxy.golang.org. 3162 // It may authenticate modules using the checksum database at 3163 // https://sum.golang.org. Both services are operated by the Go team at Google. 3164 // The privacy policies for these services are available at 3165 // https://proxy.golang.org/privacy and https://sum.golang.org/privacy, 3166 // respectively. 3167 // 3168 // The go command's download behavior may be configured using GOPROXY, GOSUMDB, 3169 // GOPRIVATE, and other environment variables. See 'go help environment' 3170 // and https://go.dev/ref/mod#private-module-privacy for more information. 3171 // 3172 // # Module authentication using go.sum 3173 // 3174 // When the go command downloads a module zip file or go.mod file into the 3175 // module cache, it computes a cryptographic hash and compares it with a known 3176 // value to verify the file hasn't changed since it was first downloaded. Known 3177 // hashes are stored in a file in the module root directory named go.sum. Hashes 3178 // may also be downloaded from the checksum database depending on the values of 3179 // GOSUMDB, GOPRIVATE, and GONOSUMDB. 3180 // 3181 // For details, see https://go.dev/ref/mod#authenticating. 3182 // 3183 // # Package lists and patterns 3184 // 3185 // Many commands apply to a set of packages: 3186 // 3187 // go <action> [packages] 3188 // 3189 // Usually, [packages] is a list of package patterns, 3190 // which can take several forms: 3191 // 3192 // - A relative or absolute path to a file system directory, 3193 // which can contain "..." wildcard elements. 3194 // - An import path, which can also contain "..." wildcard elements. 3195 // - A reserved name that expands to a set of packages 3196 // - A list of files 3197 // 3198 // If no import paths are given, the action applies to the 3199 // package in the current directory. 3200 // 3201 // "..." elements in filesystem or import paths expand 3202 // to match 0 or more path elements. 3203 // Specific rules are described below. 3204 // 3205 // # File system patterns 3206 // 3207 // Patterns beginning with a file system root like / on Unixes, 3208 // or a volume name like C: on Windows are interpreted as absolute file system paths. 3209 // Patterns beginning with a "." or ".." element are interpreted as relative file system paths. 3210 // File system paths denote the package contained within the given directory. 3211 // 3212 // Relative paths can be used as a shorthand on the command line. 3213 // If you are working in the directory containing the code imported as 3214 // "unicode" and want to run the tests for "unicode/utf8", you can type 3215 // "go test ./utf8" instead of needing to specify the full path. 3216 // Similarly, in the reverse situation, "go test .." will test "unicode" from 3217 // the "unicode/utf8" directory. Relative patterns are also allowed, such as 3218 // "go test ./..." to test all subdirectories. 3219 // 3220 // File system patterns expanded with the "..." wildcard exclude the following: 3221 // 3222 // - Directories named "vendor" 3223 // - Directories named "testdata" 3224 // - Files and directories with names beginning with "_" or "." 3225 // - Directories that contain a go.mod file 3226 // - Directories matching an ignore directive in a module's go.mod file 3227 // 3228 // These can be included by either using them in the prefix, 3229 // or changing into the directories. For example, "./..." won't 3230 // match a "./testdata/foo" package, but "./testdata/..." will. 3231 // 3232 // Directories containing other go modules, 3233 // which are denoted by the presence of a go.mod file, 3234 // can only be matched by changing the working directory into module. 3235 // 3236 // # Import path patterns 3237 // 3238 // Patterns may be import paths as described in "go help importpath". 3239 // Import path patterns natch the packages from modules in the build list. 3240 // The "build list" is the list of module versions used for a build. 3241 // See https://go.dev/ref/mod#glos-build-list for more details. 3242 // 3243 // Some commands accept versioned package patterns, 3244 // such as: "example.com/my/module@v1.2.3" 3245 // These describe the matching package at the given version, 3246 // independent of the versions used by the current module. 3247 // 3248 // Import path patterns may also use a "..." wildcard, 3249 // such as: "example.com/my/module/...". 3250 // This can be combined with the version specifier 3251 // such as: "example.com/my/module/...@latest". 3252 // 3253 // Import path pattern expansion with "..." depends on context: 3254 // 3255 // - "prefix/..." matches all packages in modules in the build list 3256 // that share the prefix, even if they belong to different modules. 3257 // - patterns that include a version specifier such as in "prefix/...@latest" 3258 // only match packages from the module that "prefix" belongs to. 3259 // 3260 // # Reserved names 3261 // 3262 // The following reserved names expand to a set of packages: 3263 // 3264 // - "work" expands to all packages in the main module (or workspace modules). 3265 // 3266 // - "tool" expands to the tools defined in the current module's go.mod file. 3267 // 3268 // - "all" expands to all packages in the main module (or workspace modules) and 3269 // their dependencies, including dependencies needed by tests of any of those. In 3270 // the legacy GOPATH mode, "all" expands to all packages found in all the GOPATH trees. 3271 // 3272 // - "std" expands to all the packages in the standard library 3273 // and their internal libraries. 3274 // 3275 // - "cmd" expands to the Go repository's commands and their 3276 // internal libraries. 3277 // 3278 // # List of .go files 3279 // 3280 // If the pattern is a list of Go files rather than a complete package, 3281 // the go command synthesizes a virtual package named "command-line-arguments" 3282 // containing just the given files. In most cases, it is an error 3283 // to do so (e.g. "go build main.go" or "go build *.go"). 3284 // Instead prefer to operate on complete packages (directories), 3285 // such as: "go build ." 3286 // 3287 // # Package names 3288 // 3289 // Packages are identified by their import path. 3290 // Import paths for packages in the standard library use their 3291 // relative path under "$GOROOT/src". 3292 // Import paths for all other packages are a combination of their module name 3293 // and their relative directory path within the module. 3294 // Within a program, all packages must be identified by a unique import path. 3295 // 3296 // Packages also have names, declared with the "package" keyword 3297 // in a .go file, and used as the identifier when imported 3298 // by another package. By convention, the names of importable packages 3299 // match the last element of their import path, generally the name 3300 // of the directory containing the package. 3301 // 3302 // Package names do not have to be unique within a module, 3303 // but packages that share the same name can't be imported 3304 // together without one of them being aliased to a different name. 3305 // 3306 // As the go command primarily operates on directories, 3307 // all non test .go files within a directory (excluding subdirectories) 3308 // should share the same package declaration. 3309 // Test files may suffix their package declaration with "_test", 3310 // tests in these files are compiled as a separate package 3311 // and don't have access to unexported identifiers of their corresponding 3312 // package. See "go help test" and "go help testflag" for details. 3313 // 3314 // There following package names have special meanings: 3315 // 3316 // - "main" denotes the top-level package in a stand-alone executable. 3317 // "main" packages cannot be imported. 3318 // 3319 // - "documentation" indicates documentation for a non-Go program 3320 // in the directory. Files in package documentation are ignored 3321 // by the go command. 3322 // 3323 // - "_test" suffix in "*_test.go" files. These form a separate test 3324 // package that only has access to the colocated package's exported 3325 // identifiers. See "go doc testing" for details. 3326 // 3327 // For more information about import paths, see "go help importpath". 3328 // 3329 // # Configuration for downloading non-public code 3330 // 3331 // The go command defaults to downloading modules from the public Go module 3332 // mirror at proxy.golang.org. It also defaults to validating downloaded modules, 3333 // regardless of source, against the public Go checksum database at sum.golang.org. 3334 // These defaults work well for publicly available source code. 3335 // 3336 // The GOPRIVATE environment variable controls which modules the go command 3337 // considers to be private (not available publicly) and should therefore not use 3338 // the proxy or checksum database. The variable is a comma-separated list of 3339 // glob patterns (in the syntax of Go's path.Match) of module path prefixes. 3340 // For example, 3341 // 3342 // GOPRIVATE=*.corp.example.com,rsc.io/private 3343 // 3344 // causes the go command to treat as private any module with a path prefix 3345 // matching either pattern, including git.corp.example.com/xyzzy, rsc.io/private, 3346 // and rsc.io/private/quux. 3347 // 3348 // For fine-grained control over module download and validation, the GONOPROXY 3349 // and GONOSUMDB environment variables accept the same kind of glob list 3350 // and override GOPRIVATE for the specific decision of whether to use the proxy 3351 // and checksum database, respectively. 3352 // 3353 // For example, if a company ran a module proxy serving private modules, 3354 // users would configure go using: 3355 // 3356 // GOPRIVATE=*.corp.example.com 3357 // GOPROXY=proxy.example.com 3358 // GONOPROXY=none 3359 // 3360 // The GOPRIVATE variable is also used to define the "public" and "private" 3361 // patterns for the GOVCS variable; see 'go help vcs'. For that usage, 3362 // GOPRIVATE applies even in GOPATH mode. In that case, it matches import paths 3363 // instead of module paths. 3364 // 3365 // The 'go env -w' command (see 'go help env') can be used to set these variables 3366 // for future go command invocations. 3367 // 3368 // For more details, see https://go.dev/ref/mod#private-modules. 3369 // 3370 // # Testing flags 3371 // 3372 // The 'go test' command takes both flags that apply to 'go test' itself 3373 // and flags that apply to the resulting test binary. 3374 // 3375 // Several of the flags control profiling and write an execution profile 3376 // suitable for "go tool pprof"; run "go tool pprof -h" for more 3377 // information. The -sample_index=alloc_space, -sample_index=alloc_objects, 3378 // and -show_bytes options of pprof control how the information is presented. 3379 // 3380 // The following flags are recognized by the 'go test' command and 3381 // control the execution of any test: 3382 // 3383 // -artifacts 3384 // Save test artifacts in the directory specified by -outputdir. 3385 // See 'go doc testing.T.ArtifactDir'. 3386 // 3387 // -bench regexp 3388 // Run only those benchmarks matching a regular expression. 3389 // By default, no benchmarks are run. 3390 // To run all benchmarks, use '-bench .' or '-bench=.'. 3391 // The regular expression is split by unbracketed slash (/) 3392 // characters into a sequence of regular expressions, and each 3393 // part of a benchmark's identifier must match the corresponding 3394 // element in the sequence, if any. Possible parents of matches 3395 // are run with b.N=1 to identify sub-benchmarks. For example, 3396 // given -bench=X/Y, top-level benchmarks matching X are run 3397 // with b.N=1 to find any sub-benchmarks matching Y, which are 3398 // then run in full. 3399 // 3400 // -benchtime t 3401 // Run enough iterations of each benchmark to take t, specified 3402 // as a time.Duration (for example, -benchtime 1h30s). 3403 // The default is 1 second (1s). 3404 // The special syntax Nx means to run the benchmark N times 3405 // (for example, -benchtime 100x). 3406 // 3407 // -count n 3408 // Run each test, benchmark, and fuzz seed n times (default 1). 3409 // If -cpu is set, run n times for each GOMAXPROCS value. 3410 // Examples are always run once. -count does not apply to 3411 // fuzz tests matched by -fuzz. 3412 // 3413 // -cover 3414 // Enable coverage analysis. 3415 // Note that because coverage works by annotating the source 3416 // code before compilation, compilation and test failures with 3417 // coverage enabled may report line numbers that don't correspond 3418 // to the original sources. 3419 // 3420 // -covermode set,count,atomic 3421 // Set the mode for coverage analysis for the package[s] 3422 // being tested. The default is "set" unless -race is enabled, 3423 // in which case it is "atomic". 3424 // The values: 3425 // set: bool: does this statement run? 3426 // count: int: how many times does this statement run? 3427 // atomic: int: count, but correct in multithreaded tests; 3428 // significantly more expensive. 3429 // Sets -cover. 3430 // 3431 // -coverpkg pattern1,pattern2,pattern3 3432 // Apply coverage analysis in each test to packages whose import paths 3433 // match the patterns. The default is for each test to analyze only 3434 // the package being tested. See 'go help packages' for a description 3435 // of package patterns. Sets -cover. 3436 // 3437 // -cpu 1,2,4 3438 // Specify a list of GOMAXPROCS values for which the tests, benchmarks or 3439 // fuzz tests should be executed. The default is the current value 3440 // of GOMAXPROCS. -cpu does not apply to fuzz tests matched by -fuzz. 3441 // 3442 // -failfast 3443 // Do not start new tests after the first test failure. 3444 // 3445 // -fullpath 3446 // Show full file names in the error messages. 3447 // 3448 // -fuzz regexp 3449 // Run the fuzz test matching the regular expression. When specified, 3450 // the command line argument must match exactly one package within the 3451 // main module, and regexp must match exactly one fuzz test within 3452 // that package. Fuzzing will occur after tests, benchmarks, seed corpora 3453 // of other fuzz tests, and examples have completed. See the Fuzzing 3454 // section of the testing package documentation for details. 3455 // 3456 // -fuzztime t 3457 // Run enough iterations of the fuzz target during fuzzing to take t, 3458 // specified as a time.Duration (for example, -fuzztime 1h30s). 3459 // The default is to run forever. 3460 // The special syntax Nx means to run the fuzz target N times 3461 // (for example, -fuzztime 1000x). 3462 // 3463 // -fuzzminimizetime t 3464 // Run enough iterations of the fuzz target during each minimization 3465 // attempt to take t, as specified as a time.Duration (for example, 3466 // -fuzzminimizetime 30s). 3467 // The default is 60s. 3468 // The special syntax Nx means to run the fuzz target N times 3469 // (for example, -fuzzminimizetime 100x). 3470 // 3471 // -json 3472 // Log verbose output and test results in JSON. This presents the 3473 // same information as the -v flag in a machine-readable format. 3474 // 3475 // -list regexp 3476 // List tests, benchmarks, fuzz tests, or examples matching the regular 3477 // expression. No tests, benchmarks, fuzz tests, or examples will be run. 3478 // This will only list top-level tests. No subtest or subbenchmarks will be 3479 // shown. 3480 // 3481 // -outputdir directory 3482 // Place output files from profiling and test artifacts in the 3483 // specified directory, by default the directory in which "go test" is running. 3484 // 3485 // -parallel n 3486 // Allow parallel execution of test functions that call t.Parallel, and 3487 // fuzz targets that call t.Parallel when running the seed corpus. 3488 // The value of this flag is the maximum number of tests to run 3489 // simultaneously. 3490 // While fuzzing, the value of this flag is the maximum number of 3491 // subprocesses that may call the fuzz function simultaneously, regardless of 3492 // whether T.Parallel is called. 3493 // By default, -parallel is set to the value of GOMAXPROCS. 3494 // Setting -parallel to values higher than GOMAXPROCS may cause degraded 3495 // performance due to CPU contention, especially when fuzzing. 3496 // Note that -parallel only applies within a single test binary. 3497 // The 'go test' command may run tests for different packages 3498 // in parallel as well, according to the setting of the -p flag 3499 // (see 'go help build'). 3500 // 3501 // -run regexp 3502 // Run only those tests, examples, and fuzz tests matching the regular 3503 // expression. For tests, the regular expression is split by unbracketed 3504 // slash (/) characters into a sequence of regular expressions, and each 3505 // part of a test's identifier must match the corresponding element in 3506 // the sequence, if any. Note that possible parents of matches are 3507 // run too, so that -run=X/Y matches and runs and reports the result 3508 // of all tests matching X, even those without sub-tests matching Y, 3509 // because it must run them to look for those sub-tests. 3510 // See also -skip. 3511 // 3512 // -short 3513 // Tell long-running tests to shorten their run time. 3514 // It is off by default but set during all.bash so that installing 3515 // the Go tree can run a sanity check but not spend time running 3516 // exhaustive tests. 3517 // 3518 // -shuffle off,on,N 3519 // Randomize the execution order of tests and benchmarks. 3520 // It is off by default. If -shuffle is set to on, then it will seed 3521 // the randomizer using the system clock. If -shuffle is set to an 3522 // integer N, then N will be used as the seed value. In both cases, 3523 // the seed will be reported for reproducibility. 3524 // 3525 // -skip regexp 3526 // Run only those tests, examples, fuzz tests, and benchmarks that 3527 // do not match the regular expression. Like for -run and -bench, 3528 // for tests and benchmarks, the regular expression is split by unbracketed 3529 // slash (/) characters into a sequence of regular expressions, and each 3530 // part of a test's identifier must match the corresponding element in 3531 // the sequence, if any. 3532 // 3533 // -timeout d 3534 // If a test binary runs longer than duration d, panic. 3535 // If d is 0, the timeout is disabled. 3536 // The default is 10 minutes (10m). 3537 // 3538 // -v 3539 // Verbose output: log all tests as they are run. Also print all 3540 // text from Log and Logf calls even if the test succeeds. 3541 // 3542 // -vet list 3543 // Configure the invocation of "go vet" during "go test" 3544 // to use the comma-separated list of vet checks. 3545 // If list is empty, "go test" runs "go vet" with a curated list of 3546 // checks believed to be always worth addressing. 3547 // If list is "off", "go test" does not run "go vet" at all. 3548 // 3549 // The following flags are also recognized by 'go test' and can be used to 3550 // profile the tests during execution: 3551 // 3552 // -benchmem 3553 // Print memory allocation statistics for benchmarks. 3554 // Allocations made in C or using C.malloc are not counted. 3555 // 3556 // -blockprofile block.out 3557 // Write a goroutine blocking profile to the specified file 3558 // when all tests are complete. 3559 // Writes test binary as -c would. 3560 // 3561 // -blockprofilerate n 3562 // Control the detail provided in goroutine blocking profiles by 3563 // calling runtime.SetBlockProfileRate with n. 3564 // See 'go doc runtime.SetBlockProfileRate'. 3565 // The profiler aims to sample, on average, one blocking event every 3566 // n nanoseconds the program spends blocked. By default, 3567 // if -test.blockprofile is set without this flag, all blocking events 3568 // are recorded, equivalent to -test.blockprofilerate=1. 3569 // 3570 // -coverprofile cover.out 3571 // Write a coverage profile to the file after all tests have passed. 3572 // Sets -cover. 3573 // 3574 // -cpuprofile cpu.out 3575 // Write a CPU profile to the specified file before exiting. 3576 // Writes test binary as -c would. 3577 // 3578 // -memprofile mem.out 3579 // Write an allocation profile to the file after all tests have passed. 3580 // Writes test binary as -c would. 3581 // 3582 // -memprofilerate n 3583 // Enable more precise (and expensive) memory allocation profiles by 3584 // setting runtime.MemProfileRate. See 'go doc runtime.MemProfileRate'. 3585 // To profile all memory allocations, use -test.memprofilerate=1. 3586 // 3587 // -mutexprofile mutex.out 3588 // Write a mutex contention profile to the specified file 3589 // when all tests are complete. 3590 // Writes test binary as -c would. 3591 // 3592 // -mutexprofilefraction n 3593 // Sample 1 in n stack traces of goroutines holding a 3594 // contended mutex. 3595 // 3596 // -trace trace.out 3597 // Write an execution trace to the specified file before exiting. 3598 // 3599 // Each of these flags is also recognized with an optional 'test.' prefix, 3600 // as in -test.v. When invoking the generated test binary (the result of 3601 // 'go test -c') directly, however, the prefix is mandatory. 3602 // 3603 // The 'go test' command rewrites or removes recognized flags, 3604 // as appropriate, both before and after the optional package list, 3605 // before invoking the test binary. 3606 // 3607 // For instance, the command 3608 // 3609 // go test -v -myflag testdata -cpuprofile=prof.out -x 3610 // 3611 // will compile the test binary and then run it as 3612 // 3613 // pkg.test -test.v -myflag testdata -test.cpuprofile=prof.out 3614 // 3615 // (The -x flag is removed because it applies only to the go command's 3616 // execution, not to the test itself.) 3617 // 3618 // The test flags that generate profiles (other than for coverage) also 3619 // leave the test binary in pkg.test for use when analyzing the profiles. 3620 // 3621 // When 'go test' runs a test binary, it does so from within the 3622 // corresponding package's source code directory. Depending on the test, 3623 // it may be necessary to do the same when invoking a generated test 3624 // binary directly. Because that directory may be located within the 3625 // module cache, which may be read-only and is verified by checksums, the 3626 // test must not write to it or any other directory within the module 3627 // unless explicitly requested by the user (such as with the -fuzz flag, 3628 // which writes failures to testdata/fuzz). 3629 // 3630 // The command-line package list, if present, must appear before any 3631 // flag not known to the go test command. Continuing the example above, 3632 // the package list would have to appear before -myflag, but could appear 3633 // on either side of -v. 3634 // 3635 // When 'go test' runs in package list mode, 'go test' caches successful 3636 // package test results to avoid unnecessary repeated running of tests. To 3637 // disable test caching, use any test flag or argument other than the 3638 // cacheable flags. The idiomatic way to disable test caching explicitly 3639 // is to use -count=1. 3640 // 3641 // To keep an argument for a test binary from being interpreted as a 3642 // known flag or a package name, use -args (see 'go help test') which 3643 // passes the remainder of the command line through to the test binary 3644 // uninterpreted and unaltered. 3645 // 3646 // For instance, the command 3647 // 3648 // go test -v -args -x -v 3649 // 3650 // will compile the test binary and then run it as 3651 // 3652 // pkg.test -test.v -x -v 3653 // 3654 // Similarly, 3655 // 3656 // go test -args math 3657 // 3658 // will compile the test binary and then run it as 3659 // 3660 // pkg.test math 3661 // 3662 // In the first example, the -x and the second -v are passed through to the 3663 // test binary unchanged and with no effect on the go command itself. 3664 // In the second example, the argument math is passed through to the test 3665 // binary, instead of being interpreted as the package list. 3666 // 3667 // # Testing functions 3668 // 3669 // The 'go test' command expects to find test, benchmark, and example functions 3670 // in the "*_test.go" files corresponding to the package under test. 3671 // 3672 // A test function is one named TestXxx (where Xxx does not start with a 3673 // lower case letter) and should have the signature, 3674 // 3675 // func TestXxx(t *testing.T) { ... } 3676 // 3677 // A benchmark function is one named BenchmarkXxx and should have the signature, 3678 // 3679 // func BenchmarkXxx(b *testing.B) { ... } 3680 // 3681 // A fuzz test is one named FuzzXxx and should have the signature, 3682 // 3683 // func FuzzXxx(f *testing.F) { ... } 3684 // 3685 // An example function is similar to a test function but, instead of using 3686 // *testing.T to report success or failure, prints output to os.Stdout. 3687 // If the last comment in the function starts with "Output:" then the output 3688 // is compared exactly against the comment (see examples below). If the last 3689 // comment begins with "Unordered output:" then the output is compared to the 3690 // comment, however the order of the lines is ignored. An example with no such 3691 // comment is compiled but not executed. An example with no text after 3692 // "Output:" is compiled, executed, and expected to produce no output. 3693 // 3694 // Godoc displays the body of ExampleXxx to demonstrate the use 3695 // of the function, constant, or variable Xxx. An example of a method M with 3696 // receiver type T or *T is named ExampleT_M. There may be multiple examples 3697 // for a given function, constant, or variable, distinguished by a trailing _xxx, 3698 // where xxx is a suffix not beginning with an upper case letter. 3699 // 3700 // Here is an example of an example: 3701 // 3702 // func ExamplePrintln() { 3703 // Println("The output of\nthis example.") 3704 // // Output: The output of 3705 // // this example. 3706 // } 3707 // 3708 // Here is another example where the ordering of the output is ignored: 3709 // 3710 // func ExamplePerm() { 3711 // for _, value := range Perm(4) { 3712 // fmt.Println(value) 3713 // } 3714 // 3715 // // Unordered output: 4 3716 // // 2 3717 // // 1 3718 // // 3 3719 // // 0 3720 // } 3721 // 3722 // The entire test file is presented as the example when it contains a single 3723 // example function, at least one other function, type, variable, or constant 3724 // declaration, and no tests, benchmarks, or fuzz tests. 3725 // 3726 // See the documentation of the testing package for more information. 3727 // 3728 // # Controlling version control with GOVCS 3729 // 3730 // The go command can run version control commands like git 3731 // to download imported code. This functionality is critical to the decentralized 3732 // Go package ecosystem, in which code can be imported from any server, 3733 // but it is also a potential security problem, if a malicious server finds a 3734 // way to cause the invoked version control command to run unintended code. 3735 // 3736 // To balance the functionality and security concerns, the go command 3737 // by default will only use git and hg to download code from public servers. 3738 // But it will use any known version control system (fossil, git, hg, svn) 3739 // to download code from private servers, defined as those hosting packages 3740 // matching the GOPRIVATE variable (see 'go help private'). The rationale behind 3741 // allowing only Git and Mercurial is that these two systems have had the most 3742 // attention to issues of being run as clients of untrusted servers. In contrast, 3743 // Bazaar, Fossil, and Subversion have primarily been used in trusted, 3744 // authenticated environments and are not as well scrutinized as attack surfaces. 3745 // 3746 // The version control command restrictions only apply when using direct version 3747 // control access to download code. When downloading modules from a proxy, 3748 // the go command uses the proxy protocol instead, which is always permitted. 3749 // By default, the go command uses the Go module mirror (proxy.golang.org) 3750 // for public packages and only falls back to version control for private 3751 // packages or when the mirror refuses to serve a public package (typically for 3752 // legal reasons). Therefore, clients can still access public code served from 3753 // Bazaar, Fossil, or Subversion repositories by default, because those downloads 3754 // use the Go module mirror, which takes on the security risk of running the 3755 // version control commands using a custom sandbox. 3756 // 3757 // The GOVCS variable can be used to change the allowed version control systems 3758 // for specific packages (identified by a module or import path). 3759 // The GOVCS variable applies when building package in both module-aware mode 3760 // and GOPATH mode. When using modules, the patterns match against the module path. 3761 // When using GOPATH, the patterns match against the import path corresponding to 3762 // the root of the version control repository. 3763 // 3764 // The general form of the GOVCS setting is a comma-separated list of 3765 // pattern:vcslist rules. The pattern is a glob pattern that must match 3766 // one or more leading elements of the module or import path. The vcslist 3767 // is a pipe-separated list of allowed version control commands, or "all" 3768 // to allow use of any known command, or "off" to disallow all commands. 3769 // Note that if a module matches a pattern with vcslist "off", it may still be 3770 // downloaded if the origin server uses the "mod" scheme, which instructs the 3771 // go command to download the module using the GOPROXY protocol. 3772 // The earliest matching pattern in the list applies, even if later patterns 3773 // might also match. 3774 // 3775 // For example, consider: 3776 // 3777 // GOVCS=github.com:git,evil.com:off,*:git|hg 3778 // 3779 // With this setting, code with a module or import path beginning with 3780 // github.com/ can only use git; paths on evil.com cannot use any version 3781 // control command, and all other paths (* matches everything) can use 3782 // only git or hg. 3783 // 3784 // The special patterns "public" and "private" match public and private 3785 // module or import paths. A path is private if it matches the GOPRIVATE 3786 // variable; otherwise it is public. 3787 // 3788 // If no rules in the GOVCS variable match a particular module or import path, 3789 // the 'go get' command applies its default rule, which can now be summarized 3790 // in GOVCS notation as 'public:git|hg,private:all'. 3791 // 3792 // To allow unfettered use of any version control system for any package, use: 3793 // 3794 // GOVCS=*:all 3795 // 3796 // To disable all use of version control, use: 3797 // 3798 // GOVCS=*:off 3799 // 3800 // The 'go env -w' command (see 'go help env') can be used to set the GOVCS 3801 // variable for future go command invocations. 3802 package main 3803