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