github.com/lianghucheng/zrddz@v0.0.0-20200923083010-c71f680932e2/src/golang.org/x/net/http2/h2demo/tmpl.go (about) 1 // Copyright 2017 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 // +build h2demo 6 7 package main 8 9 import "html/template" 10 11 var pushTmpl = template.Must(template.New("serverpush").Parse(` 12 13 <!DOCTYPE html> 14 <html> 15 <head> 16 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 17 <meta name="viewport" content="width=device-width, initial-scale=1"> 18 <meta name="theme-color" content="#375EAB"> 19 20 <title>HTTP/2 Server Push Demo</title> 21 22 <link type="text/css" rel="stylesheet" href="/serverpush/static/style.css?{{.CacheBust}}"> 23 <script> 24 window.initFuncs = []; 25 </script> 26 27 <script> 28 function showtimes() { 29 var times = 'DOM loaded: ' + (window.performance.timing.domContentLoadedEventEnd - window.performance.timing.navigationStart) + 'ms, ' 30 times += 'DOM complete (all loaded): ' + (window.performance.timing.domComplete - window.performance.timing.navigationStart) + 'ms, ' 31 times += 'Load event fired: ' + (window.performance.timing.loadEventStart - window.performance.timing.navigationStart) + 'ms' 32 document.getElementById('loadtimes').innerHTML = times 33 } 34 </script> 35 36 </head> 37 <body onload="showtimes()"> 38 39 <div style="background:#fff9a4;padding:10px"> 40 Note: This page exists for demonstration purposes. For the actual cmd/go docs, go to <a href="golang.org/cmd/go">golang.org/cmd/go</a>. 41 </div> 42 43 <div style="padding:20px"> 44 45 46 <a href="https://{{.HTTPSHost}}/serverpush">HTTP/2 with Server Push</a> | <a href="{{.HTTP1Prefix}}/serverpush">HTTP only</a> 47 <div id="loadtimes"></div> 48 49 </div> 50 51 <div id='lowframe' style="position: fixed; bottom: 0; left: 0; height: 0; width: 100%; border-top: thin solid grey; background-color: white; overflow: auto;"> 52 ... 53 </div><!-- #lowframe --> 54 55 <div id="topbar" class="wide"><div class="container"> 56 <div class="top-heading" id="heading-wide"><a href="/">The Go Programming Language</a></div> 57 <div class="top-heading" id="heading-narrow"><a href="/">Go</a></div> 58 <a href="#" id="menu-button"><span id="menu-button-arrow">▽</span></a> 59 <form method="GET" action="/search"> 60 <div id="menu"> 61 <a href="/doc/">Documents</a> 62 <a href="/pkg/">Packages</a> 63 <a href="/project/">The Project</a> 64 <a href="/help/">Help</a> 65 <a href="/blog/">Blog</a> 66 67 <a id="playgroundButton" href="http://play.golang.org/" title="Show Go Playground">Play</a> 68 69 <input type="text" id="search" name="q" class="inactive" value="Search" placeholder="Search"> 70 </div> 71 </form> 72 73 </div></div> 74 75 76 <div id="playground" class="play"> 77 <div class="input"><textarea class="code" spellcheck="false">package main 78 79 import "fmt" 80 81 func main() { 82 fmt.Println("Hello, 世界") 83 }</textarea></div> 84 <div class="output"></div> 85 <div class="buttons"> 86 <a class="run" title="Run this code [shift-enter]">Run</a> 87 <a class="fmt" title="Format this code">Format</a> 88 89 <a class="share" title="Share this code">Share</a> 90 91 </div> 92 </div> 93 94 95 <div id="page" class="wide"> 96 <div class="container"> 97 98 99 <h1>Command go</h1> 100 101 102 103 104 <div id="nav"></div> 105 106 107 <!-- 108 Copyright 2009 The Go Authors. All rights reserved. 109 Use of this source code is governed by a BSD-style 110 license that can be found in the LICENSE file. 111 --> 112 <!-- 113 Note: Static (i.e., not template-generated) href and id 114 attributes start with "pkg-" to make it impossible for 115 them to conflict with generated attributes (some of which 116 correspond to Go identifiers). 117 --> 118 119 <script type='text/javascript'> 120 document.ANALYSIS_DATA = null; 121 document.CALLGRAPH = null; 122 </script> 123 124 125 126 <p> 127 Go is a tool for managing Go source code. 128 </p> 129 <p> 130 Usage: 131 </p> 132 <pre>go command [arguments] 133 </pre> 134 <p> 135 The commands are: 136 </p> 137 <pre>build compile packages and dependencies 138 clean remove object files 139 doc show documentation for package or symbol 140 env print Go environment information 141 bug start a bug report 142 fix run go tool fix on packages 143 fmt run gofmt on package sources 144 generate generate Go files by processing source 145 get download and install packages and dependencies 146 install compile and install packages and dependencies 147 list list packages 148 run compile and run Go program 149 test test packages 150 tool run specified go tool 151 version print Go version 152 vet run go tool vet on packages 153 </pre> 154 <p> 155 Use "go help [command]" for more information about a command. 156 </p> 157 <p> 158 Additional help topics: 159 </p> 160 <pre>c calling between Go and C 161 buildmode description of build modes 162 filetype file types 163 gopath GOPATH environment variable 164 environment environment variables 165 importpath import path syntax 166 packages description of package lists 167 testflag description of testing flags 168 testfunc description of testing functions 169 </pre> 170 <p> 171 Use "go help [topic]" for more information about that topic. 172 </p> 173 <h3 id="hdr-Compile_packages_and_dependencies">Compile packages and dependencies</h3> 174 <p> 175 Usage: 176 </p> 177 <pre>go build [-o output] [-i] [build flags] [packages] 178 </pre> 179 <p> 180 Build compiles the packages named by the import paths, 181 along with their dependencies, but it does not install the results. 182 </p> 183 <p> 184 If the arguments to build are a list of .go files, build treats 185 them as a list of source files specifying a single package. 186 </p> 187 <p> 188 When compiling a single main package, build writes 189 the resulting executable to an output file named after 190 the first source file ('go build ed.go rx.go' writes 'ed' or 'ed.exe') 191 or the source code directory ('go build unix/sam' writes 'sam' or 'sam.exe'). 192 The '.exe' suffix is added when writing a Windows executable. 193 </p> 194 <p> 195 When compiling multiple packages or a single non-main package, 196 build compiles the packages but discards the resulting object, 197 serving only as a check that the packages can be built. 198 </p> 199 <p> 200 When compiling packages, build ignores files that end in '_test.go'. 201 </p> 202 <p> 203 The -o flag, only allowed when compiling a single package, 204 forces build to write the resulting executable or object 205 to the named output file, instead of the default behavior described 206 in the last two paragraphs. 207 </p> 208 <p> 209 The -i flag installs the packages that are dependencies of the target. 210 </p> 211 <p> 212 The build flags are shared by the build, clean, get, install, list, run, 213 and test commands: 214 </p> 215 <pre>-a 216 force rebuilding of packages that are already up-to-date. 217 -n 218 print the commands but do not run them. 219 -p n 220 the number of programs, such as build commands or 221 test binaries, that can be run in parallel. 222 The default is the number of CPUs available. 223 -race 224 enable data race detection. 225 Supported only on linux/amd64, freebsd/amd64, darwin/amd64 and windows/amd64. 226 -msan 227 enable interoperation with memory sanitizer. 228 Supported only on linux/amd64, 229 and only with Clang/LLVM as the host C compiler. 230 -v 231 print the names of packages as they are compiled. 232 -work 233 print the name of the temporary work directory and 234 do not delete it when exiting. 235 -x 236 print the commands. 237 238 -asmflags 'flag list' 239 arguments to pass on each go tool asm invocation. 240 -buildmode mode 241 build mode to use. See 'go help buildmode' for more. 242 -compiler name 243 name of compiler to use, as in runtime.Compiler (gccgo or gc). 244 -gccgoflags 'arg list' 245 arguments to pass on each gccgo compiler/linker invocation. 246 -gcflags 'arg list' 247 arguments to pass on each go tool compile invocation. 248 -installsuffix suffix 249 a suffix to use in the name of the package installation directory, 250 in order to keep output separate from default builds. 251 If using the -race flag, the install suffix is automatically set to race 252 or, if set explicitly, has _race appended to it. Likewise for the -msan 253 flag. Using a -buildmode option that requires non-default compile flags 254 has a similar effect. 255 -ldflags 'flag list' 256 arguments to pass on each go tool link invocation. 257 -linkshared 258 link against shared libraries previously created with 259 -buildmode=shared. 260 -pkgdir dir 261 install and load all packages from dir instead of the usual locations. 262 For example, when building with a non-standard configuration, 263 use -pkgdir to keep generated packages in a separate location. 264 -tags 'tag list' 265 a list of build tags to consider satisfied during the build. 266 For more information about build tags, see the description of 267 build constraints in the documentation for the go/build package. 268 -toolexec 'cmd args' 269 a program to use to invoke toolchain programs like vet and asm. 270 For example, instead of running asm, the go command will run 271 'cmd args /path/to/asm <arguments for asm>'. 272 </pre> 273 <p> 274 The list flags accept a space-separated list of strings. To embed spaces 275 in an element in the list, surround it with either single or double quotes. 276 </p> 277 <p> 278 For more about specifying packages, see 'go help packages'. 279 For more about where packages and binaries are installed, 280 run 'go help gopath'. 281 For more about calling between Go and C/C++, run 'go help c'. 282 </p> 283 <p> 284 Note: Build adheres to certain conventions such as those described 285 by 'go help gopath'. Not all projects can follow these conventions, 286 however. Installations that have their own conventions or that use 287 a separate software build system may choose to use lower-level 288 invocations such as 'go tool compile' and 'go tool link' to avoid 289 some of the overheads and design decisions of the build tool. 290 </p> 291 <p> 292 See also: go install, go get, go clean. 293 </p> 294 <h3 id="hdr-Remove_object_files">Remove object files</h3> 295 <p> 296 Usage: 297 </p> 298 <pre>go clean [-i] [-r] [-n] [-x] [build flags] [packages] 299 </pre> 300 <p> 301 Clean removes object files from package source directories. 302 The go command builds most objects in a temporary directory, 303 so go clean is mainly concerned with object files left by other 304 tools or by manual invocations of go build. 305 </p> 306 <p> 307 Specifically, clean removes the following files from each of the 308 source directories corresponding to the import paths: 309 </p> 310 <pre>_obj/ old object directory, left from Makefiles 311 _test/ old test directory, left from Makefiles 312 _testmain.go old gotest file, left from Makefiles 313 test.out old test log, left from Makefiles 314 build.out old test log, left from Makefiles 315 *.[568ao] object files, left from Makefiles 316 317 DIR(.exe) from go build 318 DIR.test(.exe) from go test -c 319 MAINFILE(.exe) from go build MAINFILE.go 320 *.so from SWIG 321 </pre> 322 <p> 323 In the list, DIR represents the final path element of the 324 directory, and MAINFILE is the base name of any Go source 325 file in the directory that is not included when building 326 the package. 327 </p> 328 <p> 329 The -i flag causes clean to remove the corresponding installed 330 archive or binary (what 'go install' would create). 331 </p> 332 <p> 333 The -n flag causes clean to print the remove commands it would execute, 334 but not run them. 335 </p> 336 <p> 337 The -r flag causes clean to be applied recursively to all the 338 dependencies of the packages named by the import paths. 339 </p> 340 <p> 341 The -x flag causes clean to print remove commands as it executes them. 342 </p> 343 <p> 344 For more about build flags, see 'go help build'. 345 </p> 346 <p> 347 For more about specifying packages, see 'go help packages'. 348 </p> 349 <h3 id="hdr-Show_documentation_for_package_or_symbol">Show documentation for package or symbol</h3> 350 <p> 351 Usage: 352 </p> 353 <pre>go doc [-u] [-c] [package|[package.]symbol[.method]] 354 </pre> 355 <p> 356 Doc prints the documentation comments associated with the item identified by its 357 arguments (a package, const, func, type, var, or method) followed by a one-line 358 summary of each of the first-level items "under" that item (package-level 359 declarations for a package, methods for a type, etc.). 360 </p> 361 <p> 362 Doc accepts zero, one, or two arguments. 363 </p> 364 <p> 365 Given no arguments, that is, when run as 366 </p> 367 <pre>go doc 368 </pre> 369 <p> 370 it prints the package documentation for the package in the current directory. 371 If the package is a command (package main), the exported symbols of the package 372 are elided from the presentation unless the -cmd flag is provided. 373 </p> 374 <p> 375 When run with one argument, the argument is treated as a Go-syntax-like 376 representation of the item to be documented. What the argument selects depends 377 on what is installed in GOROOT and GOPATH, as well as the form of the argument, 378 which is schematically one of these: 379 </p> 380 <pre>go doc <pkg> 381 go doc <sym>[.<method>] 382 go doc [<pkg>.]<sym>[.<method>] 383 go doc [<pkg>.][<sym>.]<method> 384 </pre> 385 <p> 386 The first item in this list matched by the argument is the one whose documentation 387 is printed. (See the examples below.) However, if the argument starts with a capital 388 letter it is assumed to identify a symbol or method in the current directory. 389 </p> 390 <p> 391 For packages, the order of scanning is determined lexically in breadth-first order. 392 That is, the package presented is the one that matches the search and is nearest 393 the root and lexically first at its level of the hierarchy. The GOROOT tree is 394 always scanned in its entirety before GOPATH. 395 </p> 396 <p> 397 If there is no package specified or matched, the package in the current 398 directory is selected, so "go doc Foo" shows the documentation for symbol Foo in 399 the current package. 400 </p> 401 <p> 402 The package path must be either a qualified path or a proper suffix of a 403 path. The go tool's usual package mechanism does not apply: package path 404 elements like . and ... are not implemented by go doc. 405 </p> 406 <p> 407 When run with two arguments, the first must be a full package path (not just a 408 suffix), and the second is a symbol or symbol and method; this is similar to the 409 syntax accepted by godoc: 410 </p> 411 <pre>go doc <pkg> <sym>[.<method>] 412 </pre> 413 <p> 414 In all forms, when matching symbols, lower-case letters in the argument match 415 either case but upper-case letters match exactly. This means that there may be 416 multiple matches of a lower-case argument in a package if different symbols have 417 different cases. If this occurs, documentation for all matches is printed. 418 </p> 419 <p> 420 Examples: 421 </p> 422 <pre>go doc 423 Show documentation for current package. 424 go doc Foo 425 Show documentation for Foo in the current package. 426 (Foo starts with a capital letter so it cannot match 427 a package path.) 428 go doc encoding/json 429 Show documentation for the encoding/json package. 430 go doc json 431 Shorthand for encoding/json. 432 go doc json.Number (or go doc json.number) 433 Show documentation and method summary for json.Number. 434 go doc json.Number.Int64 (or go doc json.number.int64) 435 Show documentation for json.Number's Int64 method. 436 go doc cmd/doc 437 Show package docs for the doc command. 438 go doc -cmd cmd/doc 439 Show package docs and exported symbols within the doc command. 440 go doc template.new 441 Show documentation for html/template's New function. 442 (html/template is lexically before text/template) 443 go doc text/template.new # One argument 444 Show documentation for text/template's New function. 445 go doc text/template new # Two arguments 446 Show documentation for text/template's New function. 447 448 At least in the current tree, these invocations all print the 449 documentation for json.Decoder's Decode method: 450 451 go doc json.Decoder.Decode 452 go doc json.decoder.decode 453 go doc json.decode 454 cd go/src/encoding/json; go doc decode 455 </pre> 456 <p> 457 Flags: 458 </p> 459 <pre>-c 460 Respect case when matching symbols. 461 -cmd 462 Treat a command (package main) like a regular package. 463 Otherwise package main's exported symbols are hidden 464 when showing the package's top-level documentation. 465 -u 466 Show documentation for unexported as well as exported 467 symbols and methods. 468 </pre> 469 <h3 id="hdr-Print_Go_environment_information">Print Go environment information</h3> 470 <p> 471 Usage: 472 </p> 473 <pre>go env [var ...] 474 </pre> 475 <p> 476 Env prints Go environment information. 477 </p> 478 <p> 479 By default env prints information as a shell script 480 (on Windows, a batch file). If one or more variable 481 names is given as arguments, env prints the value of 482 each named variable on its own line. 483 </p> 484 <h3 id="hdr-Start_a_bug_report">Start a bug report</h3> 485 <p> 486 Usage: 487 </p> 488 <pre>go bug 489 </pre> 490 <p> 491 Bug opens the default browser and starts a new bug report. 492 The report includes useful system information. 493 </p> 494 <h3 id="hdr-Run_go_tool_fix_on_packages">Run go tool fix on packages</h3> 495 <p> 496 Usage: 497 </p> 498 <pre>go fix [packages] 499 </pre> 500 <p> 501 Fix runs the Go fix command on the packages named by the import paths. 502 </p> 503 <p> 504 For more about fix, see 'go doc cmd/fix'. 505 For more about specifying packages, see 'go help packages'. 506 </p> 507 <p> 508 To run fix with specific options, run 'go tool fix'. 509 </p> 510 <p> 511 See also: go fmt, go vet. 512 </p> 513 <h3 id="hdr-Run_gofmt_on_package_sources">Run gofmt on package sources</h3> 514 <p> 515 Usage: 516 </p> 517 <pre>go fmt [-n] [-x] [packages] 518 </pre> 519 <p> 520 Fmt runs the command 'gofmt -l -w' on the packages named 521 by the import paths. It prints the names of the files that are modified. 522 </p> 523 <p> 524 For more about gofmt, see 'go doc cmd/gofmt'. 525 For more about specifying packages, see 'go help packages'. 526 </p> 527 <p> 528 The -n flag prints commands that would be executed. 529 The -x flag prints commands as they are executed. 530 </p> 531 <p> 532 To run gofmt with specific options, run gofmt itself. 533 </p> 534 <p> 535 See also: go fix, go vet. 536 </p> 537 <h3 id="hdr-Generate_Go_files_by_processing_source">Generate Go files by processing source</h3> 538 <p> 539 Usage: 540 </p> 541 <pre>go generate [-run regexp] [-n] [-v] [-x] [build flags] [file.go... | packages] 542 </pre> 543 <p> 544 Generate runs commands described by directives within existing 545 files. Those commands can run any process but the intent is to 546 create or update Go source files. 547 </p> 548 <p> 549 Go generate is never run automatically by go build, go get, go test, 550 and so on. It must be run explicitly. 551 </p> 552 <p> 553 Go generate scans the file for directives, which are lines of 554 the form, 555 </p> 556 <pre>//go:generate command argument... 557 </pre> 558 <p> 559 (note: no leading spaces and no space in "//go") where command 560 is the generator to be run, corresponding to an executable file 561 that can be run locally. It must either be in the shell path 562 (gofmt), a fully qualified path (/usr/you/bin/mytool), or a 563 command alias, described below. 564 </p> 565 <p> 566 Note that go generate does not parse the file, so lines that look 567 like directives in comments or multiline strings will be treated 568 as directives. 569 </p> 570 <p> 571 The arguments to the directive are space-separated tokens or 572 double-quoted strings passed to the generator as individual 573 arguments when it is run. 574 </p> 575 <p> 576 Quoted strings use Go syntax and are evaluated before execution; a 577 quoted string appears as a single argument to the generator. 578 </p> 579 <p> 580 Go generate sets several variables when it runs the generator: 581 </p> 582 <pre>$GOARCH 583 The execution architecture (arm, amd64, etc.) 584 $GOOS 585 The execution operating system (linux, windows, etc.) 586 $GOFILE 587 The base name of the file. 588 $GOLINE 589 The line number of the directive in the source file. 590 $GOPACKAGE 591 The name of the package of the file containing the directive. 592 $DOLLAR 593 A dollar sign. 594 </pre> 595 <p> 596 Other than variable substitution and quoted-string evaluation, no 597 special processing such as "globbing" is performed on the command 598 line. 599 </p> 600 <p> 601 As a last step before running the command, any invocations of any 602 environment variables with alphanumeric names, such as $GOFILE or 603 $HOME, are expanded throughout the command line. The syntax for 604 variable expansion is $NAME on all operating systems. Due to the 605 order of evaluation, variables are expanded even inside quoted 606 strings. If the variable NAME is not set, $NAME expands to the 607 empty string. 608 </p> 609 <p> 610 A directive of the form, 611 </p> 612 <pre>//go:generate -command xxx args... 613 </pre> 614 <p> 615 specifies, for the remainder of this source file only, that the 616 string xxx represents the command identified by the arguments. This 617 can be used to create aliases or to handle multiword generators. 618 For example, 619 </p> 620 <pre>//go:generate -command foo go tool foo 621 </pre> 622 <p> 623 specifies that the command "foo" represents the generator 624 "go tool foo". 625 </p> 626 <p> 627 Generate processes packages in the order given on the command line, 628 one at a time. If the command line lists .go files, they are treated 629 as a single package. Within a package, generate processes the 630 source files in a package in file name order, one at a time. Within 631 a source file, generate runs generators in the order they appear 632 in the file, one at a time. 633 </p> 634 <p> 635 If any generator returns an error exit status, "go generate" skips 636 all further processing for that package. 637 </p> 638 <p> 639 The generator is run in the package's source directory. 640 </p> 641 <p> 642 Go generate accepts one specific flag: 643 </p> 644 <pre>-run="" 645 if non-empty, specifies a regular expression to select 646 directives whose full original source text (excluding 647 any trailing spaces and final newline) matches the 648 expression. 649 </pre> 650 <p> 651 It also accepts the standard build flags including -v, -n, and -x. 652 The -v flag prints the names of packages and files as they are 653 processed. 654 The -n flag prints commands that would be executed. 655 The -x flag prints commands as they are executed. 656 </p> 657 <p> 658 For more about build flags, see 'go help build'. 659 </p> 660 <p> 661 For more about specifying packages, see 'go help packages'. 662 </p> 663 <h3 id="hdr-Download_and_install_packages_and_dependencies">Download and install packages and dependencies</h3> 664 <p> 665 Usage: 666 </p> 667 <pre>go get [-d] [-f] [-fix] [-insecure] [-t] [-u] [build flags] [packages] 668 </pre> 669 <p> 670 Get downloads the packages named by the import paths, along with their 671 dependencies. It then installs the named packages, like 'go install'. 672 </p> 673 <p> 674 The -d flag instructs get to stop after downloading the packages; that is, 675 it instructs get not to install the packages. 676 </p> 677 <p> 678 The -f flag, valid only when -u is set, forces get -u not to verify that 679 each package has been checked out from the source control repository 680 implied by its import path. This can be useful if the source is a local fork 681 of the original. 682 </p> 683 <p> 684 The -fix flag instructs get to run the fix tool on the downloaded packages 685 before resolving dependencies or building the code. 686 </p> 687 <p> 688 The -insecure flag permits fetching from repositories and resolving 689 custom domains using insecure schemes such as HTTP. Use with caution. 690 </p> 691 <p> 692 The -t flag instructs get to also download the packages required to build 693 the tests for the specified packages. 694 </p> 695 <p> 696 The -u flag instructs get to use the network to update the named packages 697 and their dependencies. By default, get uses the network to check out 698 missing packages but does not use it to look for updates to existing packages. 699 </p> 700 <p> 701 The -v flag enables verbose progress and debug output. 702 </p> 703 <p> 704 Get also accepts build flags to control the installation. See 'go help build'. 705 </p> 706 <p> 707 When checking out a new package, get creates the target directory 708 GOPATH/src/<import-path>. If the GOPATH contains multiple entries, 709 get uses the first one. For more details see: 'go help gopath'. 710 </p> 711 <p> 712 When checking out or updating a package, get looks for a branch or tag 713 that matches the locally installed version of Go. The most important 714 rule is that if the local installation is running version "go1", get 715 searches for a branch or tag named "go1". If no such version exists it 716 retrieves the most recent version of the package. 717 </p> 718 <p> 719 When go get checks out or updates a Git repository, 720 it also updates any git submodules referenced by the repository. 721 </p> 722 <p> 723 Get never checks out or updates code stored in vendor directories. 724 </p> 725 <p> 726 For more about specifying packages, see 'go help packages'. 727 </p> 728 <p> 729 For more about how 'go get' finds source code to 730 download, see 'go help importpath'. 731 </p> 732 <p> 733 See also: go build, go install, go clean. 734 </p> 735 <h3 id="hdr-Compile_and_install_packages_and_dependencies">Compile and install packages and dependencies</h3> 736 <p> 737 Usage: 738 </p> 739 <pre>go install [build flags] [packages] 740 </pre> 741 <p> 742 Install compiles and installs the packages named by the import paths, 743 along with their dependencies. 744 </p> 745 <p> 746 For more about the build flags, see 'go help build'. 747 For more about specifying packages, see 'go help packages'. 748 </p> 749 <p> 750 See also: go build, go get, go clean. 751 </p> 752 <h3 id="hdr-List_packages">List packages</h3> 753 <p> 754 Usage: 755 </p> 756 <pre>go list [-e] [-f format] [-json] [build flags] [packages] 757 </pre> 758 <p> 759 List lists the packages named by the import paths, one per line. 760 </p> 761 <p> 762 The default output shows the package import path: 763 </p> 764 <pre>bytes 765 encoding/json 766 github.com/gorilla/mux 767 golang.org/x/net/html 768 </pre> 769 <p> 770 The -f flag specifies an alternate format for the list, using the 771 syntax of package template. The default output is equivalent to -f 772 ''. The struct being passed to the template is: 773 </p> 774 <pre>type Package struct { 775 Dir string // directory containing package sources 776 ImportPath string // import path of package in dir 777 ImportComment string // path in import comment on package statement 778 Name string // package name 779 Doc string // package documentation string 780 Target string // install path 781 Shlib string // the shared library that contains this package (only set when -linkshared) 782 Goroot bool // is this package in the Go root? 783 Standard bool // is this package part of the standard Go library? 784 Stale bool // would 'go install' do anything for this package? 785 StaleReason string // explanation for Stale==true 786 Root string // Go root or Go path dir containing this package 787 ConflictDir string // this directory shadows Dir in $GOPATH 788 BinaryOnly bool // binary-only package: cannot be recompiled from sources 789 790 // Source files 791 GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles) 792 CgoFiles []string // .go sources files that import "C" 793 IgnoredGoFiles []string // .go sources ignored due to build constraints 794 CFiles []string // .c source files 795 CXXFiles []string // .cc, .cxx and .cpp source files 796 MFiles []string // .m source files 797 HFiles []string // .h, .hh, .hpp and .hxx source files 798 FFiles []string // .f, .F, .for and .f90 Fortran source files 799 SFiles []string // .s source files 800 SwigFiles []string // .swig files 801 SwigCXXFiles []string // .swigcxx files 802 SysoFiles []string // .syso object files to add to archive 803 TestGoFiles []string // _test.go files in package 804 XTestGoFiles []string // _test.go files outside package 805 806 // Cgo directives 807 CgoCFLAGS []string // cgo: flags for C compiler 808 CgoCPPFLAGS []string // cgo: flags for C preprocessor 809 CgoCXXFLAGS []string // cgo: flags for C++ compiler 810 CgoFFLAGS []string // cgo: flags for Fortran compiler 811 CgoLDFLAGS []string // cgo: flags for linker 812 CgoPkgConfig []string // cgo: pkg-config names 813 814 // Dependency information 815 Imports []string // import paths used by this package 816 Deps []string // all (recursively) imported dependencies 817 TestImports []string // imports from TestGoFiles 818 XTestImports []string // imports from XTestGoFiles 819 820 // Error information 821 Incomplete bool // this package or a dependency has an error 822 Error *PackageError // error loading package 823 DepsErrors []*PackageError // errors loading dependencies 824 } 825 </pre> 826 <p> 827 Packages stored in vendor directories report an ImportPath that includes the 828 path to the vendor directory (for example, "d/vendor/p" instead of "p"), 829 so that the ImportPath uniquely identifies a given copy of a package. 830 The Imports, Deps, TestImports, and XTestImports lists also contain these 831 expanded imports paths. See golang.org/s/go15vendor for more about vendoring. 832 </p> 833 <p> 834 The error information, if any, is 835 </p> 836 <pre>type PackageError struct { 837 ImportStack []string // shortest path from package named on command line to this one 838 Pos string // position of error (if present, file:line:col) 839 Err string // the error itself 840 } 841 </pre> 842 <p> 843 The template function "join" calls strings.Join. 844 </p> 845 <p> 846 The template function "context" returns the build context, defined as: 847 </p> 848 <pre>type Context struct { 849 GOARCH string // target architecture 850 GOOS string // target operating system 851 GOROOT string // Go root 852 GOPATH string // Go path 853 CgoEnabled bool // whether cgo can be used 854 UseAllFiles bool // use files regardless of +build lines, file names 855 Compiler string // compiler to assume when computing target paths 856 BuildTags []string // build constraints to match in +build lines 857 ReleaseTags []string // releases the current release is compatible with 858 InstallSuffix string // suffix to use in the name of the install dir 859 } 860 </pre> 861 <p> 862 For more information about the meaning of these fields see the documentation 863 for the go/build package's Context type. 864 </p> 865 <p> 866 The -json flag causes the package data to be printed in JSON format 867 instead of using the template format. 868 </p> 869 <p> 870 The -e flag changes the handling of erroneous packages, those that 871 cannot be found or are malformed. By default, the list command 872 prints an error to standard error for each erroneous package and 873 omits the packages from consideration during the usual printing. 874 With the -e flag, the list command never prints errors to standard 875 error and instead processes the erroneous packages with the usual 876 printing. Erroneous packages will have a non-empty ImportPath and 877 a non-nil Error field; other information may or may not be missing 878 (zeroed). 879 </p> 880 <p> 881 For more about build flags, see 'go help build'. 882 </p> 883 <p> 884 For more about specifying packages, see 'go help packages'. 885 </p> 886 <h3 id="hdr-Compile_and_run_Go_program">Compile and run Go program</h3> 887 <p> 888 Usage: 889 </p> 890 <pre>go run [build flags] [-exec xprog] gofiles... [arguments...] 891 </pre> 892 <p> 893 Run compiles and runs the main package comprising the named Go source files. 894 A Go source file is defined to be a file ending in a literal ".go" suffix. 895 </p> 896 <p> 897 By default, 'go run' runs the compiled binary directly: 'a.out arguments...'. 898 If the -exec flag is given, 'go run' invokes the binary using xprog: 899 </p> 900 <pre>'xprog a.out arguments...'. 901 </pre> 902 <p> 903 If the -exec flag is not given, GOOS or GOARCH is different from the system 904 default, and a program named go_$GOOS_$GOARCH_exec can be found 905 on the current search path, 'go run' invokes the binary using that program, 906 for example 'go_nacl_386_exec a.out arguments...'. This allows execution of 907 cross-compiled programs when a simulator or other execution method is 908 available. 909 </p> 910 <p> 911 For more about build flags, see 'go help build'. 912 </p> 913 <p> 914 See also: go build. 915 </p> 916 <h3 id="hdr-Test_packages">Test packages</h3> 917 <p> 918 Usage: 919 </p> 920 <pre>go test [build/test flags] [packages] [build/test flags & test binary flags] 921 </pre> 922 <p> 923 'Go test' automates testing the packages named by the import paths. 924 It prints a summary of the test results in the format: 925 </p> 926 <pre>ok archive/tar 0.011s 927 FAIL archive/zip 0.022s 928 ok compress/gzip 0.033s 929 ... 930 </pre> 931 <p> 932 followed by detailed output for each failed package. 933 </p> 934 <p> 935 'Go test' recompiles each package along with any files with names matching 936 the file pattern "*_test.go". 937 Files whose names begin with "_" (including "_test.go") or "." are ignored. 938 These additional files can contain test functions, benchmark functions, and 939 example functions. See 'go help testfunc' for more. 940 Each listed package causes the execution of a separate test binary. 941 </p> 942 <p> 943 Test files that declare a package with the suffix "_test" will be compiled as a 944 separate package, and then linked and run with the main test binary. 945 </p> 946 <p> 947 The go tool will ignore a directory named "testdata", making it available 948 to hold ancillary data needed by the tests. 949 </p> 950 <p> 951 By default, go test needs no arguments. It compiles and tests the package 952 with source in the current directory, including tests, and runs the tests. 953 </p> 954 <p> 955 The package is built in a temporary directory so it does not interfere with the 956 non-test installation. 957 </p> 958 <p> 959 In addition to the build flags, the flags handled by 'go test' itself are: 960 </p> 961 <pre>-args 962 Pass the remainder of the command line (everything after -args) 963 to the test binary, uninterpreted and unchanged. 964 Because this flag consumes the remainder of the command line, 965 the package list (if present) must appear before this flag. 966 967 -c 968 Compile the test binary to pkg.test but do not run it 969 (where pkg is the last element of the package's import path). 970 The file name can be changed with the -o flag. 971 972 -exec xprog 973 Run the test binary using xprog. The behavior is the same as 974 in 'go run'. See 'go help run' for details. 975 976 -i 977 Install packages that are dependencies of the test. 978 Do not run the test. 979 980 -o file 981 Compile the test binary to the named file. 982 The test still runs (unless -c or -i is specified). 983 </pre> 984 <p> 985 The test binary also accepts flags that control execution of the test; these 986 flags are also accessible by 'go test'. See 'go help testflag' for details. 987 </p> 988 <p> 989 For more about build flags, see 'go help build'. 990 For more about specifying packages, see 'go help packages'. 991 </p> 992 <p> 993 See also: go build, go vet. 994 </p> 995 <h3 id="hdr-Run_specified_go_tool">Run specified go tool</h3> 996 <p> 997 Usage: 998 </p> 999 <pre>go tool [-n] command [args...] 1000 </pre> 1001 <p> 1002 Tool runs the go tool command identified by the arguments. 1003 With no arguments it prints the list of known tools. 1004 </p> 1005 <p> 1006 The -n flag causes tool to print the command that would be 1007 executed but not execute it. 1008 </p> 1009 <p> 1010 For more about each tool command, see 'go tool command -h'. 1011 </p> 1012 <h3 id="hdr-Print_Go_version">Print Go version</h3> 1013 <p> 1014 Usage: 1015 </p> 1016 <pre>go version 1017 </pre> 1018 <p> 1019 Version prints the Go version, as reported by runtime.Version. 1020 </p> 1021 <h3 id="hdr-Run_go_tool_vet_on_packages">Run go tool vet on packages</h3> 1022 <p> 1023 Usage: 1024 </p> 1025 <pre>go vet [-n] [-x] [build flags] [packages] 1026 </pre> 1027 <p> 1028 Vet runs the Go vet command on the packages named by the import paths. 1029 </p> 1030 <p> 1031 For more about vet, see 'go doc cmd/vet'. 1032 For more about specifying packages, see 'go help packages'. 1033 </p> 1034 <p> 1035 To run the vet tool with specific options, run 'go tool vet'. 1036 </p> 1037 <p> 1038 The -n flag prints commands that would be executed. 1039 The -x flag prints commands as they are executed. 1040 </p> 1041 <p> 1042 For more about build flags, see 'go help build'. 1043 </p> 1044 <p> 1045 See also: go fmt, go fix. 1046 </p> 1047 <h3 id="hdr-Calling_between_Go_and_C">Calling between Go and C</h3> 1048 <p> 1049 There are two different ways to call between Go and C/C++ code. 1050 </p> 1051 <p> 1052 The first is the cgo tool, which is part of the Go distribution. For 1053 information on how to use it see the cgo documentation (go doc cmd/cgo). 1054 </p> 1055 <p> 1056 The second is the SWIG program, which is a general tool for 1057 interfacing between languages. For information on SWIG see 1058 <a href="http://swig.org/">http://swig.org/</a>. When running go build, any file with a .swig 1059 extension will be passed to SWIG. Any file with a .swigcxx extension 1060 will be passed to SWIG with the -c++ option. 1061 </p> 1062 <p> 1063 When either cgo or SWIG is used, go build will pass any .c, .m, .s, 1064 or .S files to the C compiler, and any .cc, .cpp, .cxx files to the C++ 1065 compiler. The CC or CXX environment variables may be set to determine 1066 the C or C++ compiler, respectively, to use. 1067 </p> 1068 <h3 id="hdr-Description_of_build_modes">Description of build modes</h3> 1069 <p> 1070 The 'go build' and 'go install' commands take a -buildmode argument which 1071 indicates which kind of object file is to be built. Currently supported values 1072 are: 1073 </p> 1074 <pre>-buildmode=archive 1075 Build the listed non-main packages into .a files. Packages named 1076 main are ignored. 1077 1078 -buildmode=c-archive 1079 Build the listed main package, plus all packages it imports, 1080 into a C archive file. The only callable symbols will be those 1081 functions exported using a cgo //export comment. Requires 1082 exactly one main package to be listed. 1083 1084 -buildmode=c-shared 1085 Build the listed main packages, plus all packages that they 1086 import, into C shared libraries. The only callable symbols will 1087 be those functions exported using a cgo //export comment. 1088 Non-main packages are ignored. 1089 1090 -buildmode=default 1091 Listed main packages are built into executables and listed 1092 non-main packages are built into .a files (the default 1093 behavior). 1094 1095 -buildmode=shared 1096 Combine all the listed non-main packages into a single shared 1097 library that will be used when building with the -linkshared 1098 option. Packages named main are ignored. 1099 1100 -buildmode=exe 1101 Build the listed main packages and everything they import into 1102 executables. Packages not named main are ignored. 1103 1104 -buildmode=pie 1105 Build the listed main packages and everything they import into 1106 position independent executables (PIE). Packages not named 1107 main are ignored. 1108 1109 -buildmode=plugin 1110 Build the listed main packages, plus all packages that they 1111 import, into a Go plugin. Packages not named main are ignored. 1112 </pre> 1113 <h3 id="hdr-File_types">File types</h3> 1114 <p> 1115 The go command examines the contents of a restricted set of files 1116 in each directory. It identifies which files to examine based on 1117 the extension of the file name. These extensions are: 1118 </p> 1119 <pre>.go 1120 Go source files. 1121 .c, .h 1122 C source files. 1123 If the package uses cgo or SWIG, these will be compiled with the 1124 OS-native compiler (typically gcc); otherwise they will 1125 trigger an error. 1126 .cc, .cpp, .cxx, .hh, .hpp, .hxx 1127 C++ source files. Only useful with cgo or SWIG, and always 1128 compiled with the OS-native compiler. 1129 .m 1130 Objective-C source files. Only useful with cgo, and always 1131 compiled with the OS-native compiler. 1132 .s, .S 1133 Assembler source files. 1134 If the package uses cgo or SWIG, these will be assembled with the 1135 OS-native assembler (typically gcc (sic)); otherwise they 1136 will be assembled with the Go assembler. 1137 .swig, .swigcxx 1138 SWIG definition files. 1139 .syso 1140 System object files. 1141 </pre> 1142 <p> 1143 Files of each of these types except .syso may contain build 1144 constraints, but the go command stops scanning for build constraints 1145 at the first item in the file that is not a blank line or //-style 1146 line comment. See the go/build package documentation for 1147 more details. 1148 </p> 1149 <p> 1150 Non-test Go source files can also include a //go:binary-only-package 1151 comment, indicating that the package sources are included 1152 for documentation only and must not be used to build the 1153 package binary. This enables distribution of Go packages in 1154 their compiled form alone. See the go/build package documentation 1155 for more details. 1156 </p> 1157 <h3 id="hdr-GOPATH_environment_variable">GOPATH environment variable</h3> 1158 <p> 1159 The Go path is used to resolve import statements. 1160 It is implemented by and documented in the go/build package. 1161 </p> 1162 <p> 1163 The GOPATH environment variable lists places to look for Go code. 1164 On Unix, the value is a colon-separated string. 1165 On Windows, the value is a semicolon-separated string. 1166 On Plan 9, the value is a list. 1167 </p> 1168 <p> 1169 If the environment variable is unset, GOPATH defaults 1170 to a subdirectory named "go" in the user's home directory 1171 ($HOME/go on Unix, %USERPROFILE%\go on Windows), 1172 unless that directory holds a Go distribution. 1173 Run "go env GOPATH" to see the current GOPATH. 1174 </p> 1175 <p> 1176 See <a href="https://golang.org/wiki/SettingGOPATH">https://golang.org/wiki/SettingGOPATH</a> to set a custom GOPATH. 1177 </p> 1178 <p> 1179 Each directory listed in GOPATH must have a prescribed structure: 1180 </p> 1181 <p> 1182 The src directory holds source code. The path below src 1183 determines the import path or executable name. 1184 </p> 1185 <p> 1186 The pkg directory holds installed package objects. 1187 As in the Go tree, each target operating system and 1188 architecture pair has its own subdirectory of pkg 1189 (pkg/GOOS_GOARCH). 1190 </p> 1191 <p> 1192 If DIR is a directory listed in the GOPATH, a package with 1193 source in DIR/src/foo/bar can be imported as "foo/bar" and 1194 has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a". 1195 </p> 1196 <p> 1197 The bin directory holds compiled commands. 1198 Each command is named for its source directory, but only 1199 the final element, not the entire path. That is, the 1200 command with source in DIR/src/foo/quux is installed into 1201 DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped 1202 so that you can add DIR/bin to your PATH to get at the 1203 installed commands. If the GOBIN environment variable is 1204 set, commands are installed to the directory it names instead 1205 of DIR/bin. GOBIN must be an absolute path. 1206 </p> 1207 <p> 1208 Here's an example directory layout: 1209 </p> 1210 <pre>GOPATH=/home/user/go 1211 1212 /home/user/go/ 1213 src/ 1214 foo/ 1215 bar/ (go code in package bar) 1216 x.go 1217 quux/ (go code in package main) 1218 y.go 1219 bin/ 1220 quux (installed command) 1221 pkg/ 1222 linux_amd64/ 1223 foo/ 1224 bar.a (installed package object) 1225 </pre> 1226 <p> 1227 Go searches each directory listed in GOPATH to find source code, 1228 but new packages are always downloaded into the first directory 1229 in the list. 1230 </p> 1231 <p> 1232 See <a href="https://golang.org/doc/code.html">https://golang.org/doc/code.html</a> for an example. 1233 </p> 1234 <h3 id="hdr-Internal_Directories">Internal Directories</h3> 1235 <p> 1236 Code in or below a directory named "internal" is importable only 1237 by code in the directory tree rooted at the parent of "internal". 1238 Here's an extended version of the directory layout above: 1239 </p> 1240 <pre>/home/user/go/ 1241 src/ 1242 crash/ 1243 bang/ (go code in package bang) 1244 b.go 1245 foo/ (go code in package foo) 1246 f.go 1247 bar/ (go code in package bar) 1248 x.go 1249 internal/ 1250 baz/ (go code in package baz) 1251 z.go 1252 quux/ (go code in package main) 1253 y.go 1254 </pre> 1255 <p> 1256 The code in z.go is imported as "foo/internal/baz", but that 1257 import statement can only appear in source files in the subtree 1258 rooted at foo. The source files foo/f.go, foo/bar/x.go, and 1259 foo/quux/y.go can all import "foo/internal/baz", but the source file 1260 crash/bang/b.go cannot. 1261 </p> 1262 <p> 1263 See <a href="https://golang.org/s/go14internal">https://golang.org/s/go14internal</a> for details. 1264 </p> 1265 <h3 id="hdr-Vendor_Directories">Vendor Directories</h3> 1266 <p> 1267 Go 1.6 includes support for using local copies of external dependencies 1268 to satisfy imports of those dependencies, often referred to as vendoring. 1269 </p> 1270 <p> 1271 Code below a directory named "vendor" is importable only 1272 by code in the directory tree rooted at the parent of "vendor", 1273 and only using an import path that omits the prefix up to and 1274 including the vendor element. 1275 </p> 1276 <p> 1277 Here's the example from the previous section, 1278 but with the "internal" directory renamed to "vendor" 1279 and a new foo/vendor/crash/bang directory added: 1280 </p> 1281 <pre>/home/user/go/ 1282 src/ 1283 crash/ 1284 bang/ (go code in package bang) 1285 b.go 1286 foo/ (go code in package foo) 1287 f.go 1288 bar/ (go code in package bar) 1289 x.go 1290 vendor/ 1291 crash/ 1292 bang/ (go code in package bang) 1293 b.go 1294 baz/ (go code in package baz) 1295 z.go 1296 quux/ (go code in package main) 1297 y.go 1298 </pre> 1299 <p> 1300 The same visibility rules apply as for internal, but the code 1301 in z.go is imported as "baz", not as "foo/vendor/baz". 1302 </p> 1303 <p> 1304 Code in vendor directories deeper in the source tree shadows 1305 code in higher directories. Within the subtree rooted at foo, an import 1306 of "crash/bang" resolves to "foo/vendor/crash/bang", not the 1307 top-level "crash/bang". 1308 </p> 1309 <p> 1310 Code in vendor directories is not subject to import path 1311 checking (see 'go help importpath'). 1312 </p> 1313 <p> 1314 When 'go get' checks out or updates a git repository, it now also 1315 updates submodules. 1316 </p> 1317 <p> 1318 Vendor directories do not affect the placement of new repositories 1319 being checked out for the first time by 'go get': those are always 1320 placed in the main GOPATH, never in a vendor subtree. 1321 </p> 1322 <p> 1323 See <a href="https://golang.org/s/go15vendor">https://golang.org/s/go15vendor</a> for details. 1324 </p> 1325 <h3 id="hdr-Environment_variables">Environment variables</h3> 1326 <p> 1327 The go command, and the tools it invokes, examine a few different 1328 environment variables. For many of these, you can see the default 1329 value of on your system by running 'go env NAME', where NAME is the 1330 name of the variable. 1331 </p> 1332 <p> 1333 General-purpose environment variables: 1334 </p> 1335 <pre>GCCGO 1336 The gccgo command to run for 'go build -compiler=gccgo'. 1337 GOARCH 1338 The architecture, or processor, for which to compile code. 1339 Examples are amd64, 386, arm, ppc64. 1340 GOBIN 1341 The directory where 'go install' will install a command. 1342 GOOS 1343 The operating system for which to compile code. 1344 Examples are linux, darwin, windows, netbsd. 1345 GOPATH 1346 For more details see: 'go help gopath'. 1347 GORACE 1348 Options for the race detector. 1349 See <a href="https://golang.org/doc/articles/race_detector.html">https://golang.org/doc/articles/race_detector.html</a>. 1350 GOROOT 1351 The root of the go tree. 1352 </pre> 1353 <p> 1354 Environment variables for use with cgo: 1355 </p> 1356 <pre>CC 1357 The command to use to compile C code. 1358 CGO_ENABLED 1359 Whether the cgo command is supported. Either 0 or 1. 1360 CGO_CFLAGS 1361 Flags that cgo will pass to the compiler when compiling 1362 C code. 1363 CGO_CPPFLAGS 1364 Flags that cgo will pass to the compiler when compiling 1365 C or C++ code. 1366 CGO_CXXFLAGS 1367 Flags that cgo will pass to the compiler when compiling 1368 C++ code. 1369 CGO_FFLAGS 1370 Flags that cgo will pass to the compiler when compiling 1371 Fortran code. 1372 CGO_LDFLAGS 1373 Flags that cgo will pass to the compiler when linking. 1374 CXX 1375 The command to use to compile C++ code. 1376 PKG_CONFIG 1377 Path to pkg-config tool. 1378 </pre> 1379 <p> 1380 Architecture-specific environment variables: 1381 </p> 1382 <pre>GOARM 1383 For GOARCH=arm, the ARM architecture for which to compile. 1384 Valid values are 5, 6, 7. 1385 GO386 1386 For GOARCH=386, the floating point instruction set. 1387 Valid values are 387, sse2. 1388 </pre> 1389 <p> 1390 Special-purpose environment variables: 1391 </p> 1392 <pre>GOROOT_FINAL 1393 The root of the installed Go tree, when it is 1394 installed in a location other than where it is built. 1395 File names in stack traces are rewritten from GOROOT to 1396 GOROOT_FINAL. 1397 GO_EXTLINK_ENABLED 1398 Whether the linker should use external linking mode 1399 when using -linkmode=auto with code that uses cgo. 1400 Set to 0 to disable external linking mode, 1 to enable it. 1401 GIT_ALLOW_PROTOCOL 1402 Defined by Git. A colon-separated list of schemes that are allowed to be used 1403 with git fetch/clone. If set, any scheme not explicitly mentioned will be 1404 considered insecure by 'go get'. 1405 </pre> 1406 <h3 id="hdr-Import_path_syntax">Import path syntax</h3> 1407 <p> 1408 An import path (see 'go help packages') denotes a package stored in the local 1409 file system. In general, an import path denotes either a standard package (such 1410 as "unicode/utf8") or a package found in one of the work spaces (For more 1411 details see: 'go help gopath'). 1412 </p> 1413 <h3 id="hdr-Relative_import_paths">Relative import paths</h3> 1414 <p> 1415 An import path beginning with ./ or ../ is called a relative path. 1416 The toolchain supports relative import paths as a shortcut in two ways. 1417 </p> 1418 <p> 1419 First, a relative path can be used as a shorthand on the command line. 1420 If you are working in the directory containing the code imported as 1421 "unicode" and want to run the tests for "unicode/utf8", you can type 1422 "go test ./utf8" instead of needing to specify the full path. 1423 Similarly, in the reverse situation, "go test .." will test "unicode" from 1424 the "unicode/utf8" directory. Relative patterns are also allowed, like 1425 "go test ./..." to test all subdirectories. See 'go help packages' for details 1426 on the pattern syntax. 1427 </p> 1428 <p> 1429 Second, if you are compiling a Go program not in a work space, 1430 you can use a relative path in an import statement in that program 1431 to refer to nearby code also not in a work space. 1432 This makes it easy to experiment with small multipackage programs 1433 outside of the usual work spaces, but such programs cannot be 1434 installed with "go install" (there is no work space in which to install them), 1435 so they are rebuilt from scratch each time they are built. 1436 To avoid ambiguity, Go programs cannot use relative import paths 1437 within a work space. 1438 </p> 1439 <h3 id="hdr-Remote_import_paths">Remote import paths</h3> 1440 <p> 1441 Certain import paths also 1442 describe how to obtain the source code for the package using 1443 a revision control system. 1444 </p> 1445 <p> 1446 A few common code hosting sites have special syntax: 1447 </p> 1448 <pre>Bitbucket (Git, Mercurial) 1449 1450 import "bitbucket.org/user/project" 1451 import "bitbucket.org/user/project/sub/directory" 1452 1453 GitHub (Git) 1454 1455 import "github.com/user/project" 1456 import "github.com/user/project/sub/directory" 1457 1458 Launchpad (Bazaar) 1459 1460 import "launchpad.net/project" 1461 import "launchpad.net/project/series" 1462 import "launchpad.net/project/series/sub/directory" 1463 1464 import "launchpad.net/~user/project/branch" 1465 import "launchpad.net/~user/project/branch/sub/directory" 1466 1467 IBM DevOps Services (Git) 1468 1469 import "hub.jazz.net/git/user/project" 1470 import "hub.jazz.net/git/user/project/sub/directory" 1471 </pre> 1472 <p> 1473 For code hosted on other servers, import paths may either be qualified 1474 with the version control type, or the go tool can dynamically fetch 1475 the import path over https/http and discover where the code resides 1476 from a <meta> tag in the HTML. 1477 </p> 1478 <p> 1479 To declare the code location, an import path of the form 1480 </p> 1481 <pre>repository.vcs/path 1482 </pre> 1483 <p> 1484 specifies the given repository, with or without the .vcs suffix, 1485 using the named version control system, and then the path inside 1486 that repository. The supported version control systems are: 1487 </p> 1488 <pre>Bazaar .bzr 1489 Git .git 1490 Mercurial .hg 1491 Subversion .svn 1492 </pre> 1493 <p> 1494 For example, 1495 </p> 1496 <pre>import "example.org/user/foo.hg" 1497 </pre> 1498 <p> 1499 denotes the root directory of the Mercurial repository at 1500 example.org/user/foo or foo.hg, and 1501 </p> 1502 <pre>import "example.org/repo.git/foo/bar" 1503 </pre> 1504 <p> 1505 denotes the foo/bar directory of the Git repository at 1506 example.org/repo or repo.git. 1507 </p> 1508 <p> 1509 When a version control system supports multiple protocols, 1510 each is tried in turn when downloading. For example, a Git 1511 download tries https://, then git+ssh://. 1512 </p> 1513 <p> 1514 By default, downloads are restricted to known secure protocols 1515 (e.g. https, ssh). To override this setting for Git downloads, the 1516 GIT_ALLOW_PROTOCOL environment variable can be set (For more details see: 1517 'go help environment'). 1518 </p> 1519 <p> 1520 If the import path is not a known code hosting site and also lacks a 1521 version control qualifier, the go tool attempts to fetch the import 1522 over https/http and looks for a <meta> tag in the document's HTML 1523 <head>. 1524 </p> 1525 <p> 1526 The meta tag has the form: 1527 </p> 1528 <pre><meta name="go-import" content="import-prefix vcs repo-root"> 1529 </pre> 1530 <p> 1531 The import-prefix is the import path corresponding to the repository 1532 root. It must be a prefix or an exact match of the package being 1533 fetched with "go get". If it's not an exact match, another http 1534 request is made at the prefix to verify the <meta> tags match. 1535 </p> 1536 <p> 1537 The meta tag should appear as early in the file as possible. 1538 In particular, it should appear before any raw JavaScript or CSS, 1539 to avoid confusing the go command's restricted parser. 1540 </p> 1541 <p> 1542 The vcs is one of "git", "hg", "svn", etc, 1543 </p> 1544 <p> 1545 The repo-root is the root of the version control system 1546 containing a scheme and not containing a .vcs qualifier. 1547 </p> 1548 <p> 1549 For example, 1550 </p> 1551 <pre>import "example.org/pkg/foo" 1552 </pre> 1553 <p> 1554 will result in the following requests: 1555 </p> 1556 <pre><a href="https://example.org/pkg/foo?go-get=1">https://example.org/pkg/foo?go-get=1</a> (preferred) 1557 <a href="http://example.org/pkg/foo?go-get=1">http://example.org/pkg/foo?go-get=1</a> (fallback, only with -insecure) 1558 </pre> 1559 <p> 1560 If that page contains the meta tag 1561 </p> 1562 <pre><meta name="go-import" content="example.org git <a href="https://code.org/r/p/exproj">https://code.org/r/p/exproj</a>"> 1563 </pre> 1564 <p> 1565 the go tool will verify that <a href="https://example.org/?go-get=1">https://example.org/?go-get=1</a> contains the 1566 same meta tag and then git clone <a href="https://code.org/r/p/exproj">https://code.org/r/p/exproj</a> into 1567 GOPATH/src/example.org. 1568 </p> 1569 <p> 1570 New downloaded packages are written to the first directory listed in the GOPATH 1571 environment variable (For more details see: 'go help gopath'). 1572 </p> 1573 <p> 1574 The go command attempts to download the version of the 1575 package appropriate for the Go release being used. 1576 Run 'go help get' for more. 1577 </p> 1578 <h3 id="hdr-Import_path_checking">Import path checking</h3> 1579 <p> 1580 When the custom import path feature described above redirects to a 1581 known code hosting site, each of the resulting packages has two possible 1582 import paths, using the custom domain or the known hosting site. 1583 </p> 1584 <p> 1585 A package statement is said to have an "import comment" if it is immediately 1586 followed (before the next newline) by a comment of one of these two forms: 1587 </p> 1588 <pre>package math // import "path" 1589 package math /* import "path" */ 1590 </pre> 1591 <p> 1592 The go command will refuse to install a package with an import comment 1593 unless it is being referred to by that import path. In this way, import comments 1594 let package authors make sure the custom import path is used and not a 1595 direct path to the underlying code hosting site. 1596 </p> 1597 <p> 1598 Import path checking is disabled for code found within vendor trees. 1599 This makes it possible to copy code into alternate locations in vendor trees 1600 without needing to update import comments. 1601 </p> 1602 <p> 1603 See <a href="https://golang.org/s/go14customimport">https://golang.org/s/go14customimport</a> for details. 1604 </p> 1605 <h3 id="hdr-Description_of_package_lists">Description of package lists</h3> 1606 <p> 1607 Many commands apply to a set of packages: 1608 </p> 1609 <pre>go action [packages] 1610 </pre> 1611 <p> 1612 Usually, [packages] is a list of import paths. 1613 </p> 1614 <p> 1615 An import path that is a rooted path or that begins with 1616 a . or .. element is interpreted as a file system path and 1617 denotes the package in that directory. 1618 </p> 1619 <p> 1620 Otherwise, the import path P denotes the package found in 1621 the directory DIR/src/P for some DIR listed in the GOPATH 1622 environment variable (For more details see: 'go help gopath'). 1623 </p> 1624 <p> 1625 If no import paths are given, the action applies to the 1626 package in the current directory. 1627 </p> 1628 <p> 1629 There are four reserved names for paths that should not be used 1630 for packages to be built with the go tool: 1631 </p> 1632 <p> 1633 - "main" denotes the top-level package in a stand-alone executable. 1634 </p> 1635 <p> 1636 - "all" expands to all package directories found in all the GOPATH 1637 trees. For example, 'go list all' lists all the packages on the local 1638 system. 1639 </p> 1640 <p> 1641 - "std" is like all but expands to just the packages in the standard 1642 Go library. 1643 </p> 1644 <p> 1645 - "cmd" expands to the Go repository's commands and their 1646 internal libraries. 1647 </p> 1648 <p> 1649 Import paths beginning with "cmd/" only match source code in 1650 the Go repository. 1651 </p> 1652 <p> 1653 An import path is a pattern if it includes one or more "..." wildcards, 1654 each of which can match any string, including the empty string and 1655 strings containing slashes. Such a pattern expands to all package 1656 directories found in the GOPATH trees with names matching the 1657 patterns. As a special case, x/... matches x as well as x's subdirectories. 1658 For example, net/... expands to net and packages in its subdirectories. 1659 </p> 1660 <p> 1661 An import path can also name a package to be downloaded from 1662 a remote repository. Run 'go help importpath' for details. 1663 </p> 1664 <p> 1665 Every package in a program must have a unique import path. 1666 By convention, this is arranged by starting each path with a 1667 unique prefix that belongs to you. For example, paths used 1668 internally at Google all begin with 'google', and paths 1669 denoting remote repositories begin with the path to the code, 1670 such as 'github.com/user/repo'. 1671 </p> 1672 <p> 1673 Packages in a program need not have unique package names, 1674 but there are two reserved package names with special meaning. 1675 The name main indicates a command, not a library. 1676 Commands are built into binaries and cannot be imported. 1677 The name documentation indicates documentation for 1678 a non-Go program in the directory. Files in package documentation 1679 are ignored by the go command. 1680 </p> 1681 <p> 1682 As a special case, if the package list is a list of .go files from a 1683 single directory, the command is applied to a single synthesized 1684 package made up of exactly those files, ignoring any build constraints 1685 in those files and ignoring any other files in the directory. 1686 </p> 1687 <p> 1688 Directory and file names that begin with "." or "_" are ignored 1689 by the go tool, as are directories named "testdata". 1690 </p> 1691 <h3 id="hdr-Description_of_testing_flags">Description of testing flags</h3> 1692 <p> 1693 The 'go test' command takes both flags that apply to 'go test' itself 1694 and flags that apply to the resulting test binary. 1695 </p> 1696 <p> 1697 Several of the flags control profiling and write an execution profile 1698 suitable for "go tool pprof"; run "go tool pprof -h" for more 1699 information. The --alloc_space, --alloc_objects, and --show_bytes 1700 options of pprof control how the information is presented. 1701 </p> 1702 <p> 1703 The following flags are recognized by the 'go test' command and 1704 control the execution of any test: 1705 </p> 1706 <pre>-bench regexp 1707 Run (sub)benchmarks matching a regular expression. 1708 The given regular expression is split into smaller ones by 1709 top-level '/', where each must match the corresponding part of a 1710 benchmark's identifier. 1711 By default, no benchmarks run. To run all benchmarks, 1712 use '-bench .' or '-bench=.'. 1713 1714 -benchtime t 1715 Run enough iterations of each benchmark to take t, specified 1716 as a time.Duration (for example, -benchtime 1h30s). 1717 The default is 1 second (1s). 1718 1719 -count n 1720 Run each test and benchmark n times (default 1). 1721 If -cpu is set, run n times for each GOMAXPROCS value. 1722 Examples are always run once. 1723 1724 -cover 1725 Enable coverage analysis. 1726 1727 -covermode set,count,atomic 1728 Set the mode for coverage analysis for the package[s] 1729 being tested. The default is "set" unless -race is enabled, 1730 in which case it is "atomic". 1731 The values: 1732 set: bool: does this statement run? 1733 count: int: how many times does this statement run? 1734 atomic: int: count, but correct in multithreaded tests; 1735 significantly more expensive. 1736 Sets -cover. 1737 1738 -coverpkg pkg1,pkg2,pkg3 1739 Apply coverage analysis in each test to the given list of packages. 1740 The default is for each test to analyze only the package being tested. 1741 Packages are specified as import paths. 1742 Sets -cover. 1743 1744 -cpu 1,2,4 1745 Specify a list of GOMAXPROCS values for which the tests or 1746 benchmarks should be executed. The default is the current value 1747 of GOMAXPROCS. 1748 1749 -parallel n 1750 Allow parallel execution of test functions that call t.Parallel. 1751 The value of this flag is the maximum number of tests to run 1752 simultaneously; by default, it is set to the value of GOMAXPROCS. 1753 Note that -parallel only applies within a single test binary. 1754 The 'go test' command may run tests for different packages 1755 in parallel as well, according to the setting of the -p flag 1756 (see 'go help build'). 1757 1758 -run regexp 1759 Run only those tests and examples matching the regular expression. 1760 For tests the regular expression is split into smaller ones by 1761 top-level '/', where each must match the corresponding part of a 1762 test's identifier. 1763 1764 -short 1765 Tell long-running tests to shorten their run time. 1766 It is off by default but set during all.bash so that installing 1767 the Go tree can run a sanity check but not spend time running 1768 exhaustive tests. 1769 1770 -timeout t 1771 If a test runs longer than t, panic. 1772 The default is 10 minutes (10m). 1773 1774 -v 1775 Verbose output: log all tests as they are run. Also print all 1776 text from Log and Logf calls even if the test succeeds. 1777 </pre> 1778 <p> 1779 The following flags are also recognized by 'go test' and can be used to 1780 profile the tests during execution: 1781 </p> 1782 <pre>-benchmem 1783 Print memory allocation statistics for benchmarks. 1784 1785 -blockprofile block.out 1786 Write a goroutine blocking profile to the specified file 1787 when all tests are complete. 1788 Writes test binary as -c would. 1789 1790 -blockprofilerate n 1791 Control the detail provided in goroutine blocking profiles by 1792 calling runtime.SetBlockProfileRate with n. 1793 See 'go doc runtime.SetBlockProfileRate'. 1794 The profiler aims to sample, on average, one blocking event every 1795 n nanoseconds the program spends blocked. By default, 1796 if -test.blockprofile is set without this flag, all blocking events 1797 are recorded, equivalent to -test.blockprofilerate=1. 1798 1799 -coverprofile cover.out 1800 Write a coverage profile to the file after all tests have passed. 1801 Sets -cover. 1802 1803 -cpuprofile cpu.out 1804 Write a CPU profile to the specified file before exiting. 1805 Writes test binary as -c would. 1806 1807 -memprofile mem.out 1808 Write a memory profile to the file after all tests have passed. 1809 Writes test binary as -c would. 1810 1811 -memprofilerate n 1812 Enable more precise (and expensive) memory profiles by setting 1813 runtime.MemProfileRate. See 'go doc runtime.MemProfileRate'. 1814 To profile all memory allocations, use -test.memprofilerate=1 1815 and pass --alloc_space flag to the pprof tool. 1816 1817 -mutexprofile mutex.out 1818 Write a mutex contention profile to the specified file 1819 when all tests are complete. 1820 Writes test binary as -c would. 1821 1822 -mutexprofilefraction n 1823 Sample 1 in n stack traces of goroutines holding a 1824 contended mutex. 1825 1826 -outputdir directory 1827 Place output files from profiling in the specified directory, 1828 by default the directory in which "go test" is running. 1829 1830 -trace trace.out 1831 Write an execution trace to the specified file before exiting. 1832 </pre> 1833 <p> 1834 Each of these flags is also recognized with an optional 'test.' prefix, 1835 as in -test.v. When invoking the generated test binary (the result of 1836 'go test -c') directly, however, the prefix is mandatory. 1837 </p> 1838 <p> 1839 The 'go test' command rewrites or removes recognized flags, 1840 as appropriate, both before and after the optional package list, 1841 before invoking the test binary. 1842 </p> 1843 <p> 1844 For instance, the command 1845 </p> 1846 <pre>go test -v -myflag testdata -cpuprofile=prof.out -x 1847 </pre> 1848 <p> 1849 will compile the test binary and then run it as 1850 </p> 1851 <pre>pkg.test -test.v -myflag testdata -test.cpuprofile=prof.out 1852 </pre> 1853 <p> 1854 (The -x flag is removed because it applies only to the go command's 1855 execution, not to the test itself.) 1856 </p> 1857 <p> 1858 The test flags that generate profiles (other than for coverage) also 1859 leave the test binary in pkg.test for use when analyzing the profiles. 1860 </p> 1861 <p> 1862 When 'go test' runs a test binary, it does so from within the 1863 corresponding package's source code directory. Depending on the test, 1864 it may be necessary to do the same when invoking a generated test 1865 binary directly. 1866 </p> 1867 <p> 1868 The command-line package list, if present, must appear before any 1869 flag not known to the go test command. Continuing the example above, 1870 the package list would have to appear before -myflag, but could appear 1871 on either side of -v. 1872 </p> 1873 <p> 1874 To keep an argument for a test binary from being interpreted as a 1875 known flag or a package name, use -args (see 'go help test') which 1876 passes the remainder of the command line through to the test binary 1877 uninterpreted and unaltered. 1878 </p> 1879 <p> 1880 For instance, the command 1881 </p> 1882 <pre>go test -v -args -x -v 1883 </pre> 1884 <p> 1885 will compile the test binary and then run it as 1886 </p> 1887 <pre>pkg.test -test.v -x -v 1888 </pre> 1889 <p> 1890 Similarly, 1891 </p> 1892 <pre>go test -args math 1893 </pre> 1894 <p> 1895 will compile the test binary and then run it as 1896 </p> 1897 <pre>pkg.test math 1898 </pre> 1899 <p> 1900 In the first example, the -x and the second -v are passed through to the 1901 test binary unchanged and with no effect on the go command itself. 1902 In the second example, the argument math is passed through to the test 1903 binary, instead of being interpreted as the package list. 1904 </p> 1905 <h3 id="hdr-Description_of_testing_functions">Description of testing functions</h3> 1906 <p> 1907 The 'go test' command expects to find test, benchmark, and example functions 1908 in the "*_test.go" files corresponding to the package under test. 1909 </p> 1910 <p> 1911 A test function is one named TestXXX (where XXX is any alphanumeric string 1912 not starting with a lower case letter) and should have the signature, 1913 </p> 1914 <pre>func TestXXX(t *testing.T) { ... } 1915 </pre> 1916 <p> 1917 A benchmark function is one named BenchmarkXXX and should have the signature, 1918 </p> 1919 <pre>func BenchmarkXXX(b *testing.B) { ... } 1920 </pre> 1921 <p> 1922 An example function is similar to a test function but, instead of using 1923 *testing.T to report success or failure, prints output to os.Stdout. 1924 If the last comment in the function starts with "Output:" then the output 1925 is compared exactly against the comment (see examples below). If the last 1926 comment begins with "Unordered output:" then the output is compared to the 1927 comment, however the order of the lines is ignored. An example with no such 1928 comment is compiled but not executed. An example with no text after 1929 "Output:" is compiled, executed, and expected to produce no output. 1930 </p> 1931 <p> 1932 Godoc displays the body of ExampleXXX to demonstrate the use 1933 of the function, constant, or variable XXX. An example of a method M with 1934 receiver type T or *T is named ExampleT_M. There may be multiple examples 1935 for a given function, constant, or variable, distinguished by a trailing _xxx, 1936 where xxx is a suffix not beginning with an upper case letter. 1937 </p> 1938 <p> 1939 Here is an example of an example: 1940 </p> 1941 <pre>func ExamplePrintln() { 1942 Println("The output of\nthis example.") 1943 // Output: The output of 1944 // this example. 1945 } 1946 </pre> 1947 <p> 1948 Here is another example where the ordering of the output is ignored: 1949 </p> 1950 <pre>func ExamplePerm() { 1951 for _, value := range Perm(4) { 1952 fmt.Println(value) 1953 } 1954 1955 // Unordered output: 4 1956 // 2 1957 // 1 1958 // 3 1959 // 0 1960 } 1961 </pre> 1962 <p> 1963 The entire test file is presented as the example when it contains a single 1964 example function, at least one other function, type, variable, or constant 1965 declaration, and no test or benchmark functions. 1966 </p> 1967 <p> 1968 See the documentation of the testing package for more information. 1969 </p> 1970 1971 <div id="footer"> 1972 Build version go1.8.<br> 1973 Except as <a href="https://developers.google.com/site-policies#restrictions">noted</a>, 1974 the content of this page is licensed under the 1975 Creative Commons Attribution 3.0 License, 1976 and code is licensed under a <a href="/LICENSE">BSD license</a>.<br> 1977 <a href="/doc/tos.html">Terms of Service</a> | 1978 <a href="http://www.google.com/intl/en/policies/privacy/">Privacy Policy</a> 1979 </div> 1980 1981 </div><!-- .container --> 1982 </div><!-- #page --> 1983 1984 <!-- TODO(adonovan): load these from <head> using "defer" attribute? --> 1985 <script type="text/javascript" src="/serverpush/static/jquery.min.js?{{.CacheBust}}"></script> 1986 <script type="text/javascript" src="/serverpush/static/playground.js?{{.CacheBust}}"></script> 1987 <script>var goVersion = "go1.8";</script> 1988 <script type="text/javascript" src="/serverpush/static/godocs.js?{{.CacheBust}}"></script> 1989 </body> 1990 </html> 1991 `))