1 // Copyright 2011 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
9 Short: "calling between Go and C",
11 There are two different ways to call between Go and C/C++ code.
13 The first is the cgo tool, which is part of the Go distribution. For
14 information on how to use it see the cgo documentation (go doc cmd/cgo).
16 The second is the SWIG program, which is a general tool for
17 interfacing between languages. For information on SWIG see
18 http://swig.org/. When running go build, any file with a .swig
19 extension will be passed to SWIG. Any file with a .swigcxx extension
20 will be passed to SWIG with the -c++ option.
22 When either cgo or SWIG is used, go build will pass any .c, .m, .s,
23 or .S files to the C compiler, and any .cc, .cpp, .cxx files to the C++
24 compiler. The CC or CXX environment variables may be set to determine
25 the C or C++ compiler, respectively, to use.
29 var helpPackages = &Command{
30 UsageLine: "packages",
31 Short: "description of package lists",
33 Many commands apply to a set of packages:
37 Usually, [packages] is a list of import paths.
39 An import path that is a rooted path or that begins with
40 a . or .. element is interpreted as a file system path and
41 denotes the package in that directory.
43 Otherwise, the import path P denotes the package found in
44 the directory DIR/src/P for some DIR listed in the GOPATH
45 environment variable (see 'go help gopath').
47 If no import paths are given, the action applies to the
48 package in the current directory.
50 There are four reserved names for paths that should not be used
51 for packages to be built with the go tool:
53 - "main" denotes the top-level package in a stand-alone executable.
55 - "all" expands to all package directories found in all the GOPATH
56 trees. For example, 'go list all' lists all the packages on the local
59 - "std" is like all but expands to just the packages in the standard
62 - "cmd" expands to the Go repository's commands and their
65 An import path is a pattern if it includes one or more "..." wildcards,
66 each of which can match any string, including the empty string and
67 strings containing slashes. Such a pattern expands to all package
68 directories found in the GOPATH trees with names matching the
69 patterns. As a special case, x/... matches x as well as x's subdirectories.
70 For example, net/... expands to net and packages in its subdirectories.
72 An import path can also name a package to be downloaded from
73 a remote repository. Run 'go help importpath' for details.
75 Every package in a program must have a unique import path.
76 By convention, this is arranged by starting each path with a
77 unique prefix that belongs to you. For example, paths used
78 internally at Google all begin with 'google', and paths
79 denoting remote repositories begin with the path to the code,
80 such as 'github.com/user/repo'.
82 As a special case, if the package list is a list of .go files from a
83 single directory, the command is applied to a single synthesized
84 package made up of exactly those files, ignoring any build constraints
85 in those files and ignoring any other files in the directory.
87 Directory and file names that begin with "." or "_" are ignored
88 by the go tool, as are directories named "testdata".
92 var helpImportPath = &Command{
93 UsageLine: "importpath",
94 Short: "import path syntax",
97 An import path (see 'go help packages') denotes a package
98 stored in the local file system. In general, an import path denotes
99 either a standard package (such as "unicode/utf8") or a package
100 found in one of the work spaces (see 'go help gopath').
102 Relative import paths
104 An import path beginning with ./ or ../ is called a relative path.
105 The toolchain supports relative import paths as a shortcut in two ways.
107 First, a relative path can be used as a shorthand on the command line.
108 If you are working in the directory containing the code imported as
109 "unicode" and want to run the tests for "unicode/utf8", you can type
110 "go test ./utf8" instead of needing to specify the full path.
111 Similarly, in the reverse situation, "go test .." will test "unicode" from
112 the "unicode/utf8" directory. Relative patterns are also allowed, like
113 "go test ./..." to test all subdirectories. See 'go help packages' for details
114 on the pattern syntax.
116 Second, if you are compiling a Go program not in a work space,
117 you can use a relative path in an import statement in that program
118 to refer to nearby code also not in a work space.
119 This makes it easy to experiment with small multipackage programs
120 outside of the usual work spaces, but such programs cannot be
121 installed with "go install" (there is no work space in which to install them),
122 so they are rebuilt from scratch each time they are built.
123 To avoid ambiguity, Go programs cannot use relative import paths
128 Certain import paths also
129 describe how to obtain the source code for the package using
130 a revision control system.
132 A few common code hosting sites have special syntax:
134 Bitbucket (Git, Mercurial)
136 import "bitbucket.org/user/project"
137 import "bitbucket.org/user/project/sub/directory"
141 import "github.com/user/project"
142 import "github.com/user/project/sub/directory"
144 Google Code Project Hosting (Git, Mercurial, Subversion)
146 import "code.google.com/p/project"
147 import "code.google.com/p/project/sub/directory"
149 import "code.google.com/p/project.subrepository"
150 import "code.google.com/p/project.subrepository/sub/directory"
154 import "launchpad.net/project"
155 import "launchpad.net/project/series"
156 import "launchpad.net/project/series/sub/directory"
158 import "launchpad.net/~user/project/branch"
159 import "launchpad.net/~user/project/branch/sub/directory"
161 IBM DevOps Services (Git)
163 import "hub.jazz.net/git/user/project"
164 import "hub.jazz.net/git/user/project/sub/directory"
166 For code hosted on other servers, import paths may either be qualified
167 with the version control type, or the go tool can dynamically fetch
168 the import path over https/http and discover where the code resides
169 from a <meta> tag in the HTML.
171 To declare the code location, an import path of the form
175 specifies the given repository, with or without the .vcs suffix,
176 using the named version control system, and then the path inside
177 that repository. The supported version control systems are:
186 import "example.org/user/foo.hg"
188 denotes the root directory of the Mercurial repository at
189 example.org/user/foo or foo.hg, and
191 import "example.org/repo.git/foo/bar"
193 denotes the foo/bar directory of the Git repository at
194 example.org/repo or repo.git.
196 When a version control system supports multiple protocols,
197 each is tried in turn when downloading. For example, a Git
198 download tries https://, then git+ssh://.
200 If the import path is not a known code hosting site and also lacks a
201 version control qualifier, the go tool attempts to fetch the import
202 over https/http and looks for a <meta> tag in the document's HTML
205 The meta tag has the form:
207 <meta name="go-import" content="import-prefix vcs repo-root">
209 The import-prefix is the import path corresponding to the repository
210 root. It must be a prefix or an exact match of the package being
211 fetched with "go get". If it's not an exact match, another http
212 request is made at the prefix to verify the <meta> tags match.
214 The meta tag should appear as early in the file as possible.
215 In particular, it should appear before any raw JavaScript or CSS,
216 to avoid confusing the go command's restricted parser.
218 The vcs is one of "git", "hg", "svn", etc,
220 The repo-root is the root of the version control system
221 containing a scheme and not containing a .vcs qualifier.
225 import "example.org/pkg/foo"
227 will result in the following requests:
229 https://example.org/pkg/foo?go-get=1 (preferred)
230 http://example.org/pkg/foo?go-get=1 (fallback, only with -insecure)
232 If that page contains the meta tag
234 <meta name="go-import" content="example.org git https://code.org/r/p/exproj">
236 the go tool will verify that https://example.org/?go-get=1 contains the
237 same meta tag and then git clone https://code.org/r/p/exproj into
238 GOPATH/src/example.org.
240 New downloaded packages are written to the first directory
241 listed in the GOPATH environment variable (see 'go help gopath').
243 The go command attempts to download the version of the
244 package appropriate for the Go release being used.
245 Run 'go help get' for more.
249 When the custom import path feature described above redirects to a
250 known code hosting site, each of the resulting packages has two possible
251 import paths, using the custom domain or the known hosting site.
253 A package statement is said to have an "import comment" if it is immediately
254 followed (before the next newline) by a comment of one of these two forms:
256 package math // import "path"
257 package math /* import "path" */
259 The go command will refuse to install a package with an import comment
260 unless it is being referred to by that import path. In this way, import comments
261 let package authors make sure the custom import path is used and not a
262 direct path to the underlying code hosting site.
264 If the vendoring experiment is enabled (see 'go help gopath'),
265 then import path checking is disabled for code found within vendor trees.
266 This makes it possible to copy code into alternate locations in vendor trees
267 without needing to update import comments.
269 See https://golang.org/s/go14customimport for details.
273 var helpGopath = &Command{
275 Short: "GOPATH environment variable",
277 The Go path is used to resolve import statements.
278 It is implemented by and documented in the go/build package.
280 The GOPATH environment variable lists places to look for Go code.
281 On Unix, the value is a colon-separated string.
282 On Windows, the value is a semicolon-separated string.
283 On Plan 9, the value is a list.
285 GOPATH must be set to get, build and install packages outside the
288 Each directory listed in GOPATH must have a prescribed structure:
290 The src directory holds source code. The path below src
291 determines the import path or executable name.
293 The pkg directory holds installed package objects.
294 As in the Go tree, each target operating system and
295 architecture pair has its own subdirectory of pkg
298 If DIR is a directory listed in the GOPATH, a package with
299 source in DIR/src/foo/bar can be imported as "foo/bar" and
300 has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a".
302 The bin directory holds compiled commands.
303 Each command is named for its source directory, but only
304 the final element, not the entire path. That is, the
305 command with source in DIR/src/foo/quux is installed into
306 DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped
307 so that you can add DIR/bin to your PATH to get at the
308 installed commands. If the GOBIN environment variable is
309 set, commands are installed to the directory it names instead
312 Here's an example directory layout:
314 GOPATH=/home/user/gocode
319 bar/ (go code in package bar)
321 quux/ (go code in package main)
324 quux (installed command)
328 bar.a (installed package object)
330 Go searches each directory listed in GOPATH to find source code,
331 but new packages are always downloaded into the first directory
334 See https://golang.org/doc/code.html for an example.
338 Code in or below a directory named "internal" is importable only
339 by code in the directory tree rooted at the parent of "internal".
340 Here's an extended version of the directory layout above:
345 bang/ (go code in package bang)
347 foo/ (go code in package foo)
349 bar/ (go code in package bar)
352 baz/ (go code in package baz)
354 quux/ (go code in package main)
358 The code in z.go is imported as "foo/internal/baz", but that
359 import statement can only appear in source files in the subtree
360 rooted at foo. The source files foo/f.go, foo/bar/x.go, and
361 foo/quux/y.go can all import "foo/internal/baz", but the source file
362 crash/bang/b.go cannot.
364 See https://golang.org/s/go14internal for details.
368 Go 1.5 includes experimental support for using local copies
369 of external dependencies to satisfy imports of those dependencies,
370 often referred to as vendoring. Setting the environment variable
371 GO15VENDOREXPERIMENT=1 enables that experimental support.
373 When the vendor experiment is enabled,
374 code below a directory named "vendor" is importable only
375 by code in the directory tree rooted at the parent of "vendor",
376 and only using an import path that omits the prefix up to and
377 including the vendor element.
379 Here's the example from the previous section,
380 but with the "internal" directory renamed to "vendor"
381 and a new foo/vendor/crash/bang directory added:
386 bang/ (go code in package bang)
388 foo/ (go code in package foo)
390 bar/ (go code in package bar)
394 bang/ (go code in package bang)
396 baz/ (go code in package baz)
398 quux/ (go code in package main)
401 The same visibility rules apply as for internal, but the code
402 in z.go is imported as "baz", not as "foo/vendor/baz".
404 Code in vendor directories deeper in the source tree shadows
405 code in higher directories. Within the subtree rooted at foo, an import
406 of "crash/bang" resolves to "foo/vendor/crash/bang", not the
407 top-level "crash/bang".
409 Code in vendor directories is not subject to import path
410 checking (see 'go help importpath').
412 When the vendor experiment is enabled, 'go get' checks out
413 submodules when checking out or updating a git repository
416 The vendoring semantics are an experiment, and they may change
417 in future releases. Once settled, they will be on by default.
419 See https://golang.org/s/go15vendor for details.
423 var helpEnvironment = &Command{
424 UsageLine: "environment",
425 Short: "environment variables",
428 The go command, and the tools it invokes, examine a few different
429 environment variables. For many of these, you can see the default
430 value of on your system by running 'go env NAME', where NAME is the
431 name of the variable.
433 General-purpose environment variables:
436 The gccgo command to run for 'go build -compiler=gccgo'.
438 The architecture, or processor, for which to compile code.
439 Examples are amd64, 386, arm, ppc64.
441 The directory where 'go install' will install a command.
443 The operating system for which to compile code.
444 Examples are linux, darwin, windows, netbsd.
446 See 'go help gopath'.
448 Options for the race detector.
449 See https://golang.org/doc/articles/race_detector.html.
451 The root of the go tree.
453 Environment variables for use with cgo:
456 The command to use to compile C code.
458 Whether the cgo command is supported. Either 0 or 1.
460 Flags that cgo will pass to the compiler when compiling
463 Flags that cgo will pass to the compiler when compiling
466 Flags that cgo will pass to the compiler when compiling
469 Flags that cgo will pass to the compiler when linking.
471 The command to use to compile C++ code.
473 Architecture-specific environment variables:
476 For GOARCH=arm, the ARM architecture for which to compile.
477 Valid values are 5, 6, 7.
479 For GOARCH=386, the floating point instruction set.
480 Valid values are 387, sse2.
482 Special-purpose environment variables:
485 The root of the installed Go tree, when it is
486 installed in a location other than where it is built.
487 File names in stack traces are rewritten from GOROOT to
490 Set to 1 to enable the Go 1.5 vendoring experiment.
492 Whether the linker should use external linking mode
493 when using -linkmode=auto with code that uses cgo.
494 Set to 0 to disable external linking mode, 1 to enable it.
498 var helpFileType = &Command{
499 UsageLine: "filetype",
502 The go command examines the contents of a restricted set of files
503 in each directory. It identifies which files to examine based on
504 the extension of the file name. These extensions are:
510 If the package uses cgo or SWIG, these will be compiled with the
511 OS-native compiler (typically gcc); otherwise they will
513 .cc, .cpp, .cxx, .hh, .hpp, .hxx
514 C++ source files. Only useful with cgo or SWIG, and always
515 compiled with the OS-native compiler.
517 Objective-C source files. Only useful with cgo, and always
518 compiled with the OS-native compiler.
520 Assembler source files.
521 If the package uses cgo or SWIG, these will be assembled with the
522 OS-native assembler (typically gcc (sic)); otherwise they
523 will be assembled with the Go assembler.
525 SWIG definition files.
529 Files of each of these types except .syso may contain build
530 constraints, but the go command stops scanning for build constraints
531 at the first item in the file that is not a blank line or //-style
536 var helpBuildmode = &Command{
537 UsageLine: "buildmode",
538 Short: "description of build modes",
540 The 'go build' and 'go install' commands take a -buildmode argument which
541 indicates which kind of object file is to be built. Currently supported values
545 Build the listed non-main packages into .a files. Packages named
549 Build the listed main package, plus all packages it imports,
550 into a C archive file. The only callable symbols will be those
551 functions exported using a cgo //export comment. Requires
552 exactly one main package to be listed.
555 Build the listed main packages, plus all packages that they
556 import, into C shared libraries. The only callable symbols will
557 be those functions exported using a cgo //export comment.
558 Non-main packages are ignored.
561 Listed main packages are built into executables and listed
562 non-main packages are built into .a files (the default
566 Combine all the listed non-main packages into a single shared
567 library that will be used when building with the -linkshared
568 option. Packages named main are ignored.
571 Build the listed main packages and everything they import into
572 executables. Packages not named main are ignored.