cmd/go: add basic docs on calling between Go and C/C++

This is a framework for docs on the subject more than it is
actual docs.

The section header in go/doc.go just says "C", not "C/C++,"
because otherwise godoc doesn't recognize the line as a
section header.

Fixes #5473.

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/13280050

diff --git a/src/cmd/go/build.go b/src/cmd/go/build.go
index e8a9430c1a05d0af583041275b725115cd316d86..bdbe490ad6f1f8c241b605ed16ce76f95c2d9ae8 100644 (file)
--- a/src/cmd/go/build.go
+++ b/src/cmd/go/build.go
@@ -94,7 +94,8 @@ 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'.
+run 'go help gopath'.  For more about calling between Go and C/C++,
+run 'go help c'.
 
 See also: go install, go get, go clean.
        `,

diff --git a/src/cmd/go/doc.go b/src/cmd/go/doc.go
index 46905c1cf996d292dde9661013144eab2078a04a..ffb2ee33a46bb997bc7d2ffdaa6ad7f484f7170c 100644 (file)
--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -32,6 +32,7 @@ Use "go help [command]" for more information about a command.
 
 Additional help topics:
 
+    c           calling between Go and C/C++
     gopath      GOPATH environment variable
     packages    description of package lists
     remote      remote import path syntax
@@ -111,7 +112,8 @@ 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'.
+run 'go help gopath'.  For more about calling between Go and C/C++,
+run 'go help c'.
 
 See also: go install, go get, go clean.
 
@@ -463,6 +465,25 @@ The -x flag prints commands as they are executed.
 See also: go fmt, go fix.
 
 
+Calling between Go and C
+
+There are two different ways to call between Go and C/C++ code.
+
+The first is the cgo tool, which is part of the Go distribution.  For
+information on how to use it see the cgo documentation (godoc cmd/cgo).
+
+The second is the SWIG program, which is a general tool for
+interfacing between languages.  For information on SWIG see
+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, .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.
+
+
 GOPATH environment variable
 
 The Go path is used to resolve import statements.

diff --git a/src/cmd/go/help.go b/src/cmd/go/help.go
index 8028fe8a9e326a3196c353491ce3be50b083404f..d10043efe1145b6481e7a4ad632cedb5b1dede07 100644 (file)
--- a/src/cmd/go/help.go
+++ b/src/cmd/go/help.go
@@ -4,6 +4,28 @@
 
 package main
 
+var helpC = &Command{
+       UsageLine: "c",
+       Short:     "calling between Go and C/C++",
+       Long: `
+There are two different ways to call between Go and C/C++ code.
+
+The first is the cgo tool, which is part of the Go distribution.  For
+information on how to use it see the cgo documentation (godoc cmd/cgo).
+
+The second is the SWIG program, which is a general tool for
+interfacing between languages.  For information on SWIG see
+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, .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.
+       `,
+}
+
 var helpPackages = &Command{
        UsageLine: "packages",
        Short:     "description of package lists",

diff --git a/src/cmd/go/main.go b/src/cmd/go/main.go
index 1553c88d6009b48304fe17ff46f77cfe25669254..ac2a7ea2867933994c60d495c64fd6c0471e3f61 100644 (file)
--- a/src/cmd/go/main.go
+++ b/src/cmd/go/main.go
@@ -88,6 +88,7 @@ var commands = []*Command{
        cmdVersion,
        cmdVet,
 
+       helpC,
        helpGopath,
        helpPackages,
        helpRemote,