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