From 0133b5df6095669bf22eda5e8d74087f036b39f8 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Tue, 9 Jan 2018 16:31:12 -0500 Subject: [PATCH] cmd/go: add go help cache Change-Id: I14eeda85f279d1082ea9f2ac590b848ac13b1daa Reviewed-on: https://go-review.googlesource.com/87023 Run-TryBot: Russ Cox TryBot-Result: Gobot Gobot Reviewed-by: Rob Pike --- src/cmd/go/alldocs.go | 56 ++++++++++++++++++++++++----- src/cmd/go/internal/help/helpdoc.go | 46 ++++++++++++++++++++++-- src/cmd/go/internal/test/test.go | 4 +-- src/cmd/go/main.go | 1 + 4 files changed, 95 insertions(+), 12 deletions(-) diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index 48a414bf85..0dc72abbc8 100644 --- a/src/cmd/go/alldocs.go +++ b/src/cmd/go/alldocs.go @@ -35,14 +35,15 @@ // Additional help topics: // // c calling between Go and C -// buildmode description of build modes +// buildmode build modes +// cache build and test caching // 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 +// packages package lists +// testflag testing flags +// testfunc testing functions // // Use "go help [topic]" for more information about that topic. // @@ -902,7 +903,7 @@ // the C or C++ compiler, respectively, to use. // // -// Description of build modes +// Build modes // // 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 @@ -948,6 +949,45 @@ // import, into a Go plugin. Packages not named main are ignored. // // +// Build and test caching +// +// The go command caches build outputs for reuse in future builds. +// The default location for cache data is a subdirectory named go-build +// in the standard user cache directory for the current operating system. +// Setting the GOCACHE environment variable overrides this default, +// and running 'go env GOCACHE' prints the current cache directory. +// +// The go command periodically deletes cached data that has not been +// used recently. Running 'go clean -cache' deletes all cached data. +// +// The build cache correctly accounts for changes to Go source files, +// compilers, compiler options, and so on: cleaning the cache explicitly +// should not be necessary in typical use. However, the build cache +// does not detect changes to C libraries imported with cgo. +// If you have made changes to the C libraries on your system, you +// will need to clean the cache explicitly or else use the -a build flag +// (see 'go help build') to force rebuilding of packages that +// depend on the updated C libraries. +// +// The go command also caches successful package test results. +// See 'go help test' for details. Running 'go clean -testcache' removes +// all cached test results (but not cached build results). +// +// The GODEBUG environment variable can enable printing of debugging +// information about the state of the cache: +// +// GODEBUG=gocacheverify=1 causes the go command to bypass the +// use of any cache entries and instead rebuild everything and check +// that the results match existing cache entries. +// +// GODEBUG=gocachehash=1 causes the go command to print the inputs +// for all of the content hashes it uses to construct cache lookup keys. +// The output is voluminous but can be useful for debugging the cache. +// +// GODEBUG=gocachetest=1 causes the go command to print details of its +// decisions about whether to reuse a cached test result. +// +// // File types // // The go command examines the contents of a restricted set of files @@ -1402,7 +1442,7 @@ // See https://golang.org/s/go14customimport for details. // // -// Description of package lists +// Package lists // // Many commands apply to a set of packages: // @@ -1484,7 +1524,7 @@ // by the go tool, as are directories named "testdata". // // -// Description of testing flags +// Testing flags // // The 'go test' command takes both flags that apply to 'go test' itself // and flags that apply to the resulting test binary. @@ -1711,7 +1751,7 @@ // binary, instead of being interpreted as the package list. // // -// Description of testing functions +// Testing functions // // The 'go test' command expects to find test, benchmark, and example functions // in the "*_test.go" files corresponding to the package under test. diff --git a/src/cmd/go/internal/help/helpdoc.go b/src/cmd/go/internal/help/helpdoc.go index 43144db593..4ebf206078 100644 --- a/src/cmd/go/internal/help/helpdoc.go +++ b/src/cmd/go/internal/help/helpdoc.go @@ -30,7 +30,7 @@ the C or C++ compiler, respectively, to use. var HelpPackages = &base.Command{ UsageLine: "packages", - Short: "description of package lists", + Short: "package lists", Long: ` Many commands apply to a set of packages: @@ -583,7 +583,7 @@ command. var HelpBuildmode = &base.Command{ UsageLine: "buildmode", - Short: "description of build modes", + Short: "build modes", Long: ` 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 @@ -629,3 +629,45 @@ are: import, into a Go plugin. Packages not named main are ignored. `, } + +var HelpCache = &base.Command{ + UsageLine: "cache", + Short: "build and test caching", + Long: ` +The go command caches build outputs for reuse in future builds. +The default location for cache data is a subdirectory named go-build +in the standard user cache directory for the current operating system. +Setting the GOCACHE environment variable overrides this default, +and running 'go env GOCACHE' prints the current cache directory. + +The go command periodically deletes cached data that has not been +used recently. Running 'go clean -cache' deletes all cached data. + +The build cache correctly accounts for changes to Go source files, +compilers, compiler options, and so on: cleaning the cache explicitly +should not be necessary in typical use. However, the build cache +does not detect changes to C libraries imported with cgo. +If you have made changes to the C libraries on your system, you +will need to clean the cache explicitly or else use the -a build flag +(see 'go help build') to force rebuilding of packages that +depend on the updated C libraries. + +The go command also caches successful package test results. +See 'go help test' for details. Running 'go clean -testcache' removes +all cached test results (but not cached build results). + +The GODEBUG environment variable can enable printing of debugging +information about the state of the cache: + +GODEBUG=gocacheverify=1 causes the go command to bypass the +use of any cache entries and instead rebuild everything and check +that the results match existing cache entries. + +GODEBUG=gocachehash=1 causes the go command to print the inputs +for all of the content hashes it uses to construct cache lookup keys. +The output is voluminous but can be useful for debugging the cache. + +GODEBUG=gocachetest=1 causes the go command to print details of its +decisions about whether to reuse a cached test result. +`, +} diff --git a/src/cmd/go/internal/test/test.go b/src/cmd/go/internal/test/test.go index 1936112c2e..fa789a48b9 100644 --- a/src/cmd/go/internal/test/test.go +++ b/src/cmd/go/internal/test/test.go @@ -176,7 +176,7 @@ func Usage() { var HelpTestflag = &base.Command{ UsageLine: "testflag", - Short: "description of testing flags", + Short: "testing flags", Long: ` The 'go test' command takes both flags that apply to 'go test' itself and flags that apply to the resulting test binary. @@ -410,7 +410,7 @@ binary, instead of being interpreted as the package list. var HelpTestfunc = &base.Command{ UsageLine: "testfunc", - Short: "description of testing functions", + Short: "testing functions", Long: ` The 'go test' command expects to find test, benchmark, and example functions in the "*_test.go" files corresponding to the package under test. diff --git a/src/cmd/go/main.go b/src/cmd/go/main.go index b7e4034152..497970b725 100644 --- a/src/cmd/go/main.go +++ b/src/cmd/go/main.go @@ -56,6 +56,7 @@ func init() { help.HelpC, help.HelpBuildmode, + help.HelpCache, help.HelpFileType, help.HelpGopath, help.HelpEnvironment,