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