cmd/go: mention go tool compile etc. in the help text for build

Not everyone is aware that go build is a wrapper for other
tools. Mention this in the text for go help build so people using
other build systems won't just wrap go build, which is usually a
mistake (it doesn't do incremental builds by default, for instance).

Update #11854.

Change-Id: I759f91f23ccd3671204c39feea12a3bfaf9f0114
Reviewed-on: https://go-review.googlesource.com/12625
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 66c277bb01ce7e8d2c1c71cc0a5a298ff28c9ed1..b5d260a7e8f20a2cb1cd0934c4a89581b11b7e74 100644 (file)
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -56,8 +56,8 @@ Usage:
 Build compiles the packages named by the import paths,
 along with their dependencies, but it does not install the results.
 
-If the arguments are a list of .go files, build treats them as a list
-of source files specifying a single package.
+If the arguments to build are a list of .go files, build treats
+them as a list of source files specifying a single package.
 
 When the command line specifies a single main package,
 build writes the resulting executable to output.
@@ -139,6 +139,13 @@ 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'.
 
+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.
+
 See also: go install, go get, go clean.
 
 

diff --git a/src/cmd/go/build.go b/src/cmd/go/build.go
index 9134e396016c01f37b16761b1a13a5580b8763a5..54fbe351052a0f3e60d5d157db8e3ea691f51309 100644 (file)
--- a/src/cmd/go/build.go
+++ b/src/cmd/go/build.go
@@ -35,8 +35,8 @@ var cmdBuild = &Command{
 Build compiles the packages named by the import paths,
 along with their dependencies, but it does not install the results.
 
-If the arguments are a list of .go files, build treats them as a list
-of source files specifying a single package.
+If the arguments to build are a list of .go files, build treats
+them as a list of source files specifying a single package.
 
 When the command line specifies a single main package,
 build writes the resulting executable to output.
@@ -118,6 +118,13 @@ 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'.
 
+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.
+
 See also: go install, go get, go clean.
        `,
 }