Source file src/pkg/cmd/go/internal/help/helpdoc.go
1
2
3
4
5 package help
6
7 import "cmd/go/internal/base"
8
9 var HelpC = &base.Command{
10 UsageLine: "c",
11 Short: "calling between Go and C",
12 Long: `
13 There are two different ways to call between Go and C/C++ code.
14
15 The first is the cgo tool, which is part of the Go distribution. For
16 information on how to use it see the cgo documentation (go doc cmd/cgo).
17
18 The second is the SWIG program, which is a general tool for
19 interfacing between languages. For information on SWIG see
20 http://swig.org/. When running go build, any file with a .swig
21 extension will be passed to SWIG. Any file with a .swigcxx extension
22 will be passed to SWIG with the -c++ option.
23
24 When either cgo or SWIG is used, go build will pass any .c, .m, .s,
25 or .S files to the C compiler, and any .cc, .cpp, .cxx files to the C++
26 compiler. The CC or CXX environment variables may be set to determine
27 the C or C++ compiler, respectively, to use.
28 `,
29 }
30
31 var HelpPackages = &base.Command{
32 UsageLine: "packages",
33 Short: "package lists and patterns",
34 Long: `
35 Many commands apply to a set of packages:
36
37 go action [packages]
38
39 Usually, [packages] is a list of import paths.
40
41 An import path that is a rooted path or that begins with
42 a . or .. element is interpreted as a file system path and
43 denotes the package in that directory.
44
45 Otherwise, the import path P denotes the package found in
46 the directory DIR/src/P for some DIR listed in the GOPATH
47 environment variable (For more details see: 'go help gopath').
48
49 If no import paths are given, the action applies to the
50 package in the current directory.
51
52 There are four reserved names for paths that should not be used
53 for packages to be built with the go tool:
54
55 - "main" denotes the top-level package in a stand-alone executable.
56
57 - "all" expands to all packages found in all the GOPATH
58 trees. For example, 'go list all' lists all the packages on the local
59 system. When using modules, "all" expands to all packages in
60 the main module and their dependencies, including dependencies
61 needed by tests of any of those.
62
63 - "std" is like all but expands to just the packages in the standard
64 Go library.
65
66 - "cmd" expands to the Go repository's commands and their
67 internal libraries.
68
69 Import paths beginning with "cmd/" only match source code in
70 the Go repository.
71
72 An import path is a pattern if it includes one or more "..." wildcards,
73 each of which can match any string, including the empty string and
74 strings containing slashes. Such a pattern expands to all package
75 directories found in the GOPATH trees with names matching the
76 patterns.
77
78 To make common patterns more convenient, there are two special cases.
79 First, /... at the end of the pattern can match an empty string,
80 so that net/... matches both net and packages in its subdirectories, like net/http.
81 Second, any slash-separated pattern element containing a wildcard never
82 participates in a match of the "vendor" element in the path of a vendored
83 package, so that ./... does not match packages in subdirectories of
84 ./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do.
85 Note, however, that a directory named vendor that itself contains code
86 is not a vendored package: cmd/vendor would be a command named vendor,
87 and the pattern cmd/... matches it.
88 See golang.org/s/go15vendor for more about vendoring.
89
90 An import path can also name a package to be downloaded from
91 a remote repository. Run 'go help importpath' for details.
92
93 Every package in a program must have a unique import path.
94 By convention, this is arranged by starting each path with a
95 unique prefix that belongs to you. For example, paths used
96 internally at Google all begin with 'google', and paths
97 denoting remote repositories begin with the path to the code,
98 such as 'github.com/user/repo'.
99
100 Packages in a program need not have unique package names,
101 but there are two reserved package names with special meaning.
102 The name main indicates a command, not a library.
103 Commands are built into binaries and cannot be imported.
104 The name documentation indicates documentation for
105 a non-Go program in the directory. Files in package documentation
106 are ignored by the go command.
107
108 As a special case, if the package list is a list of .go files from a
109 single directory, the command is applied to a single synthesized
110 package made up of exactly those files, ignoring any build constraints
111 in those files and ignoring any other files in the directory.
112
113 Directory and file names that begin with "." or "_" are ignored
114 by the go tool, as are directories named "testdata".
115 `,
116 }
117
118 var HelpImportPath = &base.Command{
119 UsageLine: "importpath",
120 Short: "import path syntax",
121 Long: `
122
123 An import path (see 'go help packages') denotes a package stored in the local
124 file system. In general, an import path denotes either a standard package (such
125 as "unicode/utf8") or a package found in one of the work spaces (For more
126 details see: 'go help gopath').
127
128 Relative import paths
129
130 An import path beginning with ./ or ../ is called a relative path.
131 The toolchain supports relative import paths as a shortcut in two ways.
132
133 First, a relative path can be used as a shorthand on the command line.
134 If you are working in the directory containing the code imported as
135 "unicode" and want to run the tests for "unicode/utf8", you can type
136 "go test ./utf8" instead of needing to specify the full path.
137 Similarly, in the reverse situation, "go test .." will test "unicode" from
138 the "unicode/utf8" directory. Relative patterns are also allowed, like
139 "go test ./..." to test all subdirectories. See 'go help packages' for details
140 on the pattern syntax.
141
142 Second, if you are compiling a Go program not in a work space,
143 you can use a relative path in an import statement in that program
144 to refer to nearby code also not in a work space.
145 This makes it easy to experiment with small multipackage programs
146 outside of the usual work spaces, but such programs cannot be
147 installed with "go install" (there is no work space in which to install them),
148 so they are rebuilt from scratch each time they are built.
149 To avoid ambiguity, Go programs cannot use relative import paths
150 within a work space.
151
152 Remote import paths
153
154 Certain import paths also
155 describe how to obtain the source code for the package using
156 a revision control system.
157
158 A few common code hosting sites have special syntax:
159
160 Bitbucket (Git, Mercurial)
161
162 import "bitbucket.org/user/project"
163 import "bitbucket.org/user/project/sub/directory"
164
165 GitHub (Git)
166
167 import "github.com/user/project"
168 import "github.com/user/project/sub/directory"
169
170 Launchpad (Bazaar)
171
172 import "launchpad.net/project"
173 import "launchpad.net/project/series"
174 import "launchpad.net/project/series/sub/directory"
175
176 import "launchpad.net/~user/project/branch"
177 import "launchpad.net/~user/project/branch/sub/directory"
178
179 IBM DevOps Services (Git)
180
181 import "hub.jazz.net/git/user/project"
182 import "hub.jazz.net/git/user/project/sub/directory"
183
184 For code hosted on other servers, import paths may either be qualified
185 with the version control type, or the go tool can dynamically fetch
186 the import path over https/http and discover where the code resides
187 from a <meta> tag in the HTML.
188
189 To declare the code location, an import path of the form
190
191 repository.vcs/path
192
193 specifies the given repository, with or without the .vcs suffix,
194 using the named version control system, and then the path inside
195 that repository. The supported version control systems are:
196
197 Bazaar .bzr
198 Fossil .fossil
199 Git .git
200 Mercurial .hg
201 Subversion .svn
202
203 For example,
204
205 import "example.org/user/foo.hg"
206
207 denotes the root directory of the Mercurial repository at
208 example.org/user/foo or foo.hg, and
209
210 import "example.org/repo.git/foo/bar"
211
212 denotes the foo/bar directory of the Git repository at
213 example.org/repo or repo.git.
214
215 When a version control system supports multiple protocols,
216 each is tried in turn when downloading. For example, a Git
217 download tries https://, then git+ssh://.
218
219 By default, downloads are restricted to known secure protocols
220 (e.g. https, ssh). To override this setting for Git downloads, the
221 GIT_ALLOW_PROTOCOL environment variable can be set (For more details see:
222 'go help environment').
223
224 If the import path is not a known code hosting site and also lacks a
225 version control qualifier, the go tool attempts to fetch the import
226 over https/http and looks for a <meta> tag in the document's HTML
227 <head>.
228
229 The meta tag has the form:
230
231 <meta name="go-import" content="import-prefix vcs repo-root">
232
233 The import-prefix is the import path corresponding to the repository
234 root. It must be a prefix or an exact match of the package being
235 fetched with "go get". If it's not an exact match, another http
236 request is made at the prefix to verify the <meta> tags match.
237
238 The meta tag should appear as early in the file as possible.
239 In particular, it should appear before any raw JavaScript or CSS,
240 to avoid confusing the go command's restricted parser.
241
242 The vcs is one of "bzr", "fossil", "git", "hg", "svn".
243
244 The repo-root is the root of the version control system
245 containing a scheme and not containing a .vcs qualifier.
246
247 For example,
248
249 import "example.org/pkg/foo"
250
251 will result in the following requests:
252
253 https://example.org/pkg/foo?go-get=1 (preferred)
254 http://example.org/pkg/foo?go-get=1 (fallback, only with -insecure)
255
256 If that page contains the meta tag
257
258 <meta name="go-import" content="example.org git https://code.org/r/p/exproj">
259
260 the go tool will verify that https://example.org/?go-get=1 contains the
261 same meta tag and then git clone https://code.org/r/p/exproj into
262 GOPATH/src/example.org.
263
264 When using GOPATH, downloaded packages are written to the first directory
265 listed in the GOPATH environment variable.
266 (See 'go help gopath-get' and 'go help gopath'.)
267
268 When using modules, downloaded packages are stored in the module cache.
269 (See 'go help module-get' and 'go help goproxy'.)
270
271 When using modules, an additional variant of the go-import meta tag is
272 recognized and is preferred over those listing version control systems.
273 That variant uses "mod" as the vcs in the content value, as in:
274
275 <meta name="go-import" content="example.org mod https://code.org/moduleproxy">
276
277 This tag means to fetch modules with paths beginning with example.org
278 from the module proxy available at the URL https://code.org/moduleproxy.
279 See 'go help goproxy' for details about the proxy protocol.
280
281 Import path checking
282
283 When the custom import path feature described above redirects to a
284 known code hosting site, each of the resulting packages has two possible
285 import paths, using the custom domain or the known hosting site.
286
287 A package statement is said to have an "import comment" if it is immediately
288 followed (before the next newline) by a comment of one of these two forms:
289
290 package math // import "path"
291 package math /* import "path" */
292
293 The go command will refuse to install a package with an import comment
294 unless it is being referred to by that import path. In this way, import comments
295 let package authors make sure the custom import path is used and not a
296 direct path to the underlying code hosting site.
297
298 Import path checking is disabled for code found within vendor trees.
299 This makes it possible to copy code into alternate locations in vendor trees
300 without needing to update import comments.
301
302 Import path checking is also disabled when using modules.
303 Import path comments are obsoleted by the go.mod file's module statement.
304
305 See https://golang.org/s/go14customimport for details.
306 `,
307 }
308
309 var HelpGopath = &base.Command{
310 UsageLine: "gopath",
311 Short: "GOPATH environment variable",
312 Long: `
313 The Go path is used to resolve import statements.
314 It is implemented by and documented in the go/build package.
315
316 The GOPATH environment variable lists places to look for Go code.
317 On Unix, the value is a colon-separated string.
318 On Windows, the value is a semicolon-separated string.
319 On Plan 9, the value is a list.
320
321 If the environment variable is unset, GOPATH defaults
322 to a subdirectory named "go" in the user's home directory
323 ($HOME/go on Unix, %USERPROFILE%\go on Windows),
324 unless that directory holds a Go distribution.
325 Run "go env GOPATH" to see the current GOPATH.
326
327 See https://golang.org/wiki/SettingGOPATH to set a custom GOPATH.
328
329 Each directory listed in GOPATH must have a prescribed structure:
330
331 The src directory holds source code. The path below src
332 determines the import path or executable name.
333
334 The pkg directory holds installed package objects.
335 As in the Go tree, each target operating system and
336 architecture pair has its own subdirectory of pkg
337 (pkg/GOOS_GOARCH).
338
339 If DIR is a directory listed in the GOPATH, a package with
340 source in DIR/src/foo/bar can be imported as "foo/bar" and
341 has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a".
342
343 The bin directory holds compiled commands.
344 Each command is named for its source directory, but only
345 the final element, not the entire path. That is, the
346 command with source in DIR/src/foo/quux is installed into
347 DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped
348 so that you can add DIR/bin to your PATH to get at the
349 installed commands. If the GOBIN environment variable is
350 set, commands are installed to the directory it names instead
351 of DIR/bin. GOBIN must be an absolute path.
352
353 Here's an example directory layout:
354
355 GOPATH=/home/user/go
356
357 /home/user/go/
358 src/
359 foo/
360 bar/ (go code in package bar)
361 x.go
362 quux/ (go code in package main)
363 y.go
364 bin/
365 quux (installed command)
366 pkg/
367 linux_amd64/
368 foo/
369 bar.a (installed package object)
370
371 Go searches each directory listed in GOPATH to find source code,
372 but new packages are always downloaded into the first directory
373 in the list.
374
375 See https://golang.org/doc/code.html for an example.
376
377 GOPATH and Modules
378
379 When using modules, GOPATH is no longer used for resolving imports.
380 However, it is still used to store downloaded source code (in GOPATH/pkg/mod)
381 and compiled commands (in GOPATH/bin).
382
383 Internal Directories
384
385 Code in or below a directory named "internal" is importable only
386 by code in the directory tree rooted at the parent of "internal".
387 Here's an extended version of the directory layout above:
388
389 /home/user/go/
390 src/
391 crash/
392 bang/ (go code in package bang)
393 b.go
394 foo/ (go code in package foo)
395 f.go
396 bar/ (go code in package bar)
397 x.go
398 internal/
399 baz/ (go code in package baz)
400 z.go
401 quux/ (go code in package main)
402 y.go
403
404
405 The code in z.go is imported as "foo/internal/baz", but that
406 import statement can only appear in source files in the subtree
407 rooted at foo. The source files foo/f.go, foo/bar/x.go, and
408 foo/quux/y.go can all import "foo/internal/baz", but the source file
409 crash/bang/b.go cannot.
410
411 See https://golang.org/s/go14internal for details.
412
413 Vendor Directories
414
415 Go 1.6 includes support for using local copies of external dependencies
416 to satisfy imports of those dependencies, often referred to as vendoring.
417
418 Code below a directory named "vendor" is importable only
419 by code in the directory tree rooted at the parent of "vendor",
420 and only using an import path that omits the prefix up to and
421 including the vendor element.
422
423 Here's the example from the previous section,
424 but with the "internal" directory renamed to "vendor"
425 and a new foo/vendor/crash/bang directory added:
426
427 /home/user/go/
428 src/
429 crash/
430 bang/ (go code in package bang)
431 b.go
432 foo/ (go code in package foo)
433 f.go
434 bar/ (go code in package bar)
435 x.go
436 vendor/
437 crash/
438 bang/ (go code in package bang)
439 b.go
440 baz/ (go code in package baz)
441 z.go
442 quux/ (go code in package main)
443 y.go
444
445 The same visibility rules apply as for internal, but the code
446 in z.go is imported as "baz", not as "foo/vendor/baz".
447
448 Code in vendor directories deeper in the source tree shadows
449 code in higher directories. Within the subtree rooted at foo, an import
450 of "crash/bang" resolves to "foo/vendor/crash/bang", not the
451 top-level "crash/bang".
452
453 Code in vendor directories is not subject to import path
454 checking (see 'go help importpath').
455
456 When 'go get' checks out or updates a git repository, it now also
457 updates submodules.
458
459 Vendor directories do not affect the placement of new repositories
460 being checked out for the first time by 'go get': those are always
461 placed in the main GOPATH, never in a vendor subtree.
462
463 See https://golang.org/s/go15vendor for details.
464 `,
465 }
466
467 var HelpEnvironment = &base.Command{
468 UsageLine: "environment",
469 Short: "environment variables",
470 Long: `
471
472 The go command and the tools it invokes consult environment variables
473 for configuration. If an environment variable is unset, the go command
474 uses a sensible default setting. To see the effective setting of the
475 variable <NAME>, run 'go env <NAME>'. To change the default setting,
476 run 'go env -w <NAME>=<VALUE>'. Defaults changed using 'go env -w'
477 are recorded in a Go environment configuration file stored in the
478 per-user configuration directory, as reported by os.UserConfigDir.
479 The location of the configuration file can be changed by setting
480 the environment variable GOENV, and 'go env GOENV' prints the
481 effective location, but 'go env -w' cannot change the default location.
482 See 'go help env' for details.
483
484 General-purpose environment variables:
485
486 GCCGO
487 The gccgo command to run for 'go build -compiler=gccgo'.
488 GOARCH
489 The architecture, or processor, for which to compile code.
490 Examples are amd64, 386, arm, ppc64.
491 GOBIN
492 The directory where 'go install' will install a command.
493 GOCACHE
494 The directory where the go command will store cached
495 information for reuse in future builds.
496 GODEBUG
497 Enable various debugging facilities. See 'go doc runtime'
498 for details.
499 GOENV
500 The location of the Go environment configuration file.
501 Cannot be set using 'go env -w'.
502 GOFLAGS
503 A space-separated list of -flag=value settings to apply
504 to go commands by default, when the given flag is known by
505 the current command. Each entry must be a standalone flag.
506 Because the entries are space-separated, flag values must
507 not contain spaces. Flags listed on the command line
508 are applied after this list and therefore override it.
509 GOOS
510 The operating system for which to compile code.
511 Examples are linux, darwin, windows, netbsd.
512 GOPATH
513 For more details see: 'go help gopath'.
514 GOPROXY
515 URL of Go module proxy. See 'go help modules'.
516 GOPRIVATE, GONOPROXY, GONOSUMDB
517 Comma-separated list of glob patterns (in the syntax of Go's path.Match)
518 of module path prefixes that should always be fetched directly
519 or that should not be compared against the checksum database.
520 See 'go help module-private'.
521 GOROOT
522 The root of the go tree.
523 GOSUMDB
524 The name of checksum database to use and optionally its public key and
525 URL. See 'go help module-auth'.
526 GOTMPDIR
527 The directory where the go command will write
528 temporary source files, packages, and binaries.
529
530 Environment variables for use with cgo:
531
532 AR
533 The command to use to manipulate library archives when
534 building with the gccgo compiler.
535 The default is 'ar'.
536 CC
537 The command to use to compile C code.
538 CGO_ENABLED
539 Whether the cgo command is supported. Either 0 or 1.
540 CGO_CFLAGS
541 Flags that cgo will pass to the compiler when compiling
542 C code.
543 CGO_CFLAGS_ALLOW
544 A regular expression specifying additional flags to allow
545 to appear in #cgo CFLAGS source code directives.
546 Does not apply to the CGO_CFLAGS environment variable.
547 CGO_CFLAGS_DISALLOW
548 A regular expression specifying flags that must be disallowed
549 from appearing in #cgo CFLAGS source code directives.
550 Does not apply to the CGO_CFLAGS environment variable.
551 CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
552 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
553 but for the C preprocessor.
554 CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
555 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
556 but for the C++ compiler.
557 CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
558 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
559 but for the Fortran compiler.
560 CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
561 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
562 but for the linker.
563 CXX
564 The command to use to compile C++ code.
565 FC
566 The command to use to compile Fortran code.
567 PKG_CONFIG
568 Path to pkg-config tool.
569
570 Architecture-specific environment variables:
571
572 GOARM
573 For GOARCH=arm, the ARM architecture for which to compile.
574 Valid values are 5, 6, 7.
575 GO386
576 For GOARCH=386, the floating point instruction set.
577 Valid values are 387, sse2.
578 GOMIPS
579 For GOARCH=mips{,le}, whether to use floating point instructions.
580 Valid values are hardfloat (default), softfloat.
581 GOMIPS64
582 For GOARCH=mips64{,le}, whether to use floating point instructions.
583 Valid values are hardfloat (default), softfloat.
584 GOWASM
585 For GOARCH=wasm, comma-separated list of experimental WebAssembly features to use.
586 Valid values are satconv, signext.
587
588 Special-purpose environment variables:
589
590 GCCGOTOOLDIR
591 If set, where to find gccgo tools, such as cgo.
592 The default is based on how gccgo was configured.
593 GOROOT_FINAL
594 The root of the installed Go tree, when it is
595 installed in a location other than where it is built.
596 File names in stack traces are rewritten from GOROOT to
597 GOROOT_FINAL.
598 GO_EXTLINK_ENABLED
599 Whether the linker should use external linking mode
600 when using -linkmode=auto with code that uses cgo.
601 Set to 0 to disable external linking mode, 1 to enable it.
602 GIT_ALLOW_PROTOCOL
603 Defined by Git. A colon-separated list of schemes that are allowed
604 to be used with git fetch/clone. If set, any scheme not explicitly
605 mentioned will be considered insecure by 'go get'.
606 Because the variable is defined by Git, the default value cannot
607 be set using 'go env -w'.
608
609 Additional information available from 'go env' but not read from the environment:
610
611 GOEXE
612 The executable file name suffix (".exe" on Windows, "" on other systems).
613 GOGCCFLAGS
614 A space-separated list of arguments supplied to the CC command.
615 GOHOSTARCH
616 The architecture (GOARCH) of the Go toolchain binaries.
617 GOHOSTOS
618 The operating system (GOOS) of the Go toolchain binaries.
619 GOMOD
620 The absolute path to the go.mod of the main module,
621 or the empty string if not using modules.
622 GOTOOLDIR
623 The directory where the go tools (compile, cover, doc, etc...) are installed.
624 `,
625 }
626
627 var HelpFileType = &base.Command{
628 UsageLine: "filetype",
629 Short: "file types",
630 Long: `
631 The go command examines the contents of a restricted set of files
632 in each directory. It identifies which files to examine based on
633 the extension of the file name. These extensions are:
634
635 .go
636 Go source files.
637 .c, .h
638 C source files.
639 If the package uses cgo or SWIG, these will be compiled with the
640 OS-native compiler (typically gcc); otherwise they will
641 trigger an error.
642 .cc, .cpp, .cxx, .hh, .hpp, .hxx
643 C++ source files. Only useful with cgo or SWIG, and always
644 compiled with the OS-native compiler.
645 .m
646 Objective-C source files. Only useful with cgo, and always
647 compiled with the OS-native compiler.
648 .s, .S
649 Assembler source files.
650 If the package uses cgo or SWIG, these will be assembled with the
651 OS-native assembler (typically gcc (sic)); otherwise they
652 will be assembled with the Go assembler.
653 .swig, .swigcxx
654 SWIG definition files.
655 .syso
656 System object files.
657
658 Files of each of these types except .syso may contain build
659 constraints, but the go command stops scanning for build constraints
660 at the first item in the file that is not a blank line or //-style
661 line comment. See the go/build package documentation for
662 more details.
663 `,
664 }
665
666 var HelpBuildmode = &base.Command{
667 UsageLine: "buildmode",
668 Short: "build modes",
669 Long: `
670 The 'go build' and 'go install' commands take a -buildmode argument which
671 indicates which kind of object file is to be built. Currently supported values
672 are:
673
674 -buildmode=archive
675 Build the listed non-main packages into .a files. Packages named
676 main are ignored.
677
678 -buildmode=c-archive
679 Build the listed main package, plus all packages it imports,
680 into a C archive file. The only callable symbols will be those
681 functions exported using a cgo //export comment. Requires
682 exactly one main package to be listed.
683
684 -buildmode=c-shared
685 Build the listed main package, plus all packages it imports,
686 into a C shared library. The only callable symbols will
687 be those functions exported using a cgo //export comment.
688 Requires exactly one main package to be listed.
689
690 -buildmode=default
691 Listed main packages are built into executables and listed
692 non-main packages are built into .a files (the default
693 behavior).
694
695 -buildmode=shared
696 Combine all the listed non-main packages into a single shared
697 library that will be used when building with the -linkshared
698 option. Packages named main are ignored.
699
700 -buildmode=exe
701 Build the listed main packages and everything they import into
702 executables. Packages not named main are ignored.
703
704 -buildmode=pie
705 Build the listed main packages and everything they import into
706 position independent executables (PIE). Packages not named
707 main are ignored.
708
709 -buildmode=plugin
710 Build the listed main packages, plus all packages that they
711 import, into a Go plugin. Packages not named main are ignored.
712
713 On AIX, when linking a C program that uses a Go archive built with
714 -buildmode=c-archive, you must pass -Wl,-bnoobjreorder to the C compiler.
715 `,
716 }
717
718 var HelpCache = &base.Command{
719 UsageLine: "cache",
720 Short: "build and test caching",
721 Long: `
722 The go command caches build outputs for reuse in future builds.
723 The default location for cache data is a subdirectory named go-build
724 in the standard user cache directory for the current operating system.
725 Setting the GOCACHE environment variable overrides this default,
726 and running 'go env GOCACHE' prints the current cache directory.
727
728 The go command periodically deletes cached data that has not been
729 used recently. Running 'go clean -cache' deletes all cached data.
730
731 The build cache correctly accounts for changes to Go source files,
732 compilers, compiler options, and so on: cleaning the cache explicitly
733 should not be necessary in typical use. However, the build cache
734 does not detect changes to C libraries imported with cgo.
735 If you have made changes to the C libraries on your system, you
736 will need to clean the cache explicitly or else use the -a build flag
737 (see 'go help build') to force rebuilding of packages that
738 depend on the updated C libraries.
739
740 The go command also caches successful package test results.
741 See 'go help test' for details. Running 'go clean -testcache' removes
742 all cached test results (but not cached build results).
743
744 The GODEBUG environment variable can enable printing of debugging
745 information about the state of the cache:
746
747 GODEBUG=gocacheverify=1 causes the go command to bypass the
748 use of any cache entries and instead rebuild everything and check
749 that the results match existing cache entries.
750
751 GODEBUG=gocachehash=1 causes the go command to print the inputs
752 for all of the content hashes it uses to construct cache lookup keys.
753 The output is voluminous but can be useful for debugging the cache.
754
755 GODEBUG=gocachetest=1 causes the go command to print details of its
756 decisions about whether to reuse a cached test result.
757 `,
758 }
759
View as plain text