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