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, .S
25 or .sx 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 use of correctly set GOINSECURE)
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 https://golang.org/ref/mod#module-cache.
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 https://golang.org/ref/mod#goproxy-protocol for details about the
280 proxy protocol.
281
282 Import path checking
283
284 When the custom import path feature described above redirects to a
285 known code hosting site, each of the resulting packages has two possible
286 import paths, using the custom domain or the known hosting site.
287
288 A package statement is said to have an "import comment" if it is immediately
289 followed (before the next newline) by a comment of one of these two forms:
290
291 package math // import "path"
292 package math /* import "path" */
293
294 The go command will refuse to install a package with an import comment
295 unless it is being referred to by that import path. In this way, import comments
296 let package authors make sure the custom import path is used and not a
297 direct path to the underlying code hosting site.
298
299 Import path checking is disabled for code found within vendor trees.
300 This makes it possible to copy code into alternate locations in vendor trees
301 without needing to update import comments.
302
303 Import path checking is also disabled when using modules.
304 Import path comments are obsoleted by the go.mod file's module statement.
305
306 See https://golang.org/s/go14customimport for details.
307 `,
308 }
309
310 var HelpGopath = &base.Command{
311 UsageLine: "gopath",
312 Short: "GOPATH environment variable",
313 Long: `
314 The Go path is used to resolve import statements.
315 It is implemented by and documented in the go/build package.
316
317 The GOPATH environment variable lists places to look for Go code.
318 On Unix, the value is a colon-separated string.
319 On Windows, the value is a semicolon-separated string.
320 On Plan 9, the value is a list.
321
322 If the environment variable is unset, GOPATH defaults
323 to a subdirectory named "go" in the user's home directory
324 ($HOME/go on Unix, %USERPROFILE%\go on Windows),
325 unless that directory holds a Go distribution.
326 Run "go env GOPATH" to see the current GOPATH.
327
328 See https://golang.org/wiki/SettingGOPATH to set a custom GOPATH.
329
330 Each directory listed in GOPATH must have a prescribed structure:
331
332 The src directory holds source code. The path below src
333 determines the import path or executable name.
334
335 The pkg directory holds installed package objects.
336 As in the Go tree, each target operating system and
337 architecture pair has its own subdirectory of pkg
338 (pkg/GOOS_GOARCH).
339
340 If DIR is a directory listed in the GOPATH, a package with
341 source in DIR/src/foo/bar can be imported as "foo/bar" and
342 has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a".
343
344 The bin directory holds compiled commands.
345 Each command is named for its source directory, but only
346 the final element, not the entire path. That is, the
347 command with source in DIR/src/foo/quux is installed into
348 DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped
349 so that you can add DIR/bin to your PATH to get at the
350 installed commands. If the GOBIN environment variable is
351 set, commands are installed to the directory it names instead
352 of DIR/bin. GOBIN must be an absolute path.
353
354 Here's an example directory layout:
355
356 GOPATH=/home/user/go
357
358 /home/user/go/
359 src/
360 foo/
361 bar/ (go code in package bar)
362 x.go
363 quux/ (go code in package main)
364 y.go
365 bin/
366 quux (installed command)
367 pkg/
368 linux_amd64/
369 foo/
370 bar.a (installed package object)
371
372 Go searches each directory listed in GOPATH to find source code,
373 but new packages are always downloaded into the first directory
374 in the list.
375
376 See https://golang.org/doc/code.html for an example.
377
378 GOPATH and Modules
379
380 When using modules, GOPATH is no longer used for resolving imports.
381 However, it is still used to store downloaded source code (in GOPATH/pkg/mod)
382 and compiled commands (in GOPATH/bin).
383
384 Internal Directories
385
386 Code in or below a directory named "internal" is importable only
387 by code in the directory tree rooted at the parent of "internal".
388 Here's an extended version of the directory layout above:
389
390 /home/user/go/
391 src/
392 crash/
393 bang/ (go code in package bang)
394 b.go
395 foo/ (go code in package foo)
396 f.go
397 bar/ (go code in package bar)
398 x.go
399 internal/
400 baz/ (go code in package baz)
401 z.go
402 quux/ (go code in package main)
403 y.go
404
405
406 The code in z.go is imported as "foo/internal/baz", but that
407 import statement can only appear in source files in the subtree
408 rooted at foo. The source files foo/f.go, foo/bar/x.go, and
409 foo/quux/y.go can all import "foo/internal/baz", but the source file
410 crash/bang/b.go cannot.
411
412 See https://golang.org/s/go14internal for details.
413
414 Vendor Directories
415
416 Go 1.6 includes support for using local copies of external dependencies
417 to satisfy imports of those dependencies, often referred to as vendoring.
418
419 Code below a directory named "vendor" is importable only
420 by code in the directory tree rooted at the parent of "vendor",
421 and only using an import path that omits the prefix up to and
422 including the vendor element.
423
424 Here's the example from the previous section,
425 but with the "internal" directory renamed to "vendor"
426 and a new foo/vendor/crash/bang directory added:
427
428 /home/user/go/
429 src/
430 crash/
431 bang/ (go code in package bang)
432 b.go
433 foo/ (go code in package foo)
434 f.go
435 bar/ (go code in package bar)
436 x.go
437 vendor/
438 crash/
439 bang/ (go code in package bang)
440 b.go
441 baz/ (go code in package baz)
442 z.go
443 quux/ (go code in package main)
444 y.go
445
446 The same visibility rules apply as for internal, but the code
447 in z.go is imported as "baz", not as "foo/vendor/baz".
448
449 Code in vendor directories deeper in the source tree shadows
450 code in higher directories. Within the subtree rooted at foo, an import
451 of "crash/bang" resolves to "foo/vendor/crash/bang", not the
452 top-level "crash/bang".
453
454 Code in vendor directories is not subject to import path
455 checking (see 'go help importpath').
456
457 When 'go get' checks out or updates a git repository, it now also
458 updates submodules.
459
460 Vendor directories do not affect the placement of new repositories
461 being checked out for the first time by 'go get': those are always
462 placed in the main GOPATH, never in a vendor subtree.
463
464 See https://golang.org/s/go15vendor for details.
465 `,
466 }
467
468 var HelpEnvironment = &base.Command{
469 UsageLine: "environment",
470 Short: "environment variables",
471 Long: `
472
473 The go command and the tools it invokes consult environment variables
474 for configuration. If an environment variable is unset or empty, the go
475 command uses a sensible default setting. To see the effective setting of
476 the variable <NAME>, run 'go env <NAME>'. To change the default setting,
477 run 'go env -w <NAME>=<VALUE>'. Defaults changed using 'go env -w'
478 are recorded in a Go environment configuration file stored in the
479 per-user configuration directory, as reported by os.UserConfigDir.
480 The location of the configuration file can be changed by setting
481 the environment variable GOENV, and 'go env GOENV' prints the
482 effective location, but 'go env -w' cannot change the default location.
483 See 'go help env' for details.
484
485 General-purpose environment variables:
486
487 GO111MODULE
488 Controls whether the go command runs in module-aware mode or GOPATH mode.
489 May be "off", "on", or "auto".
490 See https://golang.org/ref/mod#mod-commands.
491 GCCGO
492 The gccgo command to run for 'go build -compiler=gccgo'.
493 GOARCH
494 The architecture, or processor, for which to compile code.
495 Examples are amd64, 386, arm, ppc64.
496 GOBIN
497 The directory where 'go install' will install a command.
498 GOCACHE
499 The directory where the go command will store cached
500 information for reuse in future builds.
501 GOMODCACHE
502 The directory where the go command will store downloaded modules.
503 GODEBUG
504 Enable various debugging facilities. See https://go.dev/doc/godebug
505 for details.
506 GOENV
507 The location of the Go environment configuration file.
508 Cannot be set using 'go env -w'.
509 Setting GOENV=off in the environment disables the use of the
510 default configuration file.
511 GOFLAGS
512 A space-separated list of -flag=value settings to apply
513 to go commands by default, when the given flag is known by
514 the current command. Each entry must be a standalone flag.
515 Because the entries are space-separated, flag values must
516 not contain spaces. Flags listed on the command line
517 are applied after this list and therefore override it.
518 GOINSECURE
519 Comma-separated list of glob patterns (in the syntax of Go's path.Match)
520 of module path prefixes that should always be fetched in an insecure
521 manner. Only applies to dependencies that are being fetched directly.
522 GOINSECURE does not disable checksum database validation. GOPRIVATE or
523 GONOSUMDB may be used to achieve that.
524 GOOS
525 The operating system for which to compile code.
526 Examples are linux, darwin, windows, netbsd.
527 GOPATH
528 Controls where various files are stored. See: 'go help gopath'.
529 GOPROXY
530 URL of Go module proxy. See https://golang.org/ref/mod#environment-variables
531 and https://golang.org/ref/mod#module-proxy for details.
532 GOPRIVATE, GONOPROXY, GONOSUMDB
533 Comma-separated list of glob patterns (in the syntax of Go's path.Match)
534 of module path prefixes that should always be fetched directly
535 or that should not be compared against the checksum database.
536 See https://golang.org/ref/mod#private-modules.
537 GOROOT
538 The root of the go tree.
539 GOSUMDB
540 The name of checksum database to use and optionally its public key and
541 URL. See https://golang.org/ref/mod#authenticating.
542 GOTOOLCHAIN
543 Controls which Go toolchain is used. See https://go.dev/doc/toolchain.
544 GOTMPDIR
545 The directory where the go command will write
546 temporary source files, packages, and binaries.
547 GOVCS
548 Lists version control commands that may be used with matching servers.
549 See 'go help vcs'.
550 GOWORK
551 In module aware mode, use the given go.work file as a workspace file.
552 By default or when GOWORK is "auto", the go command searches for a
553 file named go.work in the current directory and then containing directories
554 until one is found. If a valid go.work file is found, the modules
555 specified will collectively be used as the main modules. If GOWORK
556 is "off", or a go.work file is not found in "auto" mode, workspace
557 mode is disabled.
558
559 Environment variables for use with cgo:
560
561 AR
562 The command to use to manipulate library archives when
563 building with the gccgo compiler.
564 The default is 'ar'.
565 CC
566 The command to use to compile C code.
567 CGO_ENABLED
568 Whether the cgo command is supported. Either 0 or 1.
569 CGO_CFLAGS
570 Flags that cgo will pass to the compiler when compiling
571 C code.
572 CGO_CFLAGS_ALLOW
573 A regular expression specifying additional flags to allow
574 to appear in #cgo CFLAGS source code directives.
575 Does not apply to the CGO_CFLAGS environment variable.
576 CGO_CFLAGS_DISALLOW
577 A regular expression specifying flags that must be disallowed
578 from appearing in #cgo CFLAGS source code directives.
579 Does not apply to the CGO_CFLAGS environment variable.
580 CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
581 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
582 but for the C preprocessor.
583 CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
584 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
585 but for the C++ compiler.
586 CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
587 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
588 but for the Fortran compiler.
589 CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
590 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
591 but for the linker.
592 CXX
593 The command to use to compile C++ code.
594 FC
595 The command to use to compile Fortran code.
596 PKG_CONFIG
597 Path to pkg-config tool.
598
599 Architecture-specific environment variables:
600
601 GOARM
602 For GOARCH=arm, the ARM architecture for which to compile.
603 Valid values are 5, 6, 7.
604 The value can be followed by an option specifying how to implement floating point instructions.
605 Valid options are ,softfloat (default for 5) and ,hardfloat (default for 6 and 7).
606 GOARM64
607 For GOARCH=arm64, the ARM64 architecture for which to compile.
608 Valid values are v8.0 (default), v8.{1-9}, v9.{0-5}.
609 The value can be followed by an option specifying extensions implemented by target hardware.
610 Valid options are ,lse and ,crypto.
611 Note that some extensions are enabled by default starting from a certain GOARM64 version;
612 for example, lse is enabled by default starting from v8.1.
613 GO386
614 For GOARCH=386, how to implement floating point instructions.
615 Valid values are sse2 (default), softfloat.
616 GOAMD64
617 For GOARCH=amd64, the microarchitecture level for which to compile.
618 Valid values are v1 (default), v2, v3, v4.
619 See https://golang.org/wiki/MinimumRequirements#amd64
620 GOMIPS
621 For GOARCH=mips{,le}, whether to use floating point instructions.
622 Valid values are hardfloat (default), softfloat.
623 GOMIPS64
624 For GOARCH=mips64{,le}, whether to use floating point instructions.
625 Valid values are hardfloat (default), softfloat.
626 GOPPC64
627 For GOARCH=ppc64{,le}, the target ISA (Instruction Set Architecture).
628 Valid values are power8 (default), power9, power10.
629 GORISCV64
630 For GOARCH=riscv64, the RISC-V user-mode application profile for which
631 to compile. Valid values are rva20u64 (default), rva22u64.
632 See https://github.com/riscv/riscv-profiles/blob/main/src/profiles.adoc
633 GOWASM
634 For GOARCH=wasm, comma-separated list of experimental WebAssembly features to use.
635 Valid values are satconv, signext.
636
637 Environment variables for use with code coverage:
638
639 GOCOVERDIR
640 Directory into which to write code coverage data files
641 generated by running a "go build -cover" binary.
642 Requires that GOEXPERIMENT=coverageredesign is enabled.
643
644 Special-purpose environment variables:
645
646 GCCGOTOOLDIR
647 If set, where to find gccgo tools, such as cgo.
648 The default is based on how gccgo was configured.
649 GOEXPERIMENT
650 Comma-separated list of toolchain experiments to enable or disable.
651 The list of available experiments may change arbitrarily over time.
652 See src/internal/goexperiment/flags.go for currently valid values.
653 Warning: This variable is provided for the development and testing
654 of the Go toolchain itself. Use beyond that purpose is unsupported.
655 GO_EXTLINK_ENABLED
656 Whether the linker should use external linking mode
657 when using -linkmode=auto with code that uses cgo.
658 Set to 0 to disable external linking mode, 1 to enable it.
659 GIT_ALLOW_PROTOCOL
660 Defined by Git. A colon-separated list of schemes that are allowed
661 to be used with git fetch/clone. If set, any scheme not explicitly
662 mentioned will be considered insecure by 'go get'.
663 Because the variable is defined by Git, the default value cannot
664 be set using 'go env -w'.
665
666 Additional information available from 'go env' but not read from the environment:
667
668 GOEXE
669 The executable file name suffix (".exe" on Windows, "" on other systems).
670 GOGCCFLAGS
671 A space-separated list of arguments supplied to the CC command.
672 GOHOSTARCH
673 The architecture (GOARCH) of the Go toolchain binaries.
674 GOHOSTOS
675 The operating system (GOOS) of the Go toolchain binaries.
676 GOMOD
677 The absolute path to the go.mod of the main module.
678 If module-aware mode is enabled, but there is no go.mod, GOMOD will be
679 os.DevNull ("/dev/null" on Unix-like systems, "NUL" on Windows).
680 If module-aware mode is disabled, GOMOD will be the empty string.
681 GOTOOLDIR
682 The directory where the go tools (compile, cover, doc, etc...) are installed.
683 GOVERSION
684 The version of the installed Go tree, as reported by runtime.Version.
685 `,
686 }
687
688 var HelpFileType = &base.Command{
689 UsageLine: "filetype",
690 Short: "file types",
691 Long: `
692 The go command examines the contents of a restricted set of files
693 in each directory. It identifies which files to examine based on
694 the extension of the file name. These extensions are:
695
696 .go
697 Go source files.
698 .c, .h
699 C source files.
700 If the package uses cgo or SWIG, these will be compiled with the
701 OS-native compiler (typically gcc); otherwise they will
702 trigger an error.
703 .cc, .cpp, .cxx, .hh, .hpp, .hxx
704 C++ source files. Only useful with cgo or SWIG, and always
705 compiled with the OS-native compiler.
706 .m
707 Objective-C source files. Only useful with cgo, and always
708 compiled with the OS-native compiler.
709 .s, .S, .sx
710 Assembler source files.
711 If the package uses cgo or SWIG, these will be assembled with the
712 OS-native assembler (typically gcc (sic)); otherwise they
713 will be assembled with the Go assembler.
714 .swig, .swigcxx
715 SWIG definition files.
716 .syso
717 System object files.
718
719 Files of each of these types except .syso may contain build
720 constraints, but the go command stops scanning for build constraints
721 at the first item in the file that is not a blank line or //-style
722 line comment. See the go/build package documentation for
723 more details.
724 `,
725 }
726
727 var HelpBuildmode = &base.Command{
728 UsageLine: "buildmode",
729 Short: "build modes",
730 Long: `
731 The 'go build' and 'go install' commands take a -buildmode argument which
732 indicates which kind of object file is to be built. Currently supported values
733 are:
734
735 -buildmode=archive
736 Build the listed non-main packages into .a files. Packages named
737 main are ignored.
738
739 -buildmode=c-archive
740 Build the listed main package, plus all packages it imports,
741 into a C archive file. The only callable symbols will be those
742 functions exported using a cgo //export comment. Requires
743 exactly one main package to be listed.
744
745 -buildmode=c-shared
746 Build the listed main package, plus all packages it imports,
747 into a C shared library. The only callable symbols will
748 be those functions exported using a cgo //export comment.
749 Requires exactly one main package to be listed.
750
751 -buildmode=default
752 Listed main packages are built into executables and listed
753 non-main packages are built into .a files (the default
754 behavior).
755
756 -buildmode=shared
757 Combine all the listed non-main packages into a single shared
758 library that will be used when building with the -linkshared
759 option. Packages named main are ignored.
760
761 -buildmode=exe
762 Build the listed main packages and everything they import into
763 executables. Packages not named main are ignored.
764
765 -buildmode=pie
766 Build the listed main packages and everything they import into
767 position independent executables (PIE). Packages not named
768 main are ignored.
769
770 -buildmode=plugin
771 Build the listed main packages, plus all packages that they
772 import, into a Go plugin. Packages not named main are ignored.
773
774 On AIX, when linking a C program that uses a Go archive built with
775 -buildmode=c-archive, you must pass -Wl,-bnoobjreorder to the C compiler.
776 `,
777 }
778
779 var HelpCache = &base.Command{
780 UsageLine: "cache",
781 Short: "build and test caching",
782 Long: `
783 The go command caches build outputs for reuse in future builds.
784 The default location for cache data is a subdirectory named go-build
785 in the standard user cache directory for the current operating system.
786 Setting the GOCACHE environment variable overrides this default,
787 and running 'go env GOCACHE' prints the current cache directory.
788
789 The go command periodically deletes cached data that has not been
790 used recently. Running 'go clean -cache' deletes all cached data.
791
792 The build cache correctly accounts for changes to Go source files,
793 compilers, compiler options, and so on: cleaning the cache explicitly
794 should not be necessary in typical use. However, the build cache
795 does not detect changes to C libraries imported with cgo.
796 If you have made changes to the C libraries on your system, you
797 will need to clean the cache explicitly or else use the -a build flag
798 (see 'go help build') to force rebuilding of packages that
799 depend on the updated C libraries.
800
801 The go command also caches successful package test results.
802 See 'go help test' for details. Running 'go clean -testcache' removes
803 all cached test results (but not cached build results).
804
805 The go command also caches values used in fuzzing with 'go test -fuzz',
806 specifically, values that expanded code coverage when passed to a
807 fuzz function. These values are not used for regular building and
808 testing, but they're stored in a subdirectory of the build cache.
809 Running 'go clean -fuzzcache' removes all cached fuzzing values.
810 This may make fuzzing less effective, temporarily.
811
812 The GODEBUG environment variable can enable printing of debugging
813 information about the state of the cache:
814
815 GODEBUG=gocacheverify=1 causes the go command to bypass the
816 use of any cache entries and instead rebuild everything and check
817 that the results match existing cache entries.
818
819 GODEBUG=gocachehash=1 causes the go command to print the inputs
820 for all of the content hashes it uses to construct cache lookup keys.
821 The output is voluminous but can be useful for debugging the cache.
822
823 GODEBUG=gocachetest=1 causes the go command to print details of its
824 decisions about whether to reuse a cached test result.
825 `,
826 }
827
828 var HelpBuildConstraint = &base.Command{
829 UsageLine: "buildconstraint",
830 Short: "build constraints",
831 Long: `
832 A build constraint, also known as a build tag, is a condition under which a
833 file should be included in the package. Build constraints are given by a
834 line comment that begins
835
836 //go:build
837
838 Build constraints can also be used to downgrade the language version
839 used to compile a file.
840
841 Constraints may appear in any kind of source file (not just Go), but
842 they must appear near the top of the file, preceded
843 only by blank lines and other comments. These rules mean that in Go
844 files a build constraint must appear before the package clause.
845
846 To distinguish build constraints from package documentation,
847 a build constraint should be followed by a blank line.
848
849 A build constraint comment is evaluated as an expression containing
850 build tags combined by ||, &&, and ! operators and parentheses.
851 Operators have the same meaning as in Go.
852
853 For example, the following build constraint constrains a file to
854 build when the "linux" and "386" constraints are satisfied, or when
855 "darwin" is satisfied and "cgo" is not:
856
857 //go:build (linux && 386) || (darwin && !cgo)
858
859 It is an error for a file to have more than one //go:build line.
860
861 During a particular build, the following build tags are satisfied:
862
863 - the target operating system, as spelled by runtime.GOOS, set with the
864 GOOS environment variable.
865 - the target architecture, as spelled by runtime.GOARCH, set with the
866 GOARCH environment variable.
867 - any architecture features, in the form GOARCH.feature
868 (for example, "amd64.v2"), as detailed below.
869 - "unix", if GOOS is a Unix or Unix-like system.
870 - the compiler being used, either "gc" or "gccgo"
871 - "cgo", if the cgo command is supported (see CGO_ENABLED in
872 'go help environment').
873 - a term for each Go major release, through the current version:
874 "go1.1" from Go version 1.1 onward, "go1.12" from Go 1.12, and so on.
875 - any additional tags given by the -tags flag (see 'go help build').
876
877 There are no separate build tags for beta or minor releases.
878
879 If a file's name, after stripping the extension and a possible _test suffix,
880 matches any of the following patterns:
881 *_GOOS
882 *_GOARCH
883 *_GOOS_GOARCH
884 (example: source_windows_amd64.go) where GOOS and GOARCH represent
885 any known operating system and architecture values respectively, then
886 the file is considered to have an implicit build constraint requiring
887 those terms (in addition to any explicit constraints in the file).
888
889 Using GOOS=android matches build tags and files as for GOOS=linux
890 in addition to android tags and files.
891
892 Using GOOS=illumos matches build tags and files as for GOOS=solaris
893 in addition to illumos tags and files.
894
895 Using GOOS=ios matches build tags and files as for GOOS=darwin
896 in addition to ios tags and files.
897
898 The defined architecture feature build tags are:
899
900 - For GOARCH=386, GO386=387 and GO386=sse2
901 set the 386.387 and 386.sse2 build tags, respectively.
902 - For GOARCH=amd64, GOAMD64=v1, v2, and v3
903 correspond to the amd64.v1, amd64.v2, and amd64.v3 feature build tags.
904 - For GOARCH=arm, GOARM=5, 6, and 7
905 correspond to the arm.5, arm.6, and arm.7 feature build tags.
906 - For GOARCH=arm64, GOARM64=v8.{0-9} and v9.{0-5}
907 correspond to the arm64.v8.{0-9} and arm64.v9.{0-5} feature build tags.
908 - For GOARCH=mips or mipsle,
909 GOMIPS=hardfloat and softfloat
910 correspond to the mips.hardfloat and mips.softfloat
911 (or mipsle.hardfloat and mipsle.softfloat) feature build tags.
912 - For GOARCH=mips64 or mips64le,
913 GOMIPS64=hardfloat and softfloat
914 correspond to the mips64.hardfloat and mips64.softfloat
915 (or mips64le.hardfloat and mips64le.softfloat) feature build tags.
916 - For GOARCH=ppc64 or ppc64le,
917 GOPPC64=power8, power9, and power10 correspond to the
918 ppc64.power8, ppc64.power9, and ppc64.power10
919 (or ppc64le.power8, ppc64le.power9, and ppc64le.power10)
920 feature build tags.
921 - For GOARCH=riscv64,
922 GORISCV64=rva20u64 and rva22u64 correspond to the riscv64.rva20u64
923 and riscv64.rva22u64 build tags.
924 - For GOARCH=wasm, GOWASM=satconv and signext
925 correspond to the wasm.satconv and wasm.signext feature build tags.
926
927 For GOARCH=amd64, arm, ppc64, ppc64le, and riscv64, a particular feature level
928 sets the feature build tags for all previous levels as well.
929 For example, GOAMD64=v2 sets the amd64.v1 and amd64.v2 feature flags.
930 This ensures that code making use of v2 features continues to compile
931 when, say, GOAMD64=v4 is introduced.
932 Code handling the absence of a particular feature level
933 should use a negation:
934
935 //go:build !amd64.v2
936
937 To keep a file from being considered for any build:
938
939 //go:build ignore
940
941 (Any other unsatisfied word will work as well, but "ignore" is conventional.)
942
943 To build a file only when using cgo, and only on Linux and OS X:
944
945 //go:build cgo && (linux || darwin)
946
947 Such a file is usually paired with another file implementing the
948 default functionality for other systems, which in this case would
949 carry the constraint:
950
951 //go:build !(cgo && (linux || darwin))
952
953 Naming a file dns_windows.go will cause it to be included only when
954 building the package for Windows; similarly, math_386.s will be included
955 only when building the package for 32-bit x86.
956
957 Go versions 1.16 and earlier used a different syntax for build constraints,
958 with a "// +build" prefix. The gofmt command will add an equivalent //go:build
959 constraint when encountering the older syntax.
960
961 In modules with a Go version of 1.21 or later, if a file's build constraint
962 has a term for a Go major release, the language version used when compiling
963 the file will be the minimum version implied by the build constraint.
964 `,
965 }
966
View as plain text