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