| // Copyright 2017 The Go Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style |
| // license that can be found in the LICENSE file. |
| |
| package main |
| |
| import "html/template" |
| |
| var pushTmpl = template.Must(template.New("serverpush").Parse(` |
| |
| <!DOCTYPE html> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| <meta name="theme-color" content="#375EAB"> |
| |
| <title>HTTP/2 Server Push Demo</title> |
| |
| <link type="text/css" rel="stylesheet" href="/serverpush/static/style.css?{{.CacheBust}}"> |
| <script> |
| window.initFuncs = []; |
| </script> |
| |
| <script> |
| function showtimes() { |
| var times = 'DOM loaded: ' + (window.performance.timing.domContentLoadedEventEnd - window.performance.timing.navigationStart) + 'ms, ' |
| times += 'DOM complete (all loaded): ' + (window.performance.timing.domComplete - window.performance.timing.navigationStart) + 'ms, ' |
| times += 'Load event fired: ' + (window.performance.timing.loadEventStart - window.performance.timing.navigationStart) + 'ms' |
| document.getElementById('loadtimes').innerHTML = times |
| } |
| </script> |
| |
| </head> |
| <body onload="showtimes()"> |
| |
| <div style="background:#fff9a4;padding:10px"> |
| 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>. |
| </div> |
| |
| <div style="padding:20px"> |
| |
| |
| <a href="https://{{.HTTPSHost}}/serverpush">HTTP/2 with Server Push</a> | <a href="{{.HTTP1Prefix}}/serverpush">HTTP only</a> |
| <div id="loadtimes"></div> |
| |
| </div> |
| |
| <div id='lowframe' style="position: fixed; bottom: 0; left: 0; height: 0; width: 100%; border-top: thin solid grey; background-color: white; overflow: auto;"> |
| ... |
| </div><!-- #lowframe --> |
| |
| <div id="topbar" class="wide"><div class="container"> |
| <div class="top-heading" id="heading-wide"><a href="/">The Go Programming Language</a></div> |
| <div class="top-heading" id="heading-narrow"><a href="/">Go</a></div> |
| <a href="#" id="menu-button"><span id="menu-button-arrow">▽</span></a> |
| <form method="GET" action="/search"> |
| <div id="menu"> |
| <a href="/doc/">Documents</a> |
| <a href="/pkg/">Packages</a> |
| <a href="/project/">The Project</a> |
| <a href="/help/">Help</a> |
| <a href="/blog/">Blog</a> |
| |
| <a id="playgroundButton" href="http://play.golang.org/" title="Show Go Playground">Play</a> |
| |
| <input type="text" id="search" name="q" class="inactive" value="Search" placeholder="Search"> |
| </div> |
| </form> |
| |
| </div></div> |
| |
| |
| <div id="playground" class="play"> |
| <div class="input"><textarea class="code" spellcheck="false">package main |
| |
| import "fmt" |
| |
| func main() { |
| fmt.Println("Hello, 世界") |
| }</textarea></div> |
| <div class="output"></div> |
| <div class="buttons"> |
| <a class="run" title="Run this code [shift-enter]">Run</a> |
| <a class="fmt" title="Format this code">Format</a> |
| |
| <a class="share" title="Share this code">Share</a> |
| |
| </div> |
| </div> |
| |
| |
| <div id="page" class="wide"> |
| <div class="container"> |
| |
| |
| <h1>Command go</h1> |
| |
| |
| |
| |
| <div id="nav"></div> |
| |
| |
| <!-- |
| Copyright 2009 The Go Authors. All rights reserved. |
| Use of this source code is governed by a BSD-style |
| license that can be found in the LICENSE file. |
| --> |
| <!-- |
| Note: Static (i.e., not template-generated) href and id |
| attributes start with "pkg-" to make it impossible for |
| them to conflict with generated attributes (some of which |
| correspond to Go identifiers). |
| --> |
| |
| <script type='text/javascript'> |
| document.ANALYSIS_DATA = null; |
| document.CALLGRAPH = null; |
| </script> |
| |
| |
| |
| <p> |
| Go is a tool for managing Go source code. |
| </p> |
| <p> |
| Usage: |
| </p> |
| <pre>go command [arguments] |
| </pre> |
| <p> |
| The commands are: |
| </p> |
| <pre>build compile packages and dependencies |
| clean remove object files |
| doc show documentation for package or symbol |
| env print Go environment information |
| bug start a bug report |
| fix run go tool fix on packages |
| fmt run gofmt on package sources |
| generate generate Go files by processing source |
| get download and install packages and dependencies |
| install compile and install packages and dependencies |
| list list packages |
| run compile and run Go program |
| test test packages |
| tool run specified go tool |
| version print Go version |
| vet run go tool vet on packages |
| </pre> |
| <p> |
| Use "go help [command]" for more information about a command. |
| </p> |
| <p> |
| Additional help topics: |
| </p> |
| <pre>c calling between Go and C |
| buildmode description of build modes |
| filetype file types |
| gopath GOPATH environment variable |
| environment environment variables |
| importpath import path syntax |
| packages description of package lists |
| testflag description of testing flags |
| testfunc description of testing functions |
| </pre> |
| <p> |
| Use "go help [topic]" for more information about that topic. |
| </p> |
| <h3 id="hdr-Compile_packages_and_dependencies">Compile packages and dependencies</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go build [-o output] [-i] [build flags] [packages] |
| </pre> |
| <p> |
| Build compiles the packages named by the import paths, |
| along with their dependencies, but it does not install the results. |
| </p> |
| <p> |
| If the arguments to build are a list of .go files, build treats |
| them as a list of source files specifying a single package. |
| </p> |
| <p> |
| When compiling a single main package, build writes |
| the resulting executable to an output file named after |
| the first source file ('go build ed.go rx.go' writes 'ed' or 'ed.exe') |
| or the source code directory ('go build unix/sam' writes 'sam' or 'sam.exe'). |
| The '.exe' suffix is added when writing a Windows executable. |
| </p> |
| <p> |
| When compiling multiple packages or a single non-main package, |
| build compiles the packages but discards the resulting object, |
| serving only as a check that the packages can be built. |
| </p> |
| <p> |
| When compiling packages, build ignores files that end in '_test.go'. |
| </p> |
| <p> |
| The -o flag, only allowed when compiling a single package, |
| forces build to write the resulting executable or object |
| to the named output file, instead of the default behavior described |
| in the last two paragraphs. |
| </p> |
| <p> |
| The -i flag installs the packages that are dependencies of the target. |
| </p> |
| <p> |
| The build flags are shared by the build, clean, get, install, list, run, |
| and test commands: |
| </p> |
| <pre>-a |
| force rebuilding of packages that are already up-to-date. |
| -n |
| print the commands but do not run them. |
| -p n |
| the number of programs, such as build commands or |
| test binaries, that can be run in parallel. |
| The default is the number of CPUs available. |
| -race |
| enable data race detection. |
| Supported only on linux/amd64, freebsd/amd64, darwin/amd64 and windows/amd64. |
| -msan |
| enable interoperation with memory sanitizer. |
| Supported only on linux/amd64, |
| and only with Clang/LLVM as the host C compiler. |
| -v |
| print the names of packages as they are compiled. |
| -work |
| print the name of the temporary work directory and |
| do not delete it when exiting. |
| -x |
| print the commands. |
| |
| -asmflags 'flag list' |
| arguments to pass on each go tool asm invocation. |
| -buildmode mode |
| build mode to use. See 'go help buildmode' for more. |
| -compiler name |
| name of compiler to use, as in runtime.Compiler (gccgo or gc). |
| -gccgoflags 'arg list' |
| arguments to pass on each gccgo compiler/linker invocation. |
| -gcflags 'arg list' |
| arguments to pass on each go tool compile invocation. |
| -installsuffix suffix |
| a suffix to use in the name of the package installation directory, |
| in order to keep output separate from default builds. |
| If using the -race flag, the install suffix is automatically set to race |
| or, if set explicitly, has _race appended to it. Likewise for the -msan |
| flag. Using a -buildmode option that requires non-default compile flags |
| has a similar effect. |
| -ldflags 'flag list' |
| arguments to pass on each go tool link invocation. |
| -linkshared |
| link against shared libraries previously created with |
| -buildmode=shared. |
| -pkgdir dir |
| install and load all packages from dir instead of the usual locations. |
| For example, when building with a non-standard configuration, |
| use -pkgdir to keep generated packages in a separate location. |
| -tags 'tag list' |
| a list of build tags to consider satisfied during the build. |
| For more information about build tags, see the description of |
| build constraints in the documentation for the go/build package. |
| -toolexec 'cmd args' |
| a program to use to invoke toolchain programs like vet and asm. |
| For example, instead of running asm, the go command will run |
| 'cmd args /path/to/asm <arguments for asm>'. |
| </pre> |
| <p> |
| The list flags accept a space-separated list of strings. To embed spaces |
| in an element in the list, surround it with either single or double quotes. |
| </p> |
| <p> |
| For more about specifying packages, see 'go help packages'. |
| For more about where packages and binaries are installed, |
| run 'go help gopath'. |
| For more about calling between Go and C/C++, run 'go help c'. |
| </p> |
| <p> |
| Note: Build adheres to certain conventions such as those described |
| by 'go help gopath'. Not all projects can follow these conventions, |
| however. Installations that have their own conventions or that use |
| a separate software build system may choose to use lower-level |
| invocations such as 'go tool compile' and 'go tool link' to avoid |
| some of the overheads and design decisions of the build tool. |
| </p> |
| <p> |
| See also: go install, go get, go clean. |
| </p> |
| <h3 id="hdr-Remove_object_files">Remove object files</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go clean [-i] [-r] [-n] [-x] [build flags] [packages] |
| </pre> |
| <p> |
| Clean removes object files from package source directories. |
| The go command builds most objects in a temporary directory, |
| so go clean is mainly concerned with object files left by other |
| tools or by manual invocations of go build. |
| </p> |
| <p> |
| Specifically, clean removes the following files from each of the |
| source directories corresponding to the import paths: |
| </p> |
| <pre>_obj/ old object directory, left from Makefiles |
| _test/ old test directory, left from Makefiles |
| _testmain.go old gotest file, left from Makefiles |
| test.out old test log, left from Makefiles |
| build.out old test log, left from Makefiles |
| *.[568ao] object files, left from Makefiles |
| |
| DIR(.exe) from go build |
| DIR.test(.exe) from go test -c |
| MAINFILE(.exe) from go build MAINFILE.go |
| *.so from SWIG |
| </pre> |
| <p> |
| In the list, DIR represents the final path element of the |
| directory, and MAINFILE is the base name of any Go source |
| file in the directory that is not included when building |
| the package. |
| </p> |
| <p> |
| The -i flag causes clean to remove the corresponding installed |
| archive or binary (what 'go install' would create). |
| </p> |
| <p> |
| The -n flag causes clean to print the remove commands it would execute, |
| but not run them. |
| </p> |
| <p> |
| The -r flag causes clean to be applied recursively to all the |
| dependencies of the packages named by the import paths. |
| </p> |
| <p> |
| The -x flag causes clean to print remove commands as it executes them. |
| </p> |
| <p> |
| For more about build flags, see 'go help build'. |
| </p> |
| <p> |
| For more about specifying packages, see 'go help packages'. |
| </p> |
| <h3 id="hdr-Show_documentation_for_package_or_symbol">Show documentation for package or symbol</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go doc [-u] [-c] [package|[package.]symbol[.method]] |
| </pre> |
| <p> |
| Doc prints the documentation comments associated with the item identified by its |
| arguments (a package, const, func, type, var, or method) followed by a one-line |
| summary of each of the first-level items "under" that item (package-level |
| declarations for a package, methods for a type, etc.). |
| </p> |
| <p> |
| Doc accepts zero, one, or two arguments. |
| </p> |
| <p> |
| Given no arguments, that is, when run as |
| </p> |
| <pre>go doc |
| </pre> |
| <p> |
| it prints the package documentation for the package in the current directory. |
| If the package is a command (package main), the exported symbols of the package |
| are elided from the presentation unless the -cmd flag is provided. |
| </p> |
| <p> |
| When run with one argument, the argument is treated as a Go-syntax-like |
| representation of the item to be documented. What the argument selects depends |
| on what is installed in GOROOT and GOPATH, as well as the form of the argument, |
| which is schematically one of these: |
| </p> |
| <pre>go doc <pkg> |
| go doc <sym>[.<method>] |
| go doc [<pkg>.]<sym>[.<method>] |
| go doc [<pkg>.][<sym>.]<method> |
| </pre> |
| <p> |
| The first item in this list matched by the argument is the one whose documentation |
| is printed. (See the examples below.) However, if the argument starts with a capital |
| letter it is assumed to identify a symbol or method in the current directory. |
| </p> |
| <p> |
| For packages, the order of scanning is determined lexically in breadth-first order. |
| That is, the package presented is the one that matches the search and is nearest |
| the root and lexically first at its level of the hierarchy. The GOROOT tree is |
| always scanned in its entirety before GOPATH. |
| </p> |
| <p> |
| If there is no package specified or matched, the package in the current |
| directory is selected, so "go doc Foo" shows the documentation for symbol Foo in |
| the current package. |
| </p> |
| <p> |
| The package path must be either a qualified path or a proper suffix of a |
| path. The go tool's usual package mechanism does not apply: package path |
| elements like . and ... are not implemented by go doc. |
| </p> |
| <p> |
| When run with two arguments, the first must be a full package path (not just a |
| suffix), and the second is a symbol or symbol and method; this is similar to the |
| syntax accepted by godoc: |
| </p> |
| <pre>go doc <pkg> <sym>[.<method>] |
| </pre> |
| <p> |
| In all forms, when matching symbols, lower-case letters in the argument match |
| either case but upper-case letters match exactly. This means that there may be |
| multiple matches of a lower-case argument in a package if different symbols have |
| different cases. If this occurs, documentation for all matches is printed. |
| </p> |
| <p> |
| Examples: |
| </p> |
| <pre>go doc |
| Show documentation for current package. |
| go doc Foo |
| Show documentation for Foo in the current package. |
| (Foo starts with a capital letter so it cannot match |
| a package path.) |
| go doc encoding/json |
| Show documentation for the encoding/json package. |
| go doc json |
| Shorthand for encoding/json. |
| go doc json.Number (or go doc json.number) |
| Show documentation and method summary for json.Number. |
| go doc json.Number.Int64 (or go doc json.number.int64) |
| Show documentation for json.Number's Int64 method. |
| go doc cmd/doc |
| Show package docs for the doc command. |
| go doc -cmd cmd/doc |
| Show package docs and exported symbols within the doc command. |
| go doc template.new |
| Show documentation for html/template's New function. |
| (html/template is lexically before text/template) |
| go doc text/template.new # One argument |
| Show documentation for text/template's New function. |
| go doc text/template new # Two arguments |
| Show documentation for text/template's New function. |
| |
| At least in the current tree, these invocations all print the |
| documentation for json.Decoder's Decode method: |
| |
| go doc json.Decoder.Decode |
| go doc json.decoder.decode |
| go doc json.decode |
| cd go/src/encoding/json; go doc decode |
| </pre> |
| <p> |
| Flags: |
| </p> |
| <pre>-c |
| Respect case when matching symbols. |
| -cmd |
| Treat a command (package main) like a regular package. |
| Otherwise package main's exported symbols are hidden |
| when showing the package's top-level documentation. |
| -u |
| Show documentation for unexported as well as exported |
| symbols and methods. |
| </pre> |
| <h3 id="hdr-Print_Go_environment_information">Print Go environment information</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go env [var ...] |
| </pre> |
| <p> |
| Env prints Go environment information. |
| </p> |
| <p> |
| By default env prints information as a shell script |
| (on Windows, a batch file). If one or more variable |
| names is given as arguments, env prints the value of |
| each named variable on its own line. |
| </p> |
| <h3 id="hdr-Start_a_bug_report">Start a bug report</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go bug |
| </pre> |
| <p> |
| Bug opens the default browser and starts a new bug report. |
| The report includes useful system information. |
| </p> |
| <h3 id="hdr-Run_go_tool_fix_on_packages">Run go tool fix on packages</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go fix [packages] |
| </pre> |
| <p> |
| Fix runs the Go fix command on the packages named by the import paths. |
| </p> |
| <p> |
| For more about fix, see 'go doc cmd/fix'. |
| For more about specifying packages, see 'go help packages'. |
| </p> |
| <p> |
| To run fix with specific options, run 'go tool fix'. |
| </p> |
| <p> |
| See also: go fmt, go vet. |
| </p> |
| <h3 id="hdr-Run_gofmt_on_package_sources">Run gofmt on package sources</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go fmt [-n] [-x] [packages] |
| </pre> |
| <p> |
| Fmt runs the command 'gofmt -l -w' on the packages named |
| by the import paths. It prints the names of the files that are modified. |
| </p> |
| <p> |
| For more about gofmt, see 'go doc cmd/gofmt'. |
| For more about specifying packages, see 'go help packages'. |
| </p> |
| <p> |
| The -n flag prints commands that would be executed. |
| The -x flag prints commands as they are executed. |
| </p> |
| <p> |
| To run gofmt with specific options, run gofmt itself. |
| </p> |
| <p> |
| See also: go fix, go vet. |
| </p> |
| <h3 id="hdr-Generate_Go_files_by_processing_source">Generate Go files by processing source</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go generate [-run regexp] [-n] [-v] [-x] [build flags] [file.go... | packages] |
| </pre> |
| <p> |
| Generate runs commands described by directives within existing |
| files. Those commands can run any process but the intent is to |
| create or update Go source files. |
| </p> |
| <p> |
| Go generate is never run automatically by go build, go get, go test, |
| and so on. It must be run explicitly. |
| </p> |
| <p> |
| Go generate scans the file for directives, which are lines of |
| the form, |
| </p> |
| <pre>//go:generate command argument... |
| </pre> |
| <p> |
| (note: no leading spaces and no space in "//go") where command |
| is the generator to be run, corresponding to an executable file |
| that can be run locally. It must either be in the shell path |
| (gofmt), a fully qualified path (/usr/you/bin/mytool), or a |
| command alias, described below. |
| </p> |
| <p> |
| Note that go generate does not parse the file, so lines that look |
| like directives in comments or multiline strings will be treated |
| as directives. |
| </p> |
| <p> |
| The arguments to the directive are space-separated tokens or |
| double-quoted strings passed to the generator as individual |
| arguments when it is run. |
| </p> |
| <p> |
| Quoted strings use Go syntax and are evaluated before execution; a |
| quoted string appears as a single argument to the generator. |
| </p> |
| <p> |
| Go generate sets several variables when it runs the generator: |
| </p> |
| <pre>$GOARCH |
| The execution architecture (arm, amd64, etc.) |
| $GOOS |
| The execution operating system (linux, windows, etc.) |
| $GOFILE |
| The base name of the file. |
| $GOLINE |
| The line number of the directive in the source file. |
| $GOPACKAGE |
| The name of the package of the file containing the directive. |
| $DOLLAR |
| A dollar sign. |
| </pre> |
| <p> |
| Other than variable substitution and quoted-string evaluation, no |
| special processing such as "globbing" is performed on the command |
| line. |
| </p> |
| <p> |
| As a last step before running the command, any invocations of any |
| environment variables with alphanumeric names, such as $GOFILE or |
| $HOME, are expanded throughout the command line. The syntax for |
| variable expansion is $NAME on all operating systems. Due to the |
| order of evaluation, variables are expanded even inside quoted |
| strings. If the variable NAME is not set, $NAME expands to the |
| empty string. |
| </p> |
| <p> |
| A directive of the form, |
| </p> |
| <pre>//go:generate -command xxx args... |
| </pre> |
| <p> |
| specifies, for the remainder of this source file only, that the |
| string xxx represents the command identified by the arguments. This |
| can be used to create aliases or to handle multiword generators. |
| For example, |
| </p> |
| <pre>//go:generate -command foo go tool foo |
| </pre> |
| <p> |
| specifies that the command "foo" represents the generator |
| "go tool foo". |
| </p> |
| <p> |
| Generate processes packages in the order given on the command line, |
| one at a time. If the command line lists .go files, they are treated |
| as a single package. Within a package, generate processes the |
| source files in a package in file name order, one at a time. Within |
| a source file, generate runs generators in the order they appear |
| in the file, one at a time. |
| </p> |
| <p> |
| If any generator returns an error exit status, "go generate" skips |
| all further processing for that package. |
| </p> |
| <p> |
| The generator is run in the package's source directory. |
| </p> |
| <p> |
| Go generate accepts one specific flag: |
| </p> |
| <pre>-run="" |
| if non-empty, specifies a regular expression to select |
| directives whose full original source text (excluding |
| any trailing spaces and final newline) matches the |
| expression. |
| </pre> |
| <p> |
| It also accepts the standard build flags including -v, -n, and -x. |
| The -v flag prints the names of packages and files as they are |
| processed. |
| The -n flag prints commands that would be executed. |
| The -x flag prints commands as they are executed. |
| </p> |
| <p> |
| For more about build flags, see 'go help build'. |
| </p> |
| <p> |
| For more about specifying packages, see 'go help packages'. |
| </p> |
| <h3 id="hdr-Download_and_install_packages_and_dependencies">Download and install packages and dependencies</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go get [-d] [-f] [-fix] [-insecure] [-t] [-u] [build flags] [packages] |
| </pre> |
| <p> |
| Get downloads the packages named by the import paths, along with their |
| dependencies. It then installs the named packages, like 'go install'. |
| </p> |
| <p> |
| The -d flag instructs get to stop after downloading the packages; that is, |
| it instructs get not to install the packages. |
| </p> |
| <p> |
| The -f flag, valid only when -u is set, forces get -u not to verify that |
| each package has been checked out from the source control repository |
| implied by its import path. This can be useful if the source is a local fork |
| of the original. |
| </p> |
| <p> |
| The -fix flag instructs get to run the fix tool on the downloaded packages |
| before resolving dependencies or building the code. |
| </p> |
| <p> |
| The -insecure flag permits fetching from repositories and resolving |
| custom domains using insecure schemes such as HTTP. Use with caution. |
| </p> |
| <p> |
| The -t flag instructs get to also download the packages required to build |
| the tests for the specified packages. |
| </p> |
| <p> |
| The -u flag instructs get to use the network to update the named packages |
| and their dependencies. By default, get uses the network to check out |
| missing packages but does not use it to look for updates to existing packages. |
| </p> |
| <p> |
| The -v flag enables verbose progress and debug output. |
| </p> |
| <p> |
| Get also accepts build flags to control the installation. See 'go help build'. |
| </p> |
| <p> |
| When checking out a new package, get creates the target directory |
| GOPATH/src/<import-path>. If the GOPATH contains multiple entries, |
| get uses the first one. For more details see: 'go help gopath'. |
| </p> |
| <p> |
| When checking out or updating a package, get looks for a branch or tag |
| that matches the locally installed version of Go. The most important |
| rule is that if the local installation is running version "go1", get |
| searches for a branch or tag named "go1". If no such version exists it |
| retrieves the most recent version of the package. |
| </p> |
| <p> |
| When go get checks out or updates a Git repository, |
| it also updates any git submodules referenced by the repository. |
| </p> |
| <p> |
| Get never checks out or updates code stored in vendor directories. |
| </p> |
| <p> |
| For more about specifying packages, see 'go help packages'. |
| </p> |
| <p> |
| For more about how 'go get' finds source code to |
| download, see 'go help importpath'. |
| </p> |
| <p> |
| See also: go build, go install, go clean. |
| </p> |
| <h3 id="hdr-Compile_and_install_packages_and_dependencies">Compile and install packages and dependencies</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go install [build flags] [packages] |
| </pre> |
| <p> |
| Install compiles and installs the packages named by the import paths, |
| along with their dependencies. |
| </p> |
| <p> |
| For more about the build flags, see 'go help build'. |
| For more about specifying packages, see 'go help packages'. |
| </p> |
| <p> |
| See also: go build, go get, go clean. |
| </p> |
| <h3 id="hdr-List_packages">List packages</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go list [-e] [-f format] [-json] [build flags] [packages] |
| </pre> |
| <p> |
| List lists the packages named by the import paths, one per line. |
| </p> |
| <p> |
| The default output shows the package import path: |
| </p> |
| <pre>bytes |
| encoding/json |
| github.com/gorilla/mux |
| golang.org/x/net/html |
| </pre> |
| <p> |
| The -f flag specifies an alternate format for the list, using the |
| syntax of package template. The default output is equivalent to -f |
| ''. The struct being passed to the template is: |
| </p> |
| <pre>type Package struct { |
| Dir string // directory containing package sources |
| ImportPath string // import path of package in dir |
| ImportComment string // path in import comment on package statement |
| Name string // package name |
| Doc string // package documentation string |
| Target string // install path |
| Shlib string // the shared library that contains this package (only set when -linkshared) |
| Goroot bool // is this package in the Go root? |
| Standard bool // is this package part of the standard Go library? |
| Stale bool // would 'go install' do anything for this package? |
| StaleReason string // explanation for Stale==true |
| Root string // Go root or Go path dir containing this package |
| ConflictDir string // this directory shadows Dir in $GOPATH |
| BinaryOnly bool // binary-only package: cannot be recompiled from sources |
| |
| // Source files |
| GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles) |
| CgoFiles []string // .go sources files that import "C" |
| IgnoredGoFiles []string // .go sources ignored due to build constraints |
| CFiles []string // .c source files |
| CXXFiles []string // .cc, .cxx and .cpp source files |
| MFiles []string // .m source files |
| HFiles []string // .h, .hh, .hpp and .hxx source files |
| FFiles []string // .f, .F, .for and .f90 Fortran source files |
| SFiles []string // .s source files |
| SwigFiles []string // .swig files |
| SwigCXXFiles []string // .swigcxx files |
| SysoFiles []string // .syso object files to add to archive |
| TestGoFiles []string // _test.go files in package |
| XTestGoFiles []string // _test.go files outside package |
| |
| // Cgo directives |
| CgoCFLAGS []string // cgo: flags for C compiler |
| CgoCPPFLAGS []string // cgo: flags for C preprocessor |
| CgoCXXFLAGS []string // cgo: flags for C++ compiler |
| CgoFFLAGS []string // cgo: flags for Fortran compiler |
| CgoLDFLAGS []string // cgo: flags for linker |
| CgoPkgConfig []string // cgo: pkg-config names |
| |
| // Dependency information |
| Imports []string // import paths used by this package |
| Deps []string // all (recursively) imported dependencies |
| TestImports []string // imports from TestGoFiles |
| XTestImports []string // imports from XTestGoFiles |
| |
| // Error information |
| Incomplete bool // this package or a dependency has an error |
| Error *PackageError // error loading package |
| DepsErrors []*PackageError // errors loading dependencies |
| } |
| </pre> |
| <p> |
| Packages stored in vendor directories report an ImportPath that includes the |
| path to the vendor directory (for example, "d/vendor/p" instead of "p"), |
| so that the ImportPath uniquely identifies a given copy of a package. |
| The Imports, Deps, TestImports, and XTestImports lists also contain these |
| expanded imports paths. See golang.org/s/go15vendor for more about vendoring. |
| </p> |
| <p> |
| The error information, if any, is |
| </p> |
| <pre>type PackageError struct { |
| ImportStack []string // shortest path from package named on command line to this one |
| Pos string // position of error (if present, file:line:col) |
| Err string // the error itself |
| } |
| </pre> |
| <p> |
| The template function "join" calls strings.Join. |
| </p> |
| <p> |
| The template function "context" returns the build context, defined as: |
| </p> |
| <pre>type Context struct { |
| GOARCH string // target architecture |
| GOOS string // target operating system |
| GOROOT string // Go root |
| GOPATH string // Go path |
| CgoEnabled bool // whether cgo can be used |
| UseAllFiles bool // use files regardless of +build lines, file names |
| Compiler string // compiler to assume when computing target paths |
| BuildTags []string // build constraints to match in +build lines |
| ReleaseTags []string // releases the current release is compatible with |
| InstallSuffix string // suffix to use in the name of the install dir |
| } |
| </pre> |
| <p> |
| For more information about the meaning of these fields see the documentation |
| for the go/build package's Context type. |
| </p> |
| <p> |
| The -json flag causes the package data to be printed in JSON format |
| instead of using the template format. |
| </p> |
| <p> |
| The -e flag changes the handling of erroneous packages, those that |
| cannot be found or are malformed. By default, the list command |
| prints an error to standard error for each erroneous package and |
| omits the packages from consideration during the usual printing. |
| With the -e flag, the list command never prints errors to standard |
| error and instead processes the erroneous packages with the usual |
| printing. Erroneous packages will have a non-empty ImportPath and |
| a non-nil Error field; other information may or may not be missing |
| (zeroed). |
| </p> |
| <p> |
| For more about build flags, see 'go help build'. |
| </p> |
| <p> |
| For more about specifying packages, see 'go help packages'. |
| </p> |
| <h3 id="hdr-Compile_and_run_Go_program">Compile and run Go program</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go run [build flags] [-exec xprog] gofiles... [arguments...] |
| </pre> |
| <p> |
| Run compiles and runs the main package comprising the named Go source files. |
| A Go source file is defined to be a file ending in a literal ".go" suffix. |
| </p> |
| <p> |
| By default, 'go run' runs the compiled binary directly: 'a.out arguments...'. |
| If the -exec flag is given, 'go run' invokes the binary using xprog: |
| </p> |
| <pre>'xprog a.out arguments...'. |
| </pre> |
| <p> |
| If the -exec flag is not given, GOOS or GOARCH is different from the system |
| default, and a program named go_$GOOS_$GOARCH_exec can be found |
| on the current search path, 'go run' invokes the binary using that program, |
| for example 'go_nacl_386_exec a.out arguments...'. This allows execution of |
| cross-compiled programs when a simulator or other execution method is |
| available. |
| </p> |
| <p> |
| For more about build flags, see 'go help build'. |
| </p> |
| <p> |
| See also: go build. |
| </p> |
| <h3 id="hdr-Test_packages">Test packages</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go test [build/test flags] [packages] [build/test flags & test binary flags] |
| </pre> |
| <p> |
| 'Go test' automates testing the packages named by the import paths. |
| It prints a summary of the test results in the format: |
| </p> |
| <pre>ok archive/tar 0.011s |
| FAIL archive/zip 0.022s |
| ok compress/gzip 0.033s |
| ... |
| </pre> |
| <p> |
| followed by detailed output for each failed package. |
| </p> |
| <p> |
| 'Go test' recompiles each package along with any files with names matching |
| the file pattern "*_test.go". |
| Files whose names begin with "_" (including "_test.go") or "." are ignored. |
| These additional files can contain test functions, benchmark functions, and |
| example functions. See 'go help testfunc' for more. |
| Each listed package causes the execution of a separate test binary. |
| </p> |
| <p> |
| Test files that declare a package with the suffix "_test" will be compiled as a |
| separate package, and then linked and run with the main test binary. |
| </p> |
| <p> |
| The go tool will ignore a directory named "testdata", making it available |
| to hold ancillary data needed by the tests. |
| </p> |
| <p> |
| By default, go test needs no arguments. It compiles and tests the package |
| with source in the current directory, including tests, and runs the tests. |
| </p> |
| <p> |
| The package is built in a temporary directory so it does not interfere with the |
| non-test installation. |
| </p> |
| <p> |
| In addition to the build flags, the flags handled by 'go test' itself are: |
| </p> |
| <pre>-args |
| Pass the remainder of the command line (everything after -args) |
| to the test binary, uninterpreted and unchanged. |
| Because this flag consumes the remainder of the command line, |
| the package list (if present) must appear before this flag. |
| |
| -c |
| Compile the test binary to pkg.test but do not run it |
| (where pkg is the last element of the package's import path). |
| The file name can be changed with the -o flag. |
| |
| -exec xprog |
| Run the test binary using xprog. The behavior is the same as |
| in 'go run'. See 'go help run' for details. |
| |
| -i |
| Install packages that are dependencies of the test. |
| Do not run the test. |
| |
| -o file |
| Compile the test binary to the named file. |
| The test still runs (unless -c or -i is specified). |
| </pre> |
| <p> |
| The test binary also accepts flags that control execution of the test; these |
| flags are also accessible by 'go test'. See 'go help testflag' for details. |
| </p> |
| <p> |
| For more about build flags, see 'go help build'. |
| For more about specifying packages, see 'go help packages'. |
| </p> |
| <p> |
| See also: go build, go vet. |
| </p> |
| <h3 id="hdr-Run_specified_go_tool">Run specified go tool</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go tool [-n] command [args...] |
| </pre> |
| <p> |
| Tool runs the go tool command identified by the arguments. |
| With no arguments it prints the list of known tools. |
| </p> |
| <p> |
| The -n flag causes tool to print the command that would be |
| executed but not execute it. |
| </p> |
| <p> |
| For more about each tool command, see 'go tool command -h'. |
| </p> |
| <h3 id="hdr-Print_Go_version">Print Go version</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go version |
| </pre> |
| <p> |
| Version prints the Go version, as reported by runtime.Version. |
| </p> |
| <h3 id="hdr-Run_go_tool_vet_on_packages">Run go tool vet on packages</h3> |
| <p> |
| Usage: |
| </p> |
| <pre>go vet [-n] [-x] [build flags] [packages] |
| </pre> |
| <p> |
| Vet runs the Go vet command on the packages named by the import paths. |
| </p> |
| <p> |
| For more about vet, see 'go doc cmd/vet'. |
| For more about specifying packages, see 'go help packages'. |
| </p> |
| <p> |
| To run the vet tool with specific options, run 'go tool vet'. |
| </p> |
| <p> |
| The -n flag prints commands that would be executed. |
| The -x flag prints commands as they are executed. |
| </p> |
| <p> |
| For more about build flags, see 'go help build'. |
| </p> |
| <p> |
| See also: go fmt, go fix. |
| </p> |
| <h3 id="hdr-Calling_between_Go_and_C">Calling between Go and C</h3> |
| <p> |
| There are two different ways to call between Go and C/C++ code. |
| </p> |
| <p> |
| The first is the cgo tool, which is part of the Go distribution. For |
| information on how to use it see the cgo documentation (go doc cmd/cgo). |
| </p> |
| <p> |
| The second is the SWIG program, which is a general tool for |
| interfacing between languages. For information on SWIG see |
| <a href="http://swig.org/">http://swig.org/</a>. When running go build, any file with a .swig |
| extension will be passed to SWIG. Any file with a .swigcxx extension |
| will be passed to SWIG with the -c++ option. |
| </p> |
| <p> |
| When either cgo or SWIG is used, go build will pass any .c, .m, .s, |
| or .S files to the C compiler, and any .cc, .cpp, .cxx files to the C++ |
| compiler. The CC or CXX environment variables may be set to determine |
| the C or C++ compiler, respectively, to use. |
| </p> |
| <h3 id="hdr-Description_of_build_modes">Description of build modes</h3> |
| <p> |
| The 'go build' and 'go install' commands take a -buildmode argument which |
| indicates which kind of object file is to be built. Currently supported values |
| are: |
| </p> |
| <pre>-buildmode=archive |
| Build the listed non-main packages into .a files. Packages named |
| main are ignored. |
| |
| -buildmode=c-archive |
| Build the listed main package, plus all packages it imports, |
| into a C archive file. The only callable symbols will be those |
| functions exported using a cgo //export comment. Requires |
| exactly one main package to be listed. |
| |
| -buildmode=c-shared |
| Build the listed main packages, plus all packages that they |
| import, into C shared libraries. The only callable symbols will |
| be those functions exported using a cgo //export comment. |
| Non-main packages are ignored. |
| |
| -buildmode=default |
| Listed main packages are built into executables and listed |
| non-main packages are built into .a files (the default |
| behavior). |
| |
| -buildmode=shared |
| Combine all the listed non-main packages into a single shared |
| library that will be used when building with the -linkshared |
| option. Packages named main are ignored. |
| |
| -buildmode=exe |
| Build the listed main packages and everything they import into |
| executables. Packages not named main are ignored. |
| |
| -buildmode=pie |
| Build the listed main packages and everything they import into |
| position independent executables (PIE). Packages not named |
| main are ignored. |
| |
| -buildmode=plugin |
| Build the listed main packages, plus all packages that they |
| import, into a Go plugin. Packages not named main are ignored. |
| </pre> |
| <h3 id="hdr-File_types">File types</h3> |
| <p> |
| The go command examines the contents of a restricted set of files |
| in each directory. It identifies which files to examine based on |
| the extension of the file name. These extensions are: |
| </p> |
| <pre>.go |
| Go source files. |
| .c, .h |
| C source files. |
| If the package uses cgo or SWIG, these will be compiled with the |
| OS-native compiler (typically gcc); otherwise they will |
| trigger an error. |
| .cc, .cpp, .cxx, .hh, .hpp, .hxx |
| C++ source files. Only useful with cgo or SWIG, and always |
| compiled with the OS-native compiler. |
| .m |
| Objective-C source files. Only useful with cgo, and always |
| compiled with the OS-native compiler. |
| .s, .S |
| Assembler source files. |
| If the package uses cgo or SWIG, these will be assembled with the |
| OS-native assembler (typically gcc (sic)); otherwise they |
| will be assembled with the Go assembler. |
| .swig, .swigcxx |
| SWIG definition files. |
| .syso |
| System object files. |
| </pre> |
| <p> |
| Files of each of these types except .syso may contain build |
| constraints, but the go command stops scanning for build constraints |
| at the first item in the file that is not a blank line or //-style |
| line comment. See the go/build package documentation for |
| more details. |
| </p> |
| <p> |
| Non-test Go source files can also include a //go:binary-only-package |
| comment, indicating that the package sources are included |
| for documentation only and must not be used to build the |
| package binary. This enables distribution of Go packages in |
| their compiled form alone. See the go/build package documentation |
| for more details. |
| </p> |
| <h3 id="hdr-GOPATH_environment_variable">GOPATH environment variable</h3> |
| <p> |
| The Go path is used to resolve import statements. |
| It is implemented by and documented in the go/build package. |
| </p> |
| <p> |
| The GOPATH environment variable lists places to look for Go code. |
| On Unix, the value is a colon-separated string. |
| On Windows, the value is a semicolon-separated string. |
| On Plan 9, the value is a list. |
| </p> |
| <p> |
| If the environment variable is unset, GOPATH defaults |
| to a subdirectory named "go" in the user's home directory |
| ($HOME/go on Unix, %USERPROFILE%\go on Windows), |
| unless that directory holds a Go distribution. |
| Run "go env GOPATH" to see the current GOPATH. |
| </p> |
| <p> |
| See <a href="https://golang.org/wiki/SettingGOPATH">https://golang.org/wiki/SettingGOPATH</a> to set a custom GOPATH. |
| </p> |
| <p> |
| Each directory listed in GOPATH must have a prescribed structure: |
| </p> |
| <p> |
| The src directory holds source code. The path below src |
| determines the import path or executable name. |
| </p> |
| <p> |
| The pkg directory holds installed package objects. |
| As in the Go tree, each target operating system and |
| architecture pair has its own subdirectory of pkg |
| (pkg/GOOS_GOARCH). |
| </p> |
| <p> |
| If DIR is a directory listed in the GOPATH, a package with |
| source in DIR/src/foo/bar can be imported as "foo/bar" and |
| has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a". |
| </p> |
| <p> |
| The bin directory holds compiled commands. |
| Each command is named for its source directory, but only |
| the final element, not the entire path. That is, the |
| command with source in DIR/src/foo/quux is installed into |
| DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped |
| so that you can add DIR/bin to your PATH to get at the |
| installed commands. If the GOBIN environment variable is |
| set, commands are installed to the directory it names instead |
| of DIR/bin. GOBIN must be an absolute path. |
| </p> |
| <p> |
| Here's an example directory layout: |
| </p> |
| <pre>GOPATH=/home/user/go |
| |
| /home/user/go/ |
| src/ |
| foo/ |
| bar/ (go code in package bar) |
| x.go |
| quux/ (go code in package main) |
| y.go |
| bin/ |
| quux (installed command) |
| pkg/ |
| linux_amd64/ |
| foo/ |
| bar.a (installed package object) |
| </pre> |
| <p> |
| Go searches each directory listed in GOPATH to find source code, |
| but new packages are always downloaded into the first directory |
| in the list. |
| </p> |
| <p> |
| See <a href="https://golang.org/doc/code.html">https://golang.org/doc/code.html</a> for an example. |
| </p> |
| <h3 id="hdr-Internal_Directories">Internal Directories</h3> |
| <p> |
| Code in or below a directory named "internal" is importable only |
| by code in the directory tree rooted at the parent of "internal". |
| Here's an extended version of the directory layout above: |
| </p> |
| <pre>/home/user/go/ |
| src/ |
| crash/ |
| bang/ (go code in package bang) |
| b.go |
| foo/ (go code in package foo) |
| f.go |
| bar/ (go code in package bar) |
| x.go |
| internal/ |
| baz/ (go code in package baz) |
| z.go |
| quux/ (go code in package main) |
| y.go |
| </pre> |
| <p> |
| The code in z.go is imported as "foo/internal/baz", but that |
| import statement can only appear in source files in the subtree |
| rooted at foo. The source files foo/f.go, foo/bar/x.go, and |
| foo/quux/y.go can all import "foo/internal/baz", but the source file |
| crash/bang/b.go cannot. |
| </p> |
| <p> |
| See <a href="https://golang.org/s/go14internal">https://golang.org/s/go14internal</a> for details. |
| </p> |
| <h3 id="hdr-Vendor_Directories">Vendor Directories</h3> |
| <p> |
| Go 1.6 includes support for using local copies of external dependencies |
| to satisfy imports of those dependencies, often referred to as vendoring. |
| </p> |
| <p> |
| Code below a directory named "vendor" is importable only |
| by code in the directory tree rooted at the parent of "vendor", |
| and only using an import path that omits the prefix up to and |
| including the vendor element. |
| </p> |
| <p> |
| Here's the example from the previous section, |
| but with the "internal" directory renamed to "vendor" |
| and a new foo/vendor/crash/bang directory added: |
| </p> |
| <pre>/home/user/go/ |
| src/ |
| crash/ |
| bang/ (go code in package bang) |
| b.go |
| foo/ (go code in package foo) |
| f.go |
| bar/ (go code in package bar) |
| x.go |
| vendor/ |
| crash/ |
| bang/ (go code in package bang) |
| b.go |
| baz/ (go code in package baz) |
| z.go |
| quux/ (go code in package main) |
| y.go |
| </pre> |
| <p> |
| The same visibility rules apply as for internal, but the code |
| in z.go is imported as "baz", not as "foo/vendor/baz". |
| </p> |
| <p> |
| Code in vendor directories deeper in the source tree shadows |
| code in higher directories. Within the subtree rooted at foo, an import |
| of "crash/bang" resolves to "foo/vendor/crash/bang", not the |
| top-level "crash/bang". |
| </p> |
| <p> |
| Code in vendor directories is not subject to import path |
| checking (see 'go help importpath'). |
| </p> |
| <p> |
| When 'go get' checks out or updates a git repository, it now also |
| updates submodules. |
| </p> |
| <p> |
| Vendor directories do not affect the placement of new repositories |
| being checked out for the first time by 'go get': those are always |
| placed in the main GOPATH, never in a vendor subtree. |
| </p> |
| <p> |
| See <a href="https://golang.org/s/go15vendor">https://golang.org/s/go15vendor</a> for details. |
| </p> |
| <h3 id="hdr-Environment_variables">Environment variables</h3> |
| <p> |
| The go command, and the tools it invokes, examine a few different |
| environment variables. For many of these, you can see the default |
| value of on your system by running 'go env NAME', where NAME is the |
| name of the variable. |
| </p> |
| <p> |
| General-purpose environment variables: |
| </p> |
| <pre>GCCGO |
| The gccgo command to run for 'go build -compiler=gccgo'. |
| GOARCH |
| The architecture, or processor, for which to compile code. |
| Examples are amd64, 386, arm, ppc64. |
| GOBIN |
| The directory where 'go install' will install a command. |
| GOOS |
| The operating system for which to compile code. |
| Examples are linux, darwin, windows, netbsd. |
| GOPATH |
| For more details see: 'go help gopath'. |
| GORACE |
| Options for the race detector. |
| See <a href="https://golang.org/doc/articles/race_detector.html">https://golang.org/doc/articles/race_detector.html</a>. |
| GOROOT |
| The root of the go tree. |
| </pre> |
| <p> |
| Environment variables for use with cgo: |
| </p> |
| <pre>CC |
| The command to use to compile C code. |
| CGO_ENABLED |
| Whether the cgo command is supported. Either 0 or 1. |
| CGO_CFLAGS |
| Flags that cgo will pass to the compiler when compiling |
| C code. |
| CGO_CPPFLAGS |
| Flags that cgo will pass to the compiler when compiling |
| C or C++ code. |
| CGO_CXXFLAGS |
| Flags that cgo will pass to the compiler when compiling |
| C++ code. |
| CGO_FFLAGS |
| Flags that cgo will pass to the compiler when compiling |
| Fortran code. |
| CGO_LDFLAGS |
| Flags that cgo will pass to the compiler when linking. |
| CXX |
| The command to use to compile C++ code. |
| PKG_CONFIG |
| Path to pkg-config tool. |
| </pre> |
| <p> |
| Architecture-specific environment variables: |
| </p> |
| <pre>GOARM |
| For GOARCH=arm, the ARM architecture for which to compile. |
| Valid values are 5, 6, 7. |
| GO386 |
| For GOARCH=386, the floating point instruction set. |
| Valid values are 387, sse2. |
| </pre> |
| <p> |
| Special-purpose environment variables: |
| </p> |
| <pre>GOROOT_FINAL |
| The root of the installed Go tree, when it is |
| installed in a location other than where it is built. |
| File names in stack traces are rewritten from GOROOT to |
| GOROOT_FINAL. |
| GO_EXTLINK_ENABLED |
| Whether the linker should use external linking mode |
| when using -linkmode=auto with code that uses cgo. |
| Set to 0 to disable external linking mode, 1 to enable it. |
| GIT_ALLOW_PROTOCOL |
| Defined by Git. A colon-separated list of schemes that are allowed to be used |
| with git fetch/clone. If set, any scheme not explicitly mentioned will be |
| considered insecure by 'go get'. |
| </pre> |
| <h3 id="hdr-Import_path_syntax">Import path syntax</h3> |
| <p> |
| An import path (see 'go help packages') denotes a package stored in the local |
| file system. In general, an import path denotes either a standard package (such |
| as "unicode/utf8") or a package found in one of the work spaces (For more |
| details see: 'go help gopath'). |
| </p> |
| <h3 id="hdr-Relative_import_paths">Relative import paths</h3> |
| <p> |
| An import path beginning with ./ or ../ is called a relative path. |
| The toolchain supports relative import paths as a shortcut in two ways. |
| </p> |
| <p> |
| First, a relative path can be used as a shorthand on the command line. |
| If you are working in the directory containing the code imported as |
| "unicode" and want to run the tests for "unicode/utf8", you can type |
| "go test ./utf8" instead of needing to specify the full path. |
| Similarly, in the reverse situation, "go test .." will test "unicode" from |
| the "unicode/utf8" directory. Relative patterns are also allowed, like |
| "go test ./..." to test all subdirectories. See 'go help packages' for details |
| on the pattern syntax. |
| </p> |
| <p> |
| Second, if you are compiling a Go program not in a work space, |
| you can use a relative path in an import statement in that program |
| to refer to nearby code also not in a work space. |
| This makes it easy to experiment with small multipackage programs |
| outside of the usual work spaces, but such programs cannot be |
| installed with "go install" (there is no work space in which to install them), |
| so they are rebuilt from scratch each time they are built. |
| To avoid ambiguity, Go programs cannot use relative import paths |
| within a work space. |
| </p> |
| <h3 id="hdr-Remote_import_paths">Remote import paths</h3> |
| <p> |
| Certain import paths also |
| describe how to obtain the source code for the package using |
| a revision control system. |
| </p> |
| <p> |
| A few common code hosting sites have special syntax: |
| </p> |
| <pre>Bitbucket (Git, Mercurial) |
| |
| import "bitbucket.org/user/project" |
| import "bitbucket.org/user/project/sub/directory" |
| |
| GitHub (Git) |
| |
| import "github.com/user/project" |
| import "github.com/user/project/sub/directory" |
| |
| Launchpad (Bazaar) |
| |
| import "launchpad.net/project" |
| import "launchpad.net/project/series" |
| import "launchpad.net/project/series/sub/directory" |
| |
| import "launchpad.net/~user/project/branch" |
| import "launchpad.net/~user/project/branch/sub/directory" |
| |
| IBM DevOps Services (Git) |
| |
| import "hub.jazz.net/git/user/project" |
| import "hub.jazz.net/git/user/project/sub/directory" |
| </pre> |
| <p> |
| For code hosted on other servers, import paths may either be qualified |
| with the version control type, or the go tool can dynamically fetch |
| the import path over https/http and discover where the code resides |
| from a <meta> tag in the HTML. |
| </p> |
| <p> |
| To declare the code location, an import path of the form |
| </p> |
| <pre>repository.vcs/path |
| </pre> |
| <p> |
| specifies the given repository, with or without the .vcs suffix, |
| using the named version control system, and then the path inside |
| that repository. The supported version control systems are: |
| </p> |
| <pre>Bazaar .bzr |
| Git .git |
| Mercurial .hg |
| Subversion .svn |
| </pre> |
| <p> |
| For example, |
| </p> |
| <pre>import "example.org/user/foo.hg" |
| </pre> |
| <p> |
| denotes the root directory of the Mercurial repository at |
| example.org/user/foo or foo.hg, and |
| </p> |
| <pre>import "example.org/repo.git/foo/bar" |
| </pre> |
| <p> |
| denotes the foo/bar directory of the Git repository at |
| example.org/repo or repo.git. |
| </p> |
| <p> |
| When a version control system supports multiple protocols, |
| each is tried in turn when downloading. For example, a Git |
| download tries https://, then git+ssh://. |
| </p> |
| <p> |
| By default, downloads are restricted to known secure protocols |
| (e.g. https, ssh). To override this setting for Git downloads, the |
| GIT_ALLOW_PROTOCOL environment variable can be set (For more details see: |
| 'go help environment'). |
| </p> |
| <p> |
| If the import path is not a known code hosting site and also lacks a |
| version control qualifier, the go tool attempts to fetch the import |
| over https/http and looks for a <meta> tag in the document's HTML |
| <head>. |
| </p> |
| <p> |
| The meta tag has the form: |
| </p> |
| <pre><meta name="go-import" content="import-prefix vcs repo-root"> |
| </pre> |
| <p> |
| The import-prefix is the import path corresponding to the repository |
| root. It must be a prefix or an exact match of the package being |
| fetched with "go get". If it's not an exact match, another http |
| request is made at the prefix to verify the <meta> tags match. |
| </p> |
| <p> |
| The meta tag should appear as early in the file as possible. |
| In particular, it should appear before any raw JavaScript or CSS, |
| to avoid confusing the go command's restricted parser. |
| </p> |
| <p> |
| The vcs is one of "git", "hg", "svn", etc, |
| </p> |
| <p> |
| The repo-root is the root of the version control system |
| containing a scheme and not containing a .vcs qualifier. |
| </p> |
| <p> |
| For example, |
| </p> |
| <pre>import "example.org/pkg/foo" |
| </pre> |
| <p> |
| will result in the following requests: |
| </p> |
| <pre><a href="https://example.org/pkg/foo?go-get=1">https://example.org/pkg/foo?go-get=1</a> (preferred) |
| <a href="http://example.org/pkg/foo?go-get=1">http://example.org/pkg/foo?go-get=1</a> (fallback, only with -insecure) |
| </pre> |
| <p> |
| If that page contains the meta tag |
| </p> |
| <pre><meta name="go-import" content="example.org git <a href="https://code.org/r/p/exproj">https://code.org/r/p/exproj</a>"> |
| </pre> |
| <p> |
| the go tool will verify that <a href="https://example.org/?go-get=1">https://example.org/?go-get=1</a> contains the |
| same meta tag and then git clone <a href="https://code.org/r/p/exproj">https://code.org/r/p/exproj</a> into |
| GOPATH/src/example.org. |
| </p> |
| <p> |
| New downloaded packages are written to the first directory listed in the GOPATH |
| environment variable (For more details see: 'go help gopath'). |
| </p> |
| <p> |
| The go command attempts to download the version of the |
| package appropriate for the Go release being used. |
| Run 'go help get' for more. |
| </p> |
| <h3 id="hdr-Import_path_checking">Import path checking</h3> |
| <p> |
| When the custom import path feature described above redirects to a |
| known code hosting site, each of the resulting packages has two possible |
| import paths, using the custom domain or the known hosting site. |
| </p> |
| <p> |
| A package statement is said to have an "import comment" if it is immediately |
| followed (before the next newline) by a comment of one of these two forms: |
| </p> |
| <pre>package math // import "path" |
| package math /* import "path" */ |
| </pre> |
| <p> |
| The go command will refuse to install a package with an import comment |
| unless it is being referred to by that import path. In this way, import comments |
| let package authors make sure the custom import path is used and not a |
| direct path to the underlying code hosting site. |
| </p> |
| <p> |
| Import path checking is disabled for code found within vendor trees. |
| This makes it possible to copy code into alternate locations in vendor trees |
| without needing to update import comments. |
| </p> |
| <p> |
| See <a href="https://golang.org/s/go14customimport">https://golang.org/s/go14customimport</a> for details. |
| </p> |
| <h3 id="hdr-Description_of_package_lists">Description of package lists</h3> |
| <p> |
| Many commands apply to a set of packages: |
| </p> |
| <pre>go action [packages] |
| </pre> |
| <p> |
| Usually, [packages] is a list of import paths. |
| </p> |
| <p> |
| An import path that is a rooted path or that begins with |
| a . or .. element is interpreted as a file system path and |
| denotes the package in that directory. |
| </p> |
| <p> |
| Otherwise, the import path P denotes the package found in |
| the directory DIR/src/P for some DIR listed in the GOPATH |
| environment variable (For more details see: 'go help gopath'). |
| </p> |
| <p> |
| If no import paths are given, the action applies to the |
| package in the current directory. |
| </p> |
| <p> |
| There are four reserved names for paths that should not be used |
| for packages to be built with the go tool: |
| </p> |
| <p> |
| - "main" denotes the top-level package in a stand-alone executable. |
| </p> |
| <p> |
| - "all" expands to all package directories found in all the GOPATH |
| trees. For example, 'go list all' lists all the packages on the local |
| system. |
| </p> |
| <p> |
| - "std" is like all but expands to just the packages in the standard |
| Go library. |
| </p> |
| <p> |
| - "cmd" expands to the Go repository's commands and their |
| internal libraries. |
| </p> |
| <p> |
| Import paths beginning with "cmd/" only match source code in |
| the Go repository. |
| </p> |
| <p> |
| An import path is a pattern if it includes one or more "..." wildcards, |
| each of which can match any string, including the empty string and |
| strings containing slashes. Such a pattern expands to all package |
| directories found in the GOPATH trees with names matching the |
| patterns. As a special case, x/... matches x as well as x's subdirectories. |
| For example, net/... expands to net and packages in its subdirectories. |
| </p> |
| <p> |
| An import path can also name a package to be downloaded from |
| a remote repository. Run 'go help importpath' for details. |
| </p> |
| <p> |
| Every package in a program must have a unique import path. |
| By convention, this is arranged by starting each path with a |
| unique prefix that belongs to you. For example, paths used |
| internally at Google all begin with 'google', and paths |
| denoting remote repositories begin with the path to the code, |
| such as 'github.com/user/repo'. |
| </p> |
| <p> |
| Packages in a program need not have unique package names, |
| but there are two reserved package names with special meaning. |
| The name main indicates a command, not a library. |
| Commands are built into binaries and cannot be imported. |
| The name documentation indicates documentation for |
| a non-Go program in the directory. Files in package documentation |
| are ignored by the go command. |
| </p> |
| <p> |
| As a special case, if the package list is a list of .go files from a |
| single directory, the command is applied to a single synthesized |
| package made up of exactly those files, ignoring any build constraints |
| in those files and ignoring any other files in the directory. |
| </p> |
| <p> |
| Directory and file names that begin with "." or "_" are ignored |
| by the go tool, as are directories named "testdata". |
| </p> |
| <h3 id="hdr-Description_of_testing_flags">Description of testing flags</h3> |
| <p> |
| The 'go test' command takes both flags that apply to 'go test' itself |
| and flags that apply to the resulting test binary. |
| </p> |
| <p> |
| Several of the flags control profiling and write an execution profile |
| suitable for "go tool pprof"; run "go tool pprof -h" for more |
| information. The --alloc_space, --alloc_objects, and --show_bytes |
| options of pprof control how the information is presented. |
| </p> |
| <p> |
| The following flags are recognized by the 'go test' command and |
| control the execution of any test: |
| </p> |
| <pre>-bench regexp |
| Run (sub)benchmarks matching a regular expression. |
| The given regular expression is split into smaller ones by |
| top-level '/', where each must match the corresponding part of a |
| benchmark's identifier. |
| By default, no benchmarks run. To run all benchmarks, |
| use '-bench .' or '-bench=.'. |
| |
| -benchtime t |
| Run enough iterations of each benchmark to take t, specified |
| as a time.Duration (for example, -benchtime 1h30s). |
| The default is 1 second (1s). |
| |
| -count n |
| Run each test and benchmark n times (default 1). |
| If -cpu is set, run n times for each GOMAXPROCS value. |
| Examples are always run once. |
| |
| -cover |
| Enable coverage analysis. |
| |
| -covermode set,count,atomic |
| Set the mode for coverage analysis for the package[s] |
| being tested. The default is "set" unless -race is enabled, |
| in which case it is "atomic". |
| The values: |
| set: bool: does this statement run? |
| count: int: how many times does this statement run? |
| atomic: int: count, but correct in multithreaded tests; |
| significantly more expensive. |
| Sets -cover. |
| |
| -coverpkg pkg1,pkg2,pkg3 |
| Apply coverage analysis in each test to the given list of packages. |
| The default is for each test to analyze only the package being tested. |
| Packages are specified as import paths. |
| Sets -cover. |
| |
| -cpu 1,2,4 |
| Specify a list of GOMAXPROCS values for which the tests or |
| benchmarks should be executed. The default is the current value |
| of GOMAXPROCS. |
| |
| -parallel n |
| Allow parallel execution of test functions that call t.Parallel. |
| The value of this flag is the maximum number of tests to run |
| simultaneously; by default, it is set to the value of GOMAXPROCS. |
| Note that -parallel only applies within a single test binary. |
| The 'go test' command may run tests for different packages |
| in parallel as well, according to the setting of the -p flag |
| (see 'go help build'). |
| |
| -run regexp |
| Run only those tests and examples matching the regular expression. |
| For tests the regular expression is split into smaller ones by |
| top-level '/', where each must match the corresponding part of a |
| test's identifier. |
| |
| -short |
| Tell long-running tests to shorten their run time. |
| It is off by default but set during all.bash so that installing |
| the Go tree can run a sanity check but not spend time running |
| exhaustive tests. |
| |
| -timeout t |
| If a test runs longer than t, panic. |
| The default is 10 minutes (10m). |
| |
| -v |
| Verbose output: log all tests as they are run. Also print all |
| text from Log and Logf calls even if the test succeeds. |
| </pre> |
| <p> |
| The following flags are also recognized by 'go test' and can be used to |
| profile the tests during execution: |
| </p> |
| <pre>-benchmem |
| Print memory allocation statistics for benchmarks. |
| |
| -blockprofile block.out |
| Write a goroutine blocking profile to the specified file |
| when all tests are complete. |
| Writes test binary as -c would. |
| |
| -blockprofilerate n |
| Control the detail provided in goroutine blocking profiles by |
| calling runtime.SetBlockProfileRate with n. |
| See 'go doc runtime.SetBlockProfileRate'. |
| The profiler aims to sample, on average, one blocking event every |
| n nanoseconds the program spends blocked. By default, |
| if -test.blockprofile is set without this flag, all blocking events |
| are recorded, equivalent to -test.blockprofilerate=1. |
| |
| -coverprofile cover.out |
| Write a coverage profile to the file after all tests have passed. |
| Sets -cover. |
| |
| -cpuprofile cpu.out |
| Write a CPU profile to the specified file before exiting. |
| Writes test binary as -c would. |
| |
| -memprofile mem.out |
| Write a memory profile to the file after all tests have passed. |
| Writes test binary as -c would. |
| |
| -memprofilerate n |
| Enable more precise (and expensive) memory profiles by setting |
| runtime.MemProfileRate. See 'go doc runtime.MemProfileRate'. |
| To profile all memory allocations, use -test.memprofilerate=1 |
| and pass --alloc_space flag to the pprof tool. |
| |
| -mutexprofile mutex.out |
| Write a mutex contention profile to the specified file |
| when all tests are complete. |
| Writes test binary as -c would. |
| |
| -mutexprofilefraction n |
| Sample 1 in n stack traces of goroutines holding a |
| contended mutex. |
| |
| -outputdir directory |
| Place output files from profiling in the specified directory, |
| by default the directory in which "go test" is running. |
| |
| -trace trace.out |
| Write an execution trace to the specified file before exiting. |
| </pre> |
| <p> |
| Each of these flags is also recognized with an optional 'test.' prefix, |
| as in -test.v. When invoking the generated test binary (the result of |
| 'go test -c') directly, however, the prefix is mandatory. |
| </p> |
| <p> |
| The 'go test' command rewrites or removes recognized flags, |
| as appropriate, both before and after the optional package list, |
| before invoking the test binary. |
| </p> |
| <p> |
| For instance, the command |
| </p> |
| <pre>go test -v -myflag testdata -cpuprofile=prof.out -x |
| </pre> |
| <p> |
| will compile the test binary and then run it as |
| </p> |
| <pre>pkg.test -test.v -myflag testdata -test.cpuprofile=prof.out |
| </pre> |
| <p> |
| (The -x flag is removed because it applies only to the go command's |
| execution, not to the test itself.) |
| </p> |
| <p> |
| The test flags that generate profiles (other than for coverage) also |
| leave the test binary in pkg.test for use when analyzing the profiles. |
| </p> |
| <p> |
| When 'go test' runs a test binary, it does so from within the |
| corresponding package's source code directory. Depending on the test, |
| it may be necessary to do the same when invoking a generated test |
| binary directly. |
| </p> |
| <p> |
| The command-line package list, if present, must appear before any |
| flag not known to the go test command. Continuing the example above, |
| the package list would have to appear before -myflag, but could appear |
| on either side of -v. |
| </p> |
| <p> |
| To keep an argument for a test binary from being interpreted as a |
| known flag or a package name, use -args (see 'go help test') which |
| passes the remainder of the command line through to the test binary |
| uninterpreted and unaltered. |
| </p> |
| <p> |
| For instance, the command |
| </p> |
| <pre>go test -v -args -x -v |
| </pre> |
| <p> |
| will compile the test binary and then run it as |
| </p> |
| <pre>pkg.test -test.v -x -v |
| </pre> |
| <p> |
| Similarly, |
| </p> |
| <pre>go test -args math |
| </pre> |
| <p> |
| will compile the test binary and then run it as |
| </p> |
| <pre>pkg.test math |
| </pre> |
| <p> |
| In the first example, the -x and the second -v are passed through to the |
| test binary unchanged and with no effect on the go command itself. |
| In the second example, the argument math is passed through to the test |
| binary, instead of being interpreted as the package list. |
| </p> |
| <h3 id="hdr-Description_of_testing_functions">Description of testing functions</h3> |
| <p> |
| The 'go test' command expects to find test, benchmark, and example functions |
| in the "*_test.go" files corresponding to the package under test. |
| </p> |
| <p> |
| A test function is one named TestXXX (where XXX is any alphanumeric string |
| not starting with a lower case letter) and should have the signature, |
| </p> |
| <pre>func TestXXX(t *testing.T) { ... } |
| </pre> |
| <p> |
| A benchmark function is one named BenchmarkXXX and should have the signature, |
| </p> |
| <pre>func BenchmarkXXX(b *testing.B) { ... } |
| </pre> |
| <p> |
| An example function is similar to a test function but, instead of using |
| *testing.T to report success or failure, prints output to os.Stdout. |
| If the last comment in the function starts with "Output:" then the output |
| is compared exactly against the comment (see examples below). If the last |
| comment begins with "Unordered output:" then the output is compared to the |
| comment, however the order of the lines is ignored. An example with no such |
| comment is compiled but not executed. An example with no text after |
| "Output:" is compiled, executed, and expected to produce no output. |
| </p> |
| <p> |
| Godoc displays the body of ExampleXXX to demonstrate the use |
| of the function, constant, or variable XXX. An example of a method M with |
| receiver type T or *T is named ExampleT_M. There may be multiple examples |
| for a given function, constant, or variable, distinguished by a trailing _xxx, |
| where xxx is a suffix not beginning with an upper case letter. |
| </p> |
| <p> |
| Here is an example of an example: |
| </p> |
| <pre>func ExamplePrintln() { |
| Println("The output of\nthis example.") |
| // Output: The output of |
| // this example. |
| } |
| </pre> |
| <p> |
| Here is another example where the ordering of the output is ignored: |
| </p> |
| <pre>func ExamplePerm() { |
| for _, value := range Perm(4) { |
| fmt.Println(value) |
| } |
| |
| // Unordered output: 4 |
| // 2 |
| // 1 |
| // 3 |
| // 0 |
| } |
| </pre> |
| <p> |
| The entire test file is presented as the example when it contains a single |
| example function, at least one other function, type, variable, or constant |
| declaration, and no test or benchmark functions. |
| </p> |
| <p> |
| See the documentation of the testing package for more information. |
| </p> |
| |
| <div id="footer"> |
| Build version go1.8.<br> |
| Except as <a href="https://developers.google.com/site-policies#restrictions">noted</a>, |
| the content of this page is licensed under the |
| Creative Commons Attribution 3.0 License, |
| and code is licensed under a <a href="/LICENSE">BSD license</a>.<br> |
| <a href="/doc/tos.html">Terms of Service</a> | |
| <a href="http://www.google.com/intl/en/policies/privacy/">Privacy Policy</a> |
| </div> |
| |
| </div><!-- .container --> |
| </div><!-- #page --> |
| |
| <!-- TODO(adonovan): load these from <head> using "defer" attribute? --> |
| <script type="text/javascript" src="/serverpush/static/jquery.min.js?{{.CacheBust}}"></script> |
| <script type="text/javascript" src="/serverpush/static/playground.js?{{.CacheBust}}"></script> |
| <script>var goVersion = "go1.8";</script> |
| <script type="text/javascript" src="/serverpush/static/godocs.js?{{.CacheBust}}"></script> |
| </body> |
| </html> |
| `)) |