cmd/go: document new -exec flag on run/test

The new flag was added by CL 68150047 (part of the NaCl replay),
but the change, like the original, omitted documentation of the
new behavior.

LGTM=r
R=r
CC=golang-codereviews
https://golang.org/cl/68580043

diff --git a/doc/go1.3.txt b/doc/go1.3.txt
index fda35a7e3ff8a7fe14594fc9637bd3ceb4035fe5..95db83a728b800008c0b8fef4e0ef3233314bc8f 100644 (file)
--- a/doc/go1.3.txt
+++ b/doc/go1.3.txt
@@ -10,3 +10,4 @@ cmd/go, go/build: support .m files (CL 60590044)
 unicode: upgrade from Unicode 6.2.0 to 6.3.0 (CL 65400044)
 runtime/debug: add SetPanicOnFault (CL 66590044)
 crypto/tls: ServerName or InsecureSkipVerify (CL 67010043)
+cmd/go: add -exec to 'go run' and 'go test' (CL 68580043)

diff --git a/src/cmd/go/doc.go b/src/cmd/go/doc.go
index 3b79ee6fe37b7b3d96cdf4300c0eb52cb91a352b..155623000ed6898318451fd8a3a9290ac6927c82 100644 (file)
--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -303,6 +303,7 @@ which calls strings.Join. The struct being passed to the template is:
         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
         SFiles   []string       // .s source files
         SwigFiles []string      // .swig files
@@ -357,11 +358,20 @@ Compile and run Go program
 
 Usage:
 
-       go run [build flags] gofiles... [arguments...]
+       go run [build flags] [-exec xprog] gofiles... [arguments...]
 
 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.
 
+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: 'xprog a.out arguments...'.
+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.
+
 For more about build flags, see 'go help build'.
 
 See also: go build.
@@ -408,6 +418,10 @@ In addition to the build flags, the flags handled by 'go test' itself are:
            Install packages that are dependencies of the test.
            Do not run the test.
 
+       -exec xprog
+           Run the test binary using xprog. The behavior is the same as
+           in 'go run'. See 'go help run' for details.
+
 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.
 
@@ -478,8 +492,8 @@ http://swig.org/.  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.
 
-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++
+When either cgo or SWIG is used, go build will pass any .c, .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.
 
@@ -823,9 +837,7 @@ control the execution of any test:
            Enable more precise (and expensive) memory profiles by setting
            runtime.MemProfileRate.  See 'godoc runtime MemProfileRate'.
            To profile all memory allocations, use -test.memprofilerate=1
-           and set the environment variable GOGC=off to disable the
-           garbage collector, provided the test can run in the available
-           memory without garbage collection.
+           and pass --alloc_space flag to the pprof tool.
 
        -outputdir directory
            Place output files from profiling in the specified directory,

diff --git a/src/cmd/go/run.go b/src/cmd/go/run.go
index b6449713dfa200deb8c38ac2fdddc9627051d553..ef8aa95a351aa3c938bc258dc78d2140a97d6f94 100644 (file)
--- a/src/cmd/go/run.go
+++ b/src/cmd/go/run.go
@@ -30,12 +30,21 @@ func findExecCmd() []string {
 }
 
 var cmdRun = &Command{
-       UsageLine: "run [build flags] gofiles... [arguments...]",
+       UsageLine: "run [build flags] [-exec xprog] gofiles... [arguments...]",
        Short:     "compile and run Go program",
        Long: `
 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.
 
+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: 'xprog a.out arguments...'.
+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.
+
 For more about build flags, see 'go help build'.
 
 See also: go build.

diff --git a/src/cmd/go/test.go b/src/cmd/go/test.go
index 2da63ef04a2805405a1f6d1eaab75ba852a05391..a6fe19d2cb517e778565576c795b8c980f905157 100644 (file)
--- a/src/cmd/go/test.go
+++ b/src/cmd/go/test.go
@@ -72,6 +72,10 @@ In addition to the build flags, the flags handled by 'go test' itself are:
            Install packages that are dependencies of the test.
            Do not run the test.
 
+       -exec xprog
+           Run the test binary using xprog. The behavior is the same as
+           in 'go run'. See 'go help run' for details.
+
 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.