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