diff options
Diffstat (limited to 'src/cmd/go/doc.go')
| -rw-r--r-- | src/cmd/go/doc.go | 143 |
1 files changed, 93 insertions, 50 deletions
diff --git a/src/cmd/go/doc.go b/src/cmd/go/doc.go index 5e7b10692..0297b7602 100644 --- a/src/cmd/go/doc.go +++ b/src/cmd/go/doc.go @@ -76,7 +76,12 @@ The build flags are shared by the build, install, run, and test commands: do not delete it when exiting. -x print the commands. + -race + enable data race detection. + Supported only on linux/amd64, darwin/amd64 and windows/amd64. + -ccflags 'arg list' + arguments to pass on each 5c, 6c, or 8c compiler invocation -compiler name name of compiler to use, as in runtime.Compiler (gccgo or gc) -gccgoflags 'arg list' @@ -90,6 +95,9 @@ The build flags are shared by the build, install, run, and test commands: See the documentation for the go/build package for more information about build tags. +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. + For more about specifying packages, see 'go help packages'. For more about where packages and binaries are installed, see 'go help gopath'. @@ -121,6 +129,7 @@ source directories corresponding to the import paths: DIR(.exe) from go build DIR.test(.exe) from go test -c MAINFILE(.exe) from go build MAINFILE.go + *.so from SWIG In the list, DIR represents the final path element of the directory, and MAINFILE is the base name of any Go source @@ -215,14 +224,11 @@ Download and install packages and dependencies Usage: - go get [-a] [-d] [-fix] [-n] [-p n] [-u] [-v] [-x] [packages] + go get [-d] [-fix] [-u] [build flags] [packages] Get downloads and installs the packages named by the import paths, along with their dependencies. -The -a, -n, -v, -x, and -p flags have the same meaning as in 'go build' -and 'go install'. See 'go help build'. - The -d flag instructs get to stop after downloading the packages; that is, it instructs get not to install the packages. @@ -233,6 +239,9 @@ 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. +Get also accepts all the flags in the 'go build' and 'go install' commands, +to control the installation. See 'go help build'. + 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 @@ -266,7 +275,7 @@ List packages Usage: - go list [-e] [-f format] [-json] [packages] + go list [-e] [-f format] [-json] [-tags 'tag list'] [packages] List lists the packages named by the import paths, one per line. @@ -276,10 +285,10 @@ The default output shows the package import path: code.google.com/p/goauth2/oauth code.google.com/p/sqlite -The -f flag specifies an alternate format for the list, -using the syntax of package template. The default output -is equivalent to -f '{{.ImportPath}}'. The struct -being passed to the template is: +The -f flag specifies an alternate format for the list, using the +syntax of package template. The default output is equivalent to -f +'{{.ImportPath}}'. One extra template function is available, "join", +which calls strings.Join. The struct being passed to the template is: type Package struct { Dir string // directory containing package sources @@ -293,12 +302,15 @@ being passed to the template is: Root string // Go root or Go path dir containing this package // Source files - GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles) - CgoFiles []string // .go sources files that import "C" - CFiles []string // .c source files - HFiles []string // .h source files - SFiles []string // .s source files - SysoFiles []string // .syso object files to add to archive + 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 + HFiles []string // .h source files + SFiles []string // .s source files + SysoFiles []string // .syso object files to add to archive + SwigFiles []string // .swig files + SwigCXXFiles []string // .swigcxx files // Cgo directives CgoCFLAGS []string // cgo: flags for C compiler @@ -333,6 +345,9 @@ printing. Erroneous packages will have a non-empty ImportPath and a non-nil Error field; other information may or may not be missing (zeroed). +The -tags flag specifies a list of build tags, like in the 'go build' +command. + For more about specifying packages, see 'go help packages'. @@ -368,6 +383,7 @@ followed by detailed output for each failed package. 'Go test' recompiles each package along with any files with names matching the file pattern "*_test.go". 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. 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. @@ -445,7 +461,7 @@ 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. -GOPATH must be set to build and install packages outside the +GOPATH must be set to get, build and install packages outside the standard Go tree. Each directory listed in GOPATH must have a prescribed structure: @@ -491,7 +507,7 @@ Here's an example directory layout: bar.a (installed package object) Go searches each directory listed in GOPATH to find source code, -but new packages are always downloaded into the first directory +but new packages are always downloaded into the first directory in the list. @@ -509,13 +525,13 @@ denotes the package in that directory. Otherwise, the import path P denotes the package found in the directory DIR/src/P for some DIR listed in the GOPATH -environment variable (see 'go help gopath'). +environment variable (see 'go help gopath'). If no import paths are given, the action applies to the package in the current directory. The special import path "all" expands to all package directories -found in all the GOPATH trees. For example, 'go list all' +found in all the GOPATH trees. For example, 'go list all' lists all the packages on the local system. The special import path "std" is like all but expands to just the @@ -623,7 +639,7 @@ The meta tag has the form: <meta name="go-import" content="import-prefix vcs repo-root"> -The import-prefix is the import path correponding to the repository +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. @@ -663,28 +679,47 @@ Description of testing flags The 'go test' command takes both flags that apply to 'go test' itself and flags that apply to the resulting test binary. -The test binary, called pkg.test, where pkg is the name of the -directory containing the package sources, has its own flags: - - -test.v - Verbose output: log all tests as they are run. +The following flags are recognized by the 'go test' command and +control the execution of any test: - -test.run pattern - Run only those tests and examples matching the regular - expression. - - -test.bench pattern + -bench regexp Run benchmarks matching the regular expression. - By default, no benchmarks run. + By default, no benchmarks run. To run all benchmarks, + use '-bench .' or '-bench=.'. + + -benchmem + Print memory allocation statistics for benchmarks. + + -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). + + -blockprofile block.out + Write a goroutine blocking profile to the specified file + when all tests are complete. + + -blockprofilerate n + Control the detail provided in goroutine blocking profiles by setting + runtime.BlockProfileRate to n. See 'godoc runtime BlockProfileRate'. + 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. + + -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. - -test.cpuprofile cpu.out + -cpuprofile cpu.out Write a CPU profile to the specified file before exiting. - -test.memprofile mem.out + -memprofile mem.out Write a memory profile to the specified file when all tests are complete. - -test.memprofilerate n + -memprofilerate n Enable more precise (and expensive) memory profiles by setting runtime.MemProfileRate. See 'godoc runtime MemProfileRate'. To profile all memory allocations, use -test.memprofilerate=1 @@ -692,32 +727,35 @@ directory containing the package sources, has its own flags: garbage collector, provided the test can run in the available memory without garbage collection. - -test.parallel n + -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. - -test.short + -run regexp + Run only those tests and examples matching the regular + expression. + + -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. - -test.timeout t + -timeout t If a test runs longer than t, panic. - -test.benchtime n - Run enough iterations of each benchmark to take n seconds. - The default is 1 second. + -v + Verbose output: log all tests as they are run. - -test.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. +The test binary, called pkg.test where pkg is the name of the +directory containing the package sources, can be invoked directly +after building it with 'go test -c'. When invoking the test binary +directly, each of the standard flag names must be prefixed with 'test.', +as in -test.run=TestMyFunc or -test.v. -For convenience, each of these -test.X flags of the test binary is -also available as the flag -X in 'go test' itself. Flags not listed -here are passed through unaltered. For instance, the command +When running 'go test', flags not listed above are passed through +unaltered. For instance, the command go test -x -v -cpuprofile=prof.out -dir=testdata -update @@ -725,6 +763,11 @@ will compile the test binary and then run it as pkg.test -test.v -test.cpuprofile=prof.out -dir=testdata -update +The test flags that generate profiles also leave the test binary in pkg.test +for use when analyzing the profiles. + +Flags not recognized by 'go test' must be placed after any specified packages. + Description of testing functions @@ -740,8 +783,8 @@ A benchmark function is one named BenchmarkXXX and should have the signature, func BenchmarkXXX(b *testing.B) { ... } -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 and os.Stderr. +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. That output is compared against the function's "Output:" comment, which must be the last comment in the function body (see example below). An example with no such comment, or with no text after "Output:" is compiled @@ -769,6 +812,6 @@ See the documentation of the testing package for more information. */ -package documentation +package main // NOTE: cmdDoc is in fmt.go. |