1992 lines
67 KiB
Go
1992 lines
67 KiB
Go
// 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.
|
|
|
|
// +build h2demo
|
|
|
|
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="http://{{.HTTPHost}}/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>
|
|
`))
|