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