github.com/spotify/syslog-redirector-golang@v0.0.0-20140320174030-4859f03d829a/src/cmd/go/doc.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 mkdoc.sh. 6 // Edit the documentation in other files and rerun mkdoc.sh to generate this one. 7 8 /* 9 Go is a tool for managing Go source code. 10 11 Usage: 12 13 go command [arguments] 14 15 The commands are: 16 17 build compile packages and dependencies 18 clean remove object files 19 env print Go environment information 20 fix run go tool fix on packages 21 fmt run gofmt on package sources 22 get download and install packages and dependencies 23 install compile and install packages and dependencies 24 list list packages 25 run compile and run Go program 26 test test packages 27 tool run specified go tool 28 version print Go version 29 vet run go tool vet on packages 30 31 Use "go help [command]" for more information about a command. 32 33 Additional help topics: 34 35 c calling between Go and C 36 gopath GOPATH environment variable 37 importpath import path syntax 38 packages description of package lists 39 testflag description of testing flags 40 testfunc description of testing functions 41 42 Use "go help [topic]" for more information about that topic. 43 44 45 Compile packages and dependencies 46 47 Usage: 48 49 go build [-o output] [build flags] [packages] 50 51 Build compiles the packages named by the import paths, 52 along with their dependencies, but it does not install the results. 53 54 If the arguments are a list of .go files, build treats them as a list 55 of source files specifying a single package. 56 57 When the command line specifies a single main package, 58 build writes the resulting executable to output. 59 Otherwise build compiles the packages but discards the results, 60 serving only as a check that the packages can be built. 61 62 The -o flag specifies the output file name. If not specified, the 63 output file name depends on the arguments and derives from the name 64 of the package, such as p.a for package p, unless p is 'main'. If 65 the package is main and file names are provided, the file name 66 derives from the first file name mentioned, such as f1 for 'go build 67 f1.go f2.go'; with no files provided ('go build'), the output file 68 name is the base name of the containing directory. 69 70 The build flags are shared by the build, install, run, and test commands: 71 72 -a 73 force rebuilding of packages that are already up-to-date. 74 -n 75 print the commands but do not run them. 76 -p n 77 the number of builds that can be run in parallel. 78 The default is the number of CPUs available. 79 -race 80 enable data race detection. 81 Supported only on linux/amd64, darwin/amd64 and windows/amd64. 82 -v 83 print the names of packages as they are compiled. 84 -work 85 print the name of the temporary work directory and 86 do not delete it when exiting. 87 -x 88 print the commands. 89 90 -ccflags 'arg list' 91 arguments to pass on each 5c, 6c, or 8c compiler invocation. 92 -compiler name 93 name of compiler to use, as in runtime.Compiler (gccgo or gc). 94 -gccgoflags 'arg list' 95 arguments to pass on each gccgo compiler/linker invocation. 96 -gcflags 'arg list' 97 arguments to pass on each 5g, 6g, or 8g compiler invocation. 98 -installsuffix suffix 99 a suffix to use in the name of the package installation directory, 100 in order to keep output separate from default builds. 101 If using the -race flag, the install suffix is automatically set to race 102 or, if set explicitly, has _race appended to it. 103 -ldflags 'flag list' 104 arguments to pass on each 5l, 6l, or 8l linker invocation. 105 -tags 'tag list' 106 a list of build tags to consider satisfied during the build. 107 See the documentation for the go/build package for 108 more information about build tags. 109 110 The list flags accept a space-separated list of strings. To embed spaces 111 in an element in the list, surround it with either single or double quotes. 112 113 For more about specifying packages, see 'go help packages'. 114 For more about where packages and binaries are installed, 115 run 'go help gopath'. For more about calling between Go and C/C++, 116 run 'go help c'. 117 118 See also: go install, go get, go clean. 119 120 121 Remove object files 122 123 Usage: 124 125 go clean [-i] [-r] [-n] [-x] [packages] 126 127 Clean removes object files from package source directories. 128 The go command builds most objects in a temporary directory, 129 so go clean is mainly concerned with object files left by other 130 tools or by manual invocations of go build. 131 132 Specifically, clean removes the following files from each of the 133 source directories corresponding to the import paths: 134 135 _obj/ old object directory, left from Makefiles 136 _test/ old test directory, left from Makefiles 137 _testmain.go old gotest file, left from Makefiles 138 test.out old test log, left from Makefiles 139 build.out old test log, left from Makefiles 140 *.[568ao] object files, left from Makefiles 141 142 DIR(.exe) from go build 143 DIR.test(.exe) from go test -c 144 MAINFILE(.exe) from go build MAINFILE.go 145 *.so from SWIG 146 147 In the list, DIR represents the final path element of the 148 directory, and MAINFILE is the base name of any Go source 149 file in the directory that is not included when building 150 the package. 151 152 The -i flag causes clean to remove the corresponding installed 153 archive or binary (what 'go install' would create). 154 155 The -n flag causes clean to print the remove commands it would execute, 156 but not run them. 157 158 The -r flag causes clean to be applied recursively to all the 159 dependencies of the packages named by the import paths. 160 161 The -x flag causes clean to print remove commands as it executes them. 162 163 For more about specifying packages, see 'go help packages'. 164 165 166 Print Go environment information 167 168 Usage: 169 170 go env [var ...] 171 172 Env prints Go environment information. 173 174 By default env prints information as a shell script 175 (on Windows, a batch file). If one or more variable 176 names is given as arguments, env prints the value of 177 each named variable on its own line. 178 179 180 Run go tool fix on packages 181 182 Usage: 183 184 go fix [packages] 185 186 Fix runs the Go fix command on the packages named by the import paths. 187 188 For more about fix, see 'godoc fix'. 189 For more about specifying packages, see 'go help packages'. 190 191 To run fix with specific options, run 'go tool fix'. 192 193 See also: go fmt, go vet. 194 195 196 Run gofmt on package sources 197 198 Usage: 199 200 go fmt [-n] [-x] [packages] 201 202 Fmt runs the command 'gofmt -l -w' on the packages named 203 by the import paths. It prints the names of the files that are modified. 204 205 For more about gofmt, see 'godoc gofmt'. 206 For more about specifying packages, see 'go help packages'. 207 208 The -n flag prints commands that would be executed. 209 The -x flag prints commands as they are executed. 210 211 To run gofmt with specific options, run gofmt itself. 212 213 See also: go fix, go vet. 214 215 216 Download and install packages and dependencies 217 218 Usage: 219 220 go get [-d] [-fix] [-t] [-u] [build flags] [packages] 221 222 Get downloads and installs the packages named by the import paths, 223 along with their dependencies. 224 225 The -d flag instructs get to stop after downloading the packages; that is, 226 it instructs get not to install the packages. 227 228 The -fix flag instructs get to run the fix tool on the downloaded packages 229 before resolving dependencies or building the code. 230 231 The -t flag instructs get to also download the packages required to build 232 the tests for the specified packages. 233 234 The -u flag instructs get to use the network to update the named packages 235 and their dependencies. By default, get uses the network to check out 236 missing packages but does not use it to look for updates to existing packages. 237 238 Get also accepts all the flags in the 'go build' and 'go install' commands, 239 to control the installation. See 'go help build'. 240 241 When checking out or updating a package, get looks for a branch or tag 242 that matches the locally installed version of Go. The most important 243 rule is that if the local installation is running version "go1", get 244 searches for a branch or tag named "go1". If no such version exists it 245 retrieves the most recent version of the package. 246 247 For more about specifying packages, see 'go help packages'. 248 249 For more about how 'go get' finds source code to 250 download, see 'go help importpath'. 251 252 See also: go build, go install, go clean. 253 254 255 Compile and install packages and dependencies 256 257 Usage: 258 259 go install [build flags] [packages] 260 261 Install compiles and installs the packages named by the import paths, 262 along with their dependencies. 263 264 For more about the build flags, see 'go help build'. 265 For more about specifying packages, see 'go help packages'. 266 267 See also: go build, go get, go clean. 268 269 270 List packages 271 272 Usage: 273 274 go list [-e] [-race] [-f format] [-json] [-tags 'tag list'] [packages] 275 276 List lists the packages named by the import paths, one per line. 277 278 The default output shows the package import path: 279 280 code.google.com/p/google-api-go-client/books/v1 281 code.google.com/p/goauth2/oauth 282 code.google.com/p/sqlite 283 284 The -f flag specifies an alternate format for the list, using the 285 syntax of package template. The default output is equivalent to -f 286 '{{.ImportPath}}'. One extra template function is available, "join", 287 which calls strings.Join. The struct being passed to the template is: 288 289 type Package struct { 290 Dir string // directory containing package sources 291 ImportPath string // import path of package in dir 292 Name string // package name 293 Doc string // package documentation string 294 Target string // install path 295 Goroot bool // is this package in the Go root? 296 Standard bool // is this package part of the standard Go library? 297 Stale bool // would 'go install' do anything for this package? 298 Root string // Go root or Go path dir containing this package 299 300 // Source files 301 GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles) 302 CgoFiles []string // .go sources files that import "C" 303 IgnoredGoFiles []string // .go sources ignored due to build constraints 304 CFiles []string // .c source files 305 CXXFiles []string // .cc, .cxx and .cpp source files 306 HFiles []string // .h, .hh, .hpp and .hxx source files 307 SFiles []string // .s source files 308 SwigFiles []string // .swig files 309 SwigCXXFiles []string // .swigcxx files 310 SysoFiles []string // .syso object files to add to archive 311 312 // Cgo directives 313 CgoCFLAGS []string // cgo: flags for C compiler 314 CgoCPPFLAGS []string // cgo: flags for C preprocessor 315 CgoCXXFLAGS []string // cgo: flags for C++ compiler 316 CgoLDFLAGS []string // cgo: flags for linker 317 CgoPkgConfig []string // cgo: pkg-config names 318 319 // Dependency information 320 Imports []string // import paths used by this package 321 Deps []string // all (recursively) imported dependencies 322 323 // Error information 324 Incomplete bool // this package or a dependency has an error 325 Error *PackageError // error loading package 326 DepsErrors []*PackageError // errors loading dependencies 327 328 TestGoFiles []string // _test.go files in package 329 TestImports []string // imports from TestGoFiles 330 XTestGoFiles []string // _test.go files outside package 331 XTestImports []string // imports from XTestGoFiles 332 } 333 334 The -json flag causes the package data to be printed in JSON format 335 instead of using the template format. 336 337 The -e flag changes the handling of erroneous packages, those that 338 cannot be found or are malformed. By default, the list command 339 prints an error to standard error for each erroneous package and 340 omits the packages from consideration during the usual printing. 341 With the -e flag, the list command never prints errors to standard 342 error and instead processes the erroneous packages with the usual 343 printing. Erroneous packages will have a non-empty ImportPath and 344 a non-nil Error field; other information may or may not be missing 345 (zeroed). 346 347 The -tags flag specifies a list of build tags, like in the 'go build' 348 command. 349 350 The -race flag causes the package data to include the dependencies 351 required by the race detector. 352 353 For more about specifying packages, see 'go help packages'. 354 355 356 Compile and run Go program 357 358 Usage: 359 360 go run [build flags] gofiles... [arguments...] 361 362 Run compiles and runs the main package comprising the named Go source files. 363 A Go source file is defined to be a file ending in a literal ".go" suffix. 364 365 For more about build flags, see 'go help build'. 366 367 See also: go build. 368 369 370 Test packages 371 372 Usage: 373 374 go test [-c] [-i] [build and test flags] [packages] [flags for test binary] 375 376 'Go test' automates testing the packages named by the import paths. 377 It prints a summary of the test results in the format: 378 379 ok archive/tar 0.011s 380 FAIL archive/zip 0.022s 381 ok compress/gzip 0.033s 382 ... 383 384 followed by detailed output for each failed package. 385 386 'Go test' recompiles each package along with any files with names matching 387 the file pattern "*_test.go". 388 Files whose names begin with "_" (including "_test.go") or "." are ignored. 389 These additional files can contain test functions, benchmark functions, and 390 example functions. See 'go help testfunc' for more. 391 Each listed package causes the execution of a separate test binary. 392 393 Test files that declare a package with the suffix "_test" will be compiled as a 394 separate package, and then linked and run with the main test binary. 395 396 By default, go test needs no arguments. It compiles and tests the package 397 with source in the current directory, including tests, and runs the tests. 398 399 The package is built in a temporary directory so it does not interfere with the 400 non-test installation. 401 402 In addition to the build flags, the flags handled by 'go test' itself are: 403 404 -c Compile the test binary to pkg.test but do not run it. 405 (Where pkg is the last element of the package's import path.) 406 407 -i 408 Install packages that are dependencies of the test. 409 Do not run the test. 410 411 The test binary also accepts flags that control execution of the test; these 412 flags are also accessible by 'go test'. See 'go help testflag' for details. 413 414 If the test binary needs any other flags, they should be presented after the 415 package names. The go tool treats as a flag the first argument that begins with 416 a minus sign that it does not recognize itself; that argument and all subsequent 417 arguments are passed as arguments to the test binary. 418 419 For more about build flags, see 'go help build'. 420 For more about specifying packages, see 'go help packages'. 421 422 See also: go build, go vet. 423 424 425 Run specified go tool 426 427 Usage: 428 429 go tool [-n] command [args...] 430 431 Tool runs the go tool command identified by the arguments. 432 With no arguments it prints the list of known tools. 433 434 The -n flag causes tool to print the command that would be 435 executed but not execute it. 436 437 For more about each tool command, see 'go tool command -h'. 438 439 440 Print Go version 441 442 Usage: 443 444 go version 445 446 Version prints the Go version, as reported by runtime.Version. 447 448 449 Run go tool vet on packages 450 451 Usage: 452 453 go vet [-n] [-x] [packages] 454 455 Vet runs the Go vet command on the packages named by the import paths. 456 457 For more about vet, see 'godoc code.google.com/p/go.tools/cmd/vet'. 458 For more about specifying packages, see 'go help packages'. 459 460 To run the vet tool with specific options, run 'go tool vet'. 461 462 The -n flag prints commands that would be executed. 463 The -x flag prints commands as they are executed. 464 465 See also: go fmt, go fix. 466 467 468 Calling between Go and C 469 470 There are two different ways to call between Go and C/C++ code. 471 472 The first is the cgo tool, which is part of the Go distribution. For 473 information on how to use it see the cgo documentation (godoc cmd/cgo). 474 475 The second is the SWIG program, which is a general tool for 476 interfacing between languages. For information on SWIG see 477 http://swig.org/. When running go build, any file with a .swig 478 extension will be passed to SWIG. Any file with a .swigcxx extension 479 will be passed to SWIG with the -c++ option. 480 481 When either cgo or SWIG is used, go build will pass any .c, .s, or .S 482 files to the C compiler, and any .cc, .cpp, .cxx files to the C++ 483 compiler. The CC or CXX environment variables may be set to determine 484 the C or C++ compiler, respectively, to use. 485 486 487 GOPATH environment variable 488 489 The Go path is used to resolve import statements. 490 It is implemented by and documented in the go/build package. 491 492 The GOPATH environment variable lists places to look for Go code. 493 On Unix, the value is a colon-separated string. 494 On Windows, the value is a semicolon-separated string. 495 On Plan 9, the value is a list. 496 497 GOPATH must be set to get, build and install packages outside the 498 standard Go tree. 499 500 Each directory listed in GOPATH must have a prescribed structure: 501 502 The src/ directory holds source code. The path below 'src' 503 determines the import path or executable name. 504 505 The pkg/ directory holds installed package objects. 506 As in the Go tree, each target operating system and 507 architecture pair has its own subdirectory of pkg 508 (pkg/GOOS_GOARCH). 509 510 If DIR is a directory listed in the GOPATH, a package with 511 source in DIR/src/foo/bar can be imported as "foo/bar" and 512 has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a". 513 514 The bin/ directory holds compiled commands. 515 Each command is named for its source directory, but only 516 the final element, not the entire path. That is, the 517 command with source in DIR/src/foo/quux is installed into 518 DIR/bin/quux, not DIR/bin/foo/quux. The foo/ is stripped 519 so that you can add DIR/bin to your PATH to get at the 520 installed commands. If the GOBIN environment variable is 521 set, commands are installed to the directory it names instead 522 of DIR/bin. 523 524 Here's an example directory layout: 525 526 GOPATH=/home/user/gocode 527 528 /home/user/gocode/ 529 src/ 530 foo/ 531 bar/ (go code in package bar) 532 x.go 533 quux/ (go code in package main) 534 y.go 535 bin/ 536 quux (installed command) 537 pkg/ 538 linux_amd64/ 539 foo/ 540 bar.a (installed package object) 541 542 Go searches each directory listed in GOPATH to find source code, 543 but new packages are always downloaded into the first directory 544 in the list. 545 546 547 Import path syntax 548 549 An import path (see 'go help packages') denotes a package 550 stored in the local file system. In general, an import path denotes 551 either a standard package (such as "unicode/utf8") or a package 552 found in one of the work spaces (see 'go help gopath'). 553 554 Relative import paths 555 556 An import path beginning with ./ or ../ is called a relative path. 557 The toolchain supports relative import paths as a shortcut in two ways. 558 559 First, a relative path can be used as a shorthand on the command line. 560 If you are working in the directory containing the code imported as 561 "unicode" and want to run the tests for "unicode/utf8", you can type 562 "go test ./utf8" instead of needing to specify the full path. 563 Similarly, in the reverse situation, "go test .." will test "unicode" from 564 the "unicode/utf8" directory. Relative patterns are also allowed, like 565 "go test ./..." to test all subdirectories. See 'go help packages' for details 566 on the pattern syntax. 567 568 Second, if you are compiling a Go program not in a work space, 569 you can use a relative path in an import statement in that program 570 to refer to nearby code also not in a work space. 571 This makes it easy to experiment with small multipackage programs 572 outside of the usual work spaces, but such programs cannot be 573 installed with "go install" (there is no work space in which to install them), 574 so they are rebuilt from scratch each time they are built. 575 To avoid ambiguity, Go programs cannot use relative import paths 576 within a work space. 577 578 Remote import paths 579 580 Certain import paths also 581 describe how to obtain the source code for the package using 582 a revision control system. 583 584 A few common code hosting sites have special syntax: 585 586 Bitbucket (Git, Mercurial) 587 588 import "bitbucket.org/user/project" 589 import "bitbucket.org/user/project/sub/directory" 590 591 GitHub (Git) 592 593 import "github.com/user/project" 594 import "github.com/user/project/sub/directory" 595 596 Google Code Project Hosting (Git, Mercurial, Subversion) 597 598 import "code.google.com/p/project" 599 import "code.google.com/p/project/sub/directory" 600 601 import "code.google.com/p/project.subrepository" 602 import "code.google.com/p/project.subrepository/sub/directory" 603 604 Launchpad (Bazaar) 605 606 import "launchpad.net/project" 607 import "launchpad.net/project/series" 608 import "launchpad.net/project/series/sub/directory" 609 610 import "launchpad.net/~user/project/branch" 611 import "launchpad.net/~user/project/branch/sub/directory" 612 613 For code hosted on other servers, import paths may either be qualified 614 with the version control type, or the go tool can dynamically fetch 615 the import path over https/http and discover where the code resides 616 from a <meta> tag in the HTML. 617 618 To declare the code location, an import path of the form 619 620 repository.vcs/path 621 622 specifies the given repository, with or without the .vcs suffix, 623 using the named version control system, and then the path inside 624 that repository. The supported version control systems are: 625 626 Bazaar .bzr 627 Git .git 628 Mercurial .hg 629 Subversion .svn 630 631 For example, 632 633 import "example.org/user/foo.hg" 634 635 denotes the root directory of the Mercurial repository at 636 example.org/user/foo or foo.hg, and 637 638 import "example.org/repo.git/foo/bar" 639 640 denotes the foo/bar directory of the Git repository at 641 example.com/repo or repo.git. 642 643 When a version control system supports multiple protocols, 644 each is tried in turn when downloading. For example, a Git 645 download tries git://, then https://, then http://. 646 647 If the import path is not a known code hosting site and also lacks a 648 version control qualifier, the go tool attempts to fetch the import 649 over https/http and looks for a <meta> tag in the document's HTML 650 <head>. 651 652 The meta tag has the form: 653 654 <meta name="go-import" content="import-prefix vcs repo-root"> 655 656 The import-prefix is the import path corresponding to the repository 657 root. It must be a prefix or an exact match of the package being 658 fetched with "go get". If it's not an exact match, another http 659 request is made at the prefix to verify the <meta> tags match. 660 661 The vcs is one of "git", "hg", "svn", etc, 662 663 The repo-root is the root of the version control system 664 containing a scheme and not containing a .vcs qualifier. 665 666 For example, 667 668 import "example.org/pkg/foo" 669 670 will result in the following request(s): 671 672 https://example.org/pkg/foo?go-get=1 (preferred) 673 http://example.org/pkg/foo?go-get=1 (fallback) 674 675 If that page contains the meta tag 676 677 <meta name="go-import" content="example.org git https://code.org/r/p/exproj"> 678 679 the go tool will verify that https://example.org/?go-get=1 contains the 680 same meta tag and then git clone https://code.org/r/p/exproj into 681 GOPATH/src/example.org. 682 683 New downloaded packages are written to the first directory 684 listed in the GOPATH environment variable (see 'go help gopath'). 685 686 The go command attempts to download the version of the 687 package appropriate for the Go release being used. 688 Run 'go help install' for more. 689 690 691 Description of package lists 692 693 Many commands apply to a set of packages: 694 695 go action [packages] 696 697 Usually, [packages] is a list of import paths. 698 699 An import path that is a rooted path or that begins with 700 a . or .. element is interpreted as a file system path and 701 denotes the package in that directory. 702 703 Otherwise, the import path P denotes the package found in 704 the directory DIR/src/P for some DIR listed in the GOPATH 705 environment variable (see 'go help gopath'). 706 707 If no import paths are given, the action applies to the 708 package in the current directory. 709 710 There are three reserved names for paths that should not be used 711 for packages to be built with the go tool: 712 713 - "main" denotes the top-level package in a stand-alone executable. 714 715 - "all" expands to all package directories found in all the GOPATH 716 trees. For example, 'go list all' lists all the packages on the local 717 system. 718 719 - "std" is like all but expands to just the packages in the standard 720 Go library. 721 722 An import path is a pattern if it includes one or more "..." wildcards, 723 each of which can match any string, including the empty string and 724 strings containing slashes. Such a pattern expands to all package 725 directories found in the GOPATH trees with names matching the 726 patterns. As a special case, x/... matches x as well as x's subdirectories. 727 For example, net/... expands to net and packages in its subdirectories. 728 729 An import path can also name a package to be downloaded from 730 a remote repository. Run 'go help importpath' for details. 731 732 Every package in a program must have a unique import path. 733 By convention, this is arranged by starting each path with a 734 unique prefix that belongs to you. For example, paths used 735 internally at Google all begin with 'google', and paths 736 denoting remote repositories begin with the path to the code, 737 such as 'code.google.com/p/project'. 738 739 As a special case, if the package list is a list of .go files from a 740 single directory, the command is applied to a single synthesized 741 package made up of exactly those files, ignoring any build constraints 742 in those files and ignoring any other files in the directory. 743 744 File names that begin with "." or "_" are ignored by the go tool. 745 746 747 Description of testing flags 748 749 The 'go test' command takes both flags that apply to 'go test' itself 750 and flags that apply to the resulting test binary. 751 752 Several of the flags control profiling and write an execution profile 753 suitable for "go tool pprof"; run "go tool pprof help" for more 754 information. The --alloc_space, --alloc_objects, and --show_bytes 755 options of pprof control how the information is presented. 756 757 The following flags are recognized by the 'go test' command and 758 control the execution of any test: 759 760 -bench regexp 761 Run benchmarks matching the regular expression. 762 By default, no benchmarks run. To run all benchmarks, 763 use '-bench .' or '-bench=.'. 764 765 -benchmem 766 Print memory allocation statistics for benchmarks. 767 768 -benchtime t 769 Run enough iterations of each benchmark to take t, specified 770 as a time.Duration (for example, -benchtime 1h30s). 771 The default is 1 second (1s). 772 773 -blockprofile block.out 774 Write a goroutine blocking profile to the specified file 775 when all tests are complete. 776 777 -blockprofilerate n 778 Control the detail provided in goroutine blocking profiles by 779 calling runtime.SetBlockProfileRate with n. 780 See 'godoc runtime SetBlockProfileRate'. 781 The profiler aims to sample, on average, one blocking event every 782 n nanoseconds the program spends blocked. By default, 783 if -test.blockprofile is set without this flag, all blocking events 784 are recorded, equivalent to -test.blockprofilerate=1. 785 786 -cover 787 Enable coverage analysis. 788 789 -covermode set,count,atomic 790 Set the mode for coverage analysis for the package[s] 791 being tested. The default is "set". 792 The values: 793 set: bool: does this statement run? 794 count: int: how many times does this statement run? 795 atomic: int: count, but correct in multithreaded tests; 796 significantly more expensive. 797 Sets -cover. 798 799 -coverpkg pkg1,pkg2,pkg3 800 Apply coverage analysis in each test to the given list of packages. 801 The default is for each test to analyze only the package being tested. 802 Packages are specified as import paths. 803 Sets -cover. 804 805 -coverprofile cover.out 806 Write a coverage profile to the specified file after all tests 807 have passed. 808 Sets -cover. 809 810 -cpu 1,2,4 811 Specify a list of GOMAXPROCS values for which the tests or 812 benchmarks should be executed. The default is the current value 813 of GOMAXPROCS. 814 815 -cpuprofile cpu.out 816 Write a CPU profile to the specified file before exiting. 817 818 -memprofile mem.out 819 Write a memory profile to the specified file after all tests 820 have passed. 821 822 -memprofilerate n 823 Enable more precise (and expensive) memory profiles by setting 824 runtime.MemProfileRate. See 'godoc runtime MemProfileRate'. 825 To profile all memory allocations, use -test.memprofilerate=1 826 and set the environment variable GOGC=off to disable the 827 garbage collector, provided the test can run in the available 828 memory without garbage collection. 829 830 -outputdir directory 831 Place output files from profiling in the specified directory, 832 by default the directory in which "go test" is running. 833 834 -parallel n 835 Allow parallel execution of test functions that call t.Parallel. 836 The value of this flag is the maximum number of tests to run 837 simultaneously; by default, it is set to the value of GOMAXPROCS. 838 839 -run regexp 840 Run only those tests and examples matching the regular 841 expression. 842 843 -short 844 Tell long-running tests to shorten their run time. 845 It is off by default but set during all.bash so that installing 846 the Go tree can run a sanity check but not spend time running 847 exhaustive tests. 848 849 -timeout t 850 If a test runs longer than t, panic. 851 852 -v 853 Verbose output: log all tests as they are run. Also print all 854 text from Log and Logf calls even if the test succeeds. 855 856 The test binary, called pkg.test where pkg is the name of the 857 directory containing the package sources, can be invoked directly 858 after building it with 'go test -c'. When invoking the test binary 859 directly, each of the standard flag names must be prefixed with 'test.', 860 as in -test.run=TestMyFunc or -test.v. 861 862 When running 'go test', flags not listed above are passed through 863 unaltered. For instance, the command 864 865 go test -x -v -cpuprofile=prof.out -dir=testdata -update 866 867 will compile the test binary and then run it as 868 869 pkg.test -test.v -test.cpuprofile=prof.out -dir=testdata -update 870 871 The test flags that generate profiles (other than for coverage) also 872 leave the test binary in pkg.test for use when analyzing the profiles. 873 874 Flags not recognized by 'go test' must be placed after any specified packages. 875 876 877 Description of testing functions 878 879 The 'go test' command expects to find test, benchmark, and example functions 880 in the "*_test.go" files corresponding to the package under test. 881 882 A test function is one named TestXXX (where XXX is any alphanumeric string 883 not starting with a lower case letter) and should have the signature, 884 885 func TestXXX(t *testing.T) { ... } 886 887 A benchmark function is one named BenchmarkXXX and should have the signature, 888 889 func BenchmarkXXX(b *testing.B) { ... } 890 891 An example function is similar to a test function but, instead of using 892 *testing.T to report success or failure, prints output to os.Stdout. 893 That output is compared against the function's "Output:" comment, which 894 must be the last comment in the function body (see example below). An 895 example with no such comment, or with no text after "Output:" is compiled 896 but not executed. 897 898 Godoc displays the body of ExampleXXX to demonstrate the use 899 of the function, constant, or variable XXX. An example of a method M with 900 receiver type T or *T is named ExampleT_M. There may be multiple examples 901 for a given function, constant, or variable, distinguished by a trailing _xxx, 902 where xxx is a suffix not beginning with an upper case letter. 903 904 Here is an example of an example: 905 906 func ExamplePrintln() { 907 Println("The output of\nthis example.") 908 // Output: The output of 909 // this example. 910 } 911 912 The entire test file is presented as the example when it contains a single 913 example function, at least one other function, type, variable, or constant 914 declaration, and no test or benchmark functions. 915 916 See the documentation of the testing package for more information. 917 918 919 */ 920 package main