diff options
Diffstat (limited to 'src/cmd/go/help.go')
| -rw-r--r-- | src/cmd/go/help.go | 79 |
1 files changed, 69 insertions, 10 deletions
diff --git a/src/cmd/go/help.go b/src/cmd/go/help.go index c70a25fdd..71e55175a 100644 --- 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", + 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", @@ -25,12 +47,17 @@ environment variable (see 'go help gopath'). If no import paths are given, the action applies to the package in the current directory. -The special import path "all" expands to all package directories -found in all the GOPATH trees. For example, 'go list all' -lists all the packages on the local system. +There are three reserved names for paths that should not be used +for packages to be built with the go tool: + +- "main" denotes the top-level package in a stand-alone executable. -The special import path "std" is like all but expands to just the -packages in the standard Go library. +- "all" expands to all package directories found in all the GOPATH +trees. For example, 'go list all' lists all the packages on the local +system. + +- "std" is like all but expands to just the packages in the standard +Go library. An import path is a pattern if it includes one or more "..." wildcards, each of which can match any string, including the empty string and @@ -40,7 +67,7 @@ patterns. As a special case, x/... matches x as well as x's subdirectories. For example, net/... expands to net and packages in its subdirectories. An import path can also name a package to be downloaded from -a remote repository. Run 'go help remote' for details. +a remote repository. Run 'go help importpath' for details. Every package in a program must have a unique import path. By convention, this is arranged by starting each path with a @@ -53,16 +80,48 @@ As a special case, if the package list is a list of .go files from a single directory, the command is applied to a single synthesized package made up of exactly those files, ignoring any build constraints in those files and ignoring any other files in the directory. + +File names that begin with "." or "_" are ignored by the go tool. `, } -var helpRemote = &Command{ - UsageLine: "remote", - Short: "remote import path syntax", +var helpImportPath = &Command{ + UsageLine: "importpath", + Short: "import path syntax", Long: ` An import path (see 'go help packages') denotes a package -stored in the local file system. Certain import paths also +stored in the local file system. In general, an import path denotes +either a standard package (such as "unicode/utf8") or a package +found in one of the work spaces (see 'go help gopath'). + +Relative import paths + +An import path beginning with ./ or ../ is called a relative path. +The toolchain supports relative import paths as a shortcut in two ways. + +First, a relative path can be used as a shorthand on the command line. +If you are working in the directory containing the code imported as +"unicode" and want to run the tests for "unicode/utf8", you can type +"go test ./utf8" instead of needing to specify the full path. +Similarly, in the reverse situation, "go test .." will test "unicode" from +the "unicode/utf8" directory. Relative patterns are also allowed, like +"go test ./..." to test all subdirectories. See 'go help packages' for details +on the pattern syntax. + +Second, if you are compiling a Go program not in a work space, +you can use a relative path in an import statement in that program +to refer to nearby code also not in a work space. +This makes it easy to experiment with small multipackage programs +outside of the usual work spaces, but such programs cannot be +installed with "go install" (there is no work space in which to install them), +so they are rebuilt from scratch each time they are built. +To avoid ambiguity, Go programs cannot use relative import paths +within a work space. + +Remote import paths + +Certain import paths also describe how to obtain the source code for the package using a revision control system. |