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