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