From 280d46b03be642fbbb817332069d6b337774746e Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Tue, 25 Feb 2014 10:22:27 -0500 Subject: [PATCH] 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 --- doc/go1.3.txt | 1 + src/cmd/go/doc.go | 24 ++++++++++++++++++------ src/cmd/go/run.go | 11 ++++++++++- src/cmd/go/test.go | 4 ++++ 4 files changed, 33 insertions(+), 7 deletions(-) diff --git a/doc/go1.3.txt b/doc/go1.3.txt index fda35a7e3ff..95db83a728b 100644 --- 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 3b79ee6fe37..155623000ed 100644 --- 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 b6449713dfa..ef8aa95a351 100644 --- 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 2da63ef04a2..a6fe19d2cb5 100644 --- 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.