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