vendor/golang.org/x/net/http2/h2demo/tmpl.go

   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="http://{{.HTTPHost}}/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">&#9661;</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 &#34;go help [command]&#34; 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 &#34;go help [topic]&#34; 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 (&#39;go build ed.go rx.go&#39; writes &#39;ed&#39; or &#39;ed.exe&#39;)
 191 or the source code directory (&#39;go build unix/sam&#39; writes &#39;sam&#39; or &#39;sam.exe&#39;).
 192 The &#39;.exe&#39; 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 &#39;_test.go&#39;.
 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 &#39;flag list&#39;
 239         arguments to pass on each go tool asm invocation.
 240 -buildmode mode
 241         build mode to use. See &#39;go help buildmode&#39; for more.
 242 -compiler name
 243         name of compiler to use, as in runtime.Compiler (gccgo or gc).
 244 -gccgoflags &#39;arg list&#39;
 245         arguments to pass on each gccgo compiler/linker invocation.
 246 -gcflags &#39;arg list&#39;
 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 &#39;flag list&#39;
 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 &#39;tag list&#39;
 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 &#39;cmd args&#39;
 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         &#39;cmd args /path/to/asm &lt;arguments for asm&gt;&#39;.
 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 &#39;go help packages&#39;.
 279 For more about where packages and binaries are installed,
 280 run &#39;go help gopath&#39;.
 281 For more about calling between Go and C/C++, run &#39;go help c&#39;.
 282 </p>
 283 <p>
 284 Note: Build adheres to certain conventions such as those described
 285 by &#39;go help gopath&#39;. 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 &#39;go tool compile&#39; and &#39;go tool link&#39; 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 &#39;go install&#39; 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 &#39;go help build&#39;.
 345 </p>
 346 <p>
 347 For more about specifying packages, see &#39;go help packages&#39;.
 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 &#34;under&#34; 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 &lt;pkg&gt;
 381 go doc &lt;sym&gt;[.&lt;method&gt;]
 382 go doc [&lt;pkg&gt;.]&lt;sym&gt;[.&lt;method&gt;]
 383 go doc [&lt;pkg&gt;.][&lt;sym&gt;.]&lt;method&gt;
 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 &#34;go doc Foo&#34; 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&#39;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 &lt;pkg&gt; &lt;sym&gt;[.&lt;method&gt;]
 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&#39;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&#39;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&#39;s New function.
 445 go doc text/template new # Two arguments
 446         Show documentation for text/template&#39;s New function.
 447
 448 At least in the current tree, these invocations all print the
 449 documentation for json.Decoder&#39;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&#39;s exported symbols are hidden
 464         when showing the package&#39;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 &#39;go doc cmd/fix&#39;.
 505 For more about specifying packages, see &#39;go help packages&#39;.
 506 </p>
 507 <p>
 508 To run fix with specific options, run &#39;go tool fix&#39;.
 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 &#39;gofmt -l -w&#39; 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 &#39;go doc cmd/gofmt&#39;.
 525 For more about specifying packages, see &#39;go help packages&#39;.
 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 &#34;//go&#34;) 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 &#34;globbing&#34; 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 &#34;foo&#34; represents the generator
 624 &#34;go tool foo&#34;.
 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, &#34;go generate&#34; skips
 636 all further processing for that package.
 637 </p>
 638 <p>
 639 The generator is run in the package&#39;s source directory.
 640 </p>
 641 <p>
 642 Go generate accepts one specific flag:
 643 </p>
 644 <pre>-run=&#34;&#34;
 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 &#39;go help build&#39;.
 659 </p>
 660 <p>
 661 For more about specifying packages, see &#39;go help packages&#39;.
 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 &#39;go install&#39;.
 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 &#39;go help build&#39;.
 705 </p>
 706 <p>
 707 When checking out a new package, get creates the target directory
 708 GOPATH/src/&lt;import-path&gt;. If the GOPATH contains multiple entries,
 709 get uses the first one. For more details see: &#39;go help gopath&#39;.
 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 &#34;go1&#34;, get
 715 searches for a branch or tag named &#34;go1&#34;. 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 &#39;go help packages&#39;.
 727 </p>
 728 <p>
 729 For more about how &#39;go get&#39; finds source code to
 730 download, see &#39;go help importpath&#39;.
 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 &#39;go help build&#39;.
 747 For more about specifying packages, see &#39;go help packages&#39;.
 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 &#39;&#39;. 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 &#39;go install&#39; 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 &#34;C&#34;
 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, &#34;d/vendor/p&#34; instead of &#34;p&#34;),
 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 &#34;join&#34; calls strings.Join.
 844 </p>
 845 <p>
 846 The template function &#34;context&#34; 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&#39;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 &#39;go help build&#39;.
 882 </p>
 883 <p>
 884 For more about specifying packages, see &#39;go help packages&#39;.
 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 &#34;.go&#34; suffix.
 895 </p>
 896 <p>
 897 By default, &#39;go run&#39; runs the compiled binary directly: &#39;a.out arguments...&#39;.
 898 If the -exec flag is given, &#39;go run&#39; invokes the binary using xprog:
 899 </p>
 900 <pre>&#39;xprog a.out arguments...&#39;.
 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, &#39;go run&#39; invokes the binary using that program,
 906 for example &#39;go_nacl_386_exec a.out arguments...&#39;. 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 &#39;go help build&#39;.
 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 &amp; test binary flags]
 921 </pre>
 922 <p>
 923 &#39;Go test&#39; 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 &#39;Go test&#39; recompiles each package along with any files with names matching
 936 the file pattern &#34;*_test.go&#34;.
 937 Files whose names begin with &#34;_&#34; (including &#34;_test.go&#34;) or &#34;.&#34; are ignored.
 938 These additional files can contain test functions, benchmark functions, and
 939 example functions.  See &#39;go help testfunc&#39; 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 &#34;_test&#34; 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 &#34;testdata&#34;, 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 &#39;go test&#39; 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&#39;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 &#39;go run&#39;. See &#39;go help run&#39; 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 &#39;go test&#39;. See &#39;go help testflag&#39; for details.
 987 </p>
 988 <p>
 989 For more about build flags, see &#39;go help build&#39;.
 990 For more about specifying packages, see &#39;go help packages&#39;.
 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 &#39;go tool command -h&#39;.
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 &#39;go doc cmd/vet&#39;.
1032 For more about specifying packages, see &#39;go help packages&#39;.
1033 </p>
1034 <p>
1035 To run the vet tool with specific options, run &#39;go tool vet&#39;.
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 &#39;go help build&#39;.
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 &#39;go build&#39; and &#39;go install&#39; 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 &#34;go&#34; in the user&#39;s home directory
1171 ($HOME/go on Unix, %USERPROFILE%\go on Windows),
1172 unless that directory holds a Go distribution.
1173 Run &#34;go env GOPATH&#34; 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 &#34;foo/bar&#34; and
1194 has its compiled form installed to &#34;DIR/pkg/GOOS_GOARCH/foo/bar.a&#34;.
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 &#34;foo/&#34; 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&#39;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 &#34;internal&#34; is importable only
1237 by code in the directory tree rooted at the parent of &#34;internal&#34;.
1238 Here&#39;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 &#34;foo/internal/baz&#34;, 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 &#34;foo/internal/baz&#34;, 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 &#34;vendor&#34; is importable only
1272 by code in the directory tree rooted at the parent of &#34;vendor&#34;,
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&#39;s the example from the previous section,
1278 but with the &#34;internal&#34; directory renamed to &#34;vendor&#34;
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 &#34;baz&#34;, not as &#34;foo/vendor/baz&#34;.
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 &#34;crash/bang&#34; resolves to &#34;foo/vendor/crash/bang&#34;, not the
1307 top-level &#34;crash/bang&#34;.
1308 </p>
1309 <p>
1310 Code in vendor directories is not subject to import path
1311 checking (see &#39;go help importpath&#39;).
1312 </p>
1313 <p>
1314 When &#39;go get&#39; 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 &#39;go get&#39;: 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 &#39;go env NAME&#39;, 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 &#39;go build -compiler=gccgo&#39;.
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 &#39;go install&#39; 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: &#39;go help gopath&#39;.
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 &#39;go get&#39;.
1405 </pre>
1406 <h3 id="hdr-Import_path_syntax">Import path syntax</h3>
1407 <p>
1408 An import path (see &#39;go help packages&#39;) denotes a package stored in the local
1409 file system.  In general, an import path denotes either a standard package (such
1410 as &#34;unicode/utf8&#34;) or a package found in one of the work spaces (For more
1411 details see: &#39;go help gopath&#39;).
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 &#34;unicode&#34; and want to run the tests for &#34;unicode/utf8&#34;, you can type
1422 &#34;go test ./utf8&#34; instead of needing to specify the full path.
1423 Similarly, in the reverse situation, &#34;go test ..&#34; will test &#34;unicode&#34; from
1424 the &#34;unicode/utf8&#34; directory. Relative patterns are also allowed, like
1425 &#34;go test ./...&#34; to test all subdirectories. See &#39;go help packages&#39; 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 &#34;go install&#34; (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 &#34;bitbucket.org/user/project&#34;
1451         import &#34;bitbucket.org/user/project/sub/directory&#34;
1452
1453 GitHub (Git)
1454
1455         import &#34;github.com/user/project&#34;
1456         import &#34;github.com/user/project/sub/directory&#34;
1457
1458 Launchpad (Bazaar)
1459
1460         import &#34;launchpad.net/project&#34;
1461         import &#34;launchpad.net/project/series&#34;
1462         import &#34;launchpad.net/project/series/sub/directory&#34;
1463
1464         import &#34;launchpad.net/~user/project/branch&#34;
1465         import &#34;launchpad.net/~user/project/branch/sub/directory&#34;
1466
1467 IBM DevOps Services (Git)
1468
1469         import &#34;hub.jazz.net/git/user/project&#34;
1470         import &#34;hub.jazz.net/git/user/project/sub/directory&#34;
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 &lt;meta&gt; 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 &#34;example.org/user/foo.hg&#34;
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 &#34;example.org/repo.git/foo/bar&#34;
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 &#39;go help environment&#39;).
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 &lt;meta&gt; tag in the document&#39;s HTML
1523 &lt;head&gt;.
1524 </p>
1525 <p>
1526 The meta tag has the form:
1527 </p>
1528 <pre>&lt;meta name=&#34;go-import&#34; content=&#34;import-prefix vcs repo-root&#34;&gt;
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 &#34;go get&#34;. If it&#39;s not an exact match, another http
1534 request is made at the prefix to verify the &lt;meta&gt; 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&#39;s restricted parser.
1540 </p>
1541 <p>
1542 The vcs is one of &#34;git&#34;, &#34;hg&#34;, &#34;svn&#34;, 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 &#34;example.org/pkg/foo&#34;
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>&lt;meta name=&#34;go-import&#34; content=&#34;example.org git <a href="https://code.org/r/p/exproj">https://code.org/r/p/exproj</a>&#34;&gt;
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: &#39;go help gopath&#39;).
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 &#39;go help get&#39; 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 &#34;import comment&#34; 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 &#34;path&#34;
1589 package math /* import &#34;path&#34; */
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: &#39;go help gopath&#39;).
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 - &#34;main&#34; denotes the top-level package in a stand-alone executable.
1634 </p>
1635 <p>
1636 - &#34;all&#34; expands to all package directories found in all the GOPATH
1637 trees. For example, &#39;go list all&#39; lists all the packages on the local
1638 system.
1639 </p>
1640 <p>
1641 - &#34;std&#34; is like all but expands to just the packages in the standard
1642 Go library.
1643 </p>
1644 <p>
1645 - &#34;cmd&#34; expands to the Go repository&#39;s commands and their
1646 internal libraries.
1647 </p>
1648 <p>
1649 Import paths beginning with &#34;cmd/&#34; 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 &#34;...&#34; 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&#39;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 &#39;go help importpath&#39; 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 &#39;google&#39;, and paths
1669 denoting remote repositories begin with the path to the code,
1670 such as &#39;github.com/user/repo&#39;.
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 &#34;.&#34; or &#34;_&#34; are ignored
1689 by the go tool, as are directories named &#34;testdata&#34;.
1690 </p>
1691 <h3 id="hdr-Description_of_testing_flags">Description of testing flags</h3>
1692 <p>
1693 The &#39;go test&#39; command takes both flags that apply to &#39;go test&#39; 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 &#34;go tool pprof&#34;; run &#34;go tool pprof -h&#34; 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 &#39;go test&#39; 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 &#39;/&#39;, where each must match the corresponding part of a
1710     benchmark&#39;s identifier.
1711     By default, no benchmarks run. To run all benchmarks,
1712     use &#39;-bench .&#39; or &#39;-bench=.&#39;.
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 &#34;set&#34; unless -race is enabled,
1730     in which case it is &#34;atomic&#34;.
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 &#39;go test&#39; command may run tests for different packages
1755     in parallel as well, according to the setting of the -p flag
1756     (see &#39;go help build&#39;).
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 &#39;/&#39;, where each must match the corresponding part of a
1762     test&#39;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 &#39;go test&#39; 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 &#39;go doc runtime.SetBlockProfileRate&#39;.
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 &#39;go doc runtime.MemProfileRate&#39;.
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 &#34;go test&#34; 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 &#39;test.&#39; prefix,
1835 as in -test.v. When invoking the generated test binary (the result of
1836 &#39;go test -c&#39;) directly, however, the prefix is mandatory.
1837 </p>
1838 <p>
1839 The &#39;go test&#39; 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&#39;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 &#39;go test&#39; runs a test binary, it does so from within the
1863 corresponding package&#39;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 &#39;go help test&#39;) 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 &#39;go test&#39; command expects to find test, benchmark, and example functions
1908 in the &#34;*_test.go&#34; 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 &#34;Output:&#34; then the output
1925 is compared exactly against the comment (see examples below). If the last
1926 comment begins with &#34;Unordered output:&#34; 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 &#34;Output:&#34; 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(&#34;The output of\nthis example.&#34;)
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 `))