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