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 in the main module (or workspace modules) and
58 their dependencies, including dependencies needed by tests of any of those. In
59 GOPATH mode, "all" expands to all packages found in all the GOPATH trees.
60
61 - "std" is like all but expands to just the packages in the standard
62 Go library.
63
64 - "cmd" expands to the Go repository's commands and their
65 internal libraries.
66
67 Package names match against fully-qualified import paths or patterns that
68 match against any number of import paths. For instance, "fmt" refers to the
69 standard library's package fmt, but "http" alone for package http would not
70 match the import path "net/http" from the standard library. Instead, the
71 complete import path "net/http" must be used.
72
73 Import paths beginning with "cmd/" only match source code in
74 the Go repository.
75
76 An import path is a pattern if it includes one or more "..." wildcards,
77 each of which can match any string, including the empty string and
78 strings containing slashes. Such a pattern expands to all package
79 directories found in the GOPATH trees with names matching the
80 patterns.
81
82 To make common patterns more convenient, there are two special cases.
83 First, /... at the end of the pattern can match an empty string,
84 so that net/... matches both net and packages in its subdirectories, like net/http.
85 Second, any slash-separated pattern element containing a wildcard never
86 participates in a match of the "vendor" element in the path of a vendored
87 package, so that ./... does not match packages in subdirectories of
88 ./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do.
89 Note, however, that a directory named vendor that itself contains code
90 is not a vendored package: cmd/vendor would be a command named vendor,
91 and the pattern cmd/... matches it.
92 See golang.org/s/go15vendor for more about vendoring.
93
94 An import path can also name a package to be downloaded from
95 a remote repository. Run 'go help importpath' for details.
96
97 Every package in a program must have a unique import path.
98 By convention, this is arranged by starting each path with a
99 unique prefix that belongs to you. For example, paths used
100 internally at Google all begin with 'google', and paths
101 denoting remote repositories begin with the path to the code,
102 such as 'github.com/user/repo'. Package patterns should include this prefix.
103 For instance, a package called 'http' residing under 'github.com/user/repo',
104 would be addressed with the fully-qualified pattern:
105 'github.com/user/repo/http'.
106
107 Packages in a program need not have unique package names,
108 but there are two reserved package names with special meaning.
109 The name main indicates a command, not a library.
110 Commands are built into binaries and cannot be imported.
111 The name documentation indicates documentation for
112 a non-Go program in the directory. Files in package documentation
113 are ignored by the go command.
114
115 As a special case, if the package list is a list of .go files from a
116 single directory, the command is applied to a single synthesized
117 package made up of exactly those files, ignoring any build constraints
118 in those files and ignoring any other files in the directory.
119
120 Directory and file names that begin with "." or "_" are ignored
121 by the go tool, as are directories named "testdata".
122 `,
123 }
124
125 var HelpImportPath = &base.Command{
126 UsageLine: "importpath",
127 Short: "import path syntax",
128 Long: `
129
130 An import path (see 'go help packages') denotes a package stored in the local
131 file system. In general, an import path denotes either a standard package (such
132 as "unicode/utf8") or a package found in one of the work spaces (For more
133 details see: 'go help gopath').
134
135 Relative import paths
136
137 An import path beginning with ./ or ../ is called a relative path.
138 The toolchain supports relative import paths as a shortcut in two ways.
139
140 First, a relative path can be used as a shorthand on the command line.
141 If you are working in the directory containing the code imported as
142 "unicode" and want to run the tests for "unicode/utf8", you can type
143 "go test ./utf8" instead of needing to specify the full path.
144 Similarly, in the reverse situation, "go test .." will test "unicode" from
145 the "unicode/utf8" directory. Relative patterns are also allowed, like
146 "go test ./..." to test all subdirectories. See 'go help packages' for details
147 on the pattern syntax.
148
149 Second, if you are compiling a Go program not in a work space,
150 you can use a relative path in an import statement in that program
151 to refer to nearby code also not in a work space.
152 This makes it easy to experiment with small multipackage programs
153 outside of the usual work spaces, but such programs cannot be
154 installed with "go install" (there is no work space in which to install them),
155 so they are rebuilt from scratch each time they are built.
156 To avoid ambiguity, Go programs cannot use relative import paths
157 within a work space.
158
159 Remote import paths
160
161 Certain import paths also
162 describe how to obtain the source code for the package using
163 a revision control system.
164
165 A few common code hosting sites have special syntax:
166
167 Bitbucket (Git, Mercurial)
168
169 import "bitbucket.org/user/project"
170 import "bitbucket.org/user/project/sub/directory"
171
172 GitHub (Git)
173
174 import "github.com/user/project"
175 import "github.com/user/project/sub/directory"
176
177 Launchpad (Bazaar)
178
179 import "launchpad.net/project"
180 import "launchpad.net/project/series"
181 import "launchpad.net/project/series/sub/directory"
182
183 import "launchpad.net/~user/project/branch"
184 import "launchpad.net/~user/project/branch/sub/directory"
185
186 IBM DevOps Services (Git)
187
188 import "hub.jazz.net/git/user/project"
189 import "hub.jazz.net/git/user/project/sub/directory"
190
191 For code hosted on other servers, import paths may either be qualified
192 with the version control type, or the go tool can dynamically fetch
193 the import path over https/http and discover where the code resides
194 from a <meta> tag in the HTML.
195
196 To declare the code location, an import path of the form
197
198 repository.vcs/path
199
200 specifies the given repository, with or without the .vcs suffix,
201 using the named version control system, and then the path inside
202 that repository. The supported version control systems are:
203
204 Bazaar .bzr
205 Fossil .fossil
206 Git .git
207 Mercurial .hg
208 Subversion .svn
209
210 For example,
211
212 import "example.org/user/foo.hg"
213
214 denotes the root directory of the Mercurial repository at
215 example.org/user/foo or foo.hg, and
216
217 import "example.org/repo.git/foo/bar"
218
219 denotes the foo/bar directory of the Git repository at
220 example.org/repo or repo.git.
221
222 When a version control system supports multiple protocols,
223 each is tried in turn when downloading. For example, a Git
224 download tries https://, then git+ssh://.
225
226 By default, downloads are restricted to known secure protocols
227 (e.g. https, ssh). To override this setting for Git downloads, the
228 GIT_ALLOW_PROTOCOL environment variable can be set (For more details see:
229 'go help environment').
230
231 If the import path is not a known code hosting site and also lacks a
232 version control qualifier, the go tool attempts to fetch the import
233 over https/http and looks for a <meta> tag in the document's HTML
234 <head>.
235
236 The meta tag has the form:
237
238 <meta name="go-import" content="import-prefix vcs repo-root">
239
240 The import-prefix is the import path corresponding to the repository
241 root. It must be a prefix or an exact match of the package being
242 fetched with "go get". If it's not an exact match, another http
243 request is made at the prefix to verify the <meta> tags match.
244
245 The meta tag should appear as early in the file as possible.
246 In particular, it should appear before any raw JavaScript or CSS,
247 to avoid confusing the go command's restricted parser.
248
249 The vcs is one of "bzr", "fossil", "git", "hg", "svn".
250
251 The repo-root is the root of the version control system
252 containing a scheme and not containing a .vcs qualifier.
253
254 For example,
255
256 import "example.org/pkg/foo"
257
258 will result in the following requests:
259
260 https://example.org/pkg/foo?go-get=1 (preferred)
261 http://example.org/pkg/foo?go-get=1 (fallback, only with use of correctly set GOINSECURE)
262
263 If that page contains the meta tag
264
265 <meta name="go-import" content="example.org git https://code.org/r/p/exproj">
266
267 the go tool will verify that https://example.org/?go-get=1 contains the
268 same meta tag and then git clone https://code.org/r/p/exproj into
269 GOPATH/src/example.org.
270
271 When using GOPATH, downloaded packages are written to the first directory
272 listed in the GOPATH environment variable.
273 (See 'go help gopath-get' and 'go help gopath'.)
274
275 When using modules, downloaded packages are stored in the module cache.
276 See https://golang.org/ref/mod#module-cache.
277
278 When using modules, an additional variant of the go-import meta tag is
279 recognized and is preferred over those listing version control systems.
280 That variant uses "mod" as the vcs in the content value, as in:
281
282 <meta name="go-import" content="example.org mod https://code.org/moduleproxy">
283
284 This tag means to fetch modules with paths beginning with example.org
285 from the module proxy available at the URL https://code.org/moduleproxy.
286 See https://golang.org/ref/mod#goproxy-protocol for details about the
287 proxy protocol.
288
289 Import path checking
290
291 When the custom import path feature described above redirects to a
292 known code hosting site, each of the resulting packages has two possible
293 import paths, using the custom domain or the known hosting site.
294
295 A package statement is said to have an "import comment" if it is immediately
296 followed (before the next newline) by a comment of one of these two forms:
297
298 package math // import "path"
299 package math /* import "path" */
300
301 The go command will refuse to install a package with an import comment
302 unless it is being referred to by that import path. In this way, import comments
303 let package authors make sure the custom import path is used and not a
304 direct path to the underlying code hosting site.
305
306 Import path checking is disabled for code found within vendor trees.
307 This makes it possible to copy code into alternate locations in vendor trees
308 without needing to update import comments.
309
310 Import path checking is also disabled when using modules.
311 Import path comments are obsoleted by the go.mod file's module statement.
312
313 See https://golang.org/s/go14customimport for details.
314 `,
315 }
316
317 var HelpGopath = &base.Command{
318 UsageLine: "gopath",
319 Short: "GOPATH environment variable",
320 Long: `
321 The Go path is used to resolve import statements.
322 It is implemented by and documented in the go/build package.
323
324 The GOPATH environment variable lists places to look for Go code.
325 On Unix, the value is a colon-separated string.
326 On Windows, the value is a semicolon-separated string.
327 On Plan 9, the value is a list.
328
329 If the environment variable is unset, GOPATH defaults
330 to a subdirectory named "go" in the user's home directory
331 ($HOME/go on Unix, %USERPROFILE%\go on Windows),
332 unless that directory holds a Go distribution.
333 Run "go env GOPATH" to see the current GOPATH.
334
335 See https://golang.org/wiki/SettingGOPATH to set a custom GOPATH.
336
337 Each directory listed in GOPATH must have a prescribed structure:
338
339 The src directory holds source code. The path below src
340 determines the import path or executable name.
341
342 The pkg directory holds installed package objects.
343 As in the Go tree, each target operating system and
344 architecture pair has its own subdirectory of pkg
345 (pkg/GOOS_GOARCH).
346
347 If DIR is a directory listed in the GOPATH, a package with
348 source in DIR/src/foo/bar can be imported as "foo/bar" and
349 has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a".
350
351 The bin directory holds compiled commands.
352 Each command is named for its source directory, but only
353 the final element, not the entire path. That is, the
354 command with source in DIR/src/foo/quux is installed into
355 DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped
356 so that you can add DIR/bin to your PATH to get at the
357 installed commands. If the GOBIN environment variable is
358 set, commands are installed to the directory it names instead
359 of DIR/bin. GOBIN must be an absolute path.
360
361 Here's an example directory layout:
362
363 GOPATH=/home/user/go
364
365 /home/user/go/
366 src/
367 foo/
368 bar/ (go code in package bar)
369 x.go
370 quux/ (go code in package main)
371 y.go
372 bin/
373 quux (installed command)
374 pkg/
375 linux_amd64/
376 foo/
377 bar.a (installed package object)
378
379 Go searches each directory listed in GOPATH to find source code,
380 but new packages are always downloaded into the first directory
381 in the list.
382
383 See https://golang.org/doc/code.html for an example.
384
385 GOPATH and Modules
386
387 When using modules, GOPATH is no longer used for resolving imports.
388 However, it is still used to store downloaded source code (in GOPATH/pkg/mod)
389 and compiled commands (in GOPATH/bin).
390
391 Internal Directories
392
393 Code in or below a directory named "internal" is importable only
394 by code in the directory tree rooted at the parent of "internal".
395 Here's an extended version of the directory layout above:
396
397 /home/user/go/
398 src/
399 crash/
400 bang/ (go code in package bang)
401 b.go
402 foo/ (go code in package foo)
403 f.go
404 bar/ (go code in package bar)
405 x.go
406 internal/
407 baz/ (go code in package baz)
408 z.go
409 quux/ (go code in package main)
410 y.go
411
412
413 The code in z.go is imported as "foo/internal/baz", but that
414 import statement can only appear in source files in the subtree
415 rooted at foo. The source files foo/f.go, foo/bar/x.go, and
416 foo/quux/y.go can all import "foo/internal/baz", but the source file
417 crash/bang/b.go cannot.
418
419 See https://golang.org/s/go14internal for details.
420
421 Vendor Directories
422
423 Go 1.6 includes support for using local copies of external dependencies
424 to satisfy imports of those dependencies, often referred to as vendoring.
425
426 Code below a directory named "vendor" is importable only
427 by code in the directory tree rooted at the parent of "vendor",
428 and only using an import path that omits the prefix up to and
429 including the vendor element.
430
431 Here's the example from the previous section,
432 but with the "internal" directory renamed to "vendor"
433 and a new foo/vendor/crash/bang directory added:
434
435 /home/user/go/
436 src/
437 crash/
438 bang/ (go code in package bang)
439 b.go
440 foo/ (go code in package foo)
441 f.go
442 bar/ (go code in package bar)
443 x.go
444 vendor/
445 crash/
446 bang/ (go code in package bang)
447 b.go
448 baz/ (go code in package baz)
449 z.go
450 quux/ (go code in package main)
451 y.go
452
453 The same visibility rules apply as for internal, but the code
454 in z.go is imported as "baz", not as "foo/vendor/baz".
455
456 Code in vendor directories deeper in the source tree shadows
457 code in higher directories. Within the subtree rooted at foo, an import
458 of "crash/bang" resolves to "foo/vendor/crash/bang", not the
459 top-level "crash/bang".
460
461 Code in vendor directories is not subject to import path
462 checking (see 'go help importpath').
463
464 When 'go get' checks out or updates a git repository, it now also
465 updates submodules.
466
467 Vendor directories do not affect the placement of new repositories
468 being checked out for the first time by 'go get': those are always
469 placed in the main GOPATH, never in a vendor subtree.
470
471 See https://golang.org/s/go15vendor for details.
472 `,
473 }
474
475 var HelpEnvironment = &base.Command{
476 UsageLine: "environment",
477 Short: "environment variables",
478 Long: `
479
480 The go command and the tools it invokes consult environment variables
481 for configuration. If an environment variable is unset or empty, the go
482 command uses a sensible default setting. To see the effective setting of
483 the variable <NAME>, run 'go env <NAME>'. To change the default setting,
484 run 'go env -w <NAME>=<VALUE>'. Defaults changed using 'go env -w'
485 are recorded in a Go environment configuration file stored in the
486 per-user configuration directory, as reported by os.UserConfigDir.
487 The location of the configuration file can be changed by setting
488 the environment variable GOENV, and 'go env GOENV' prints the
489 effective location, but 'go env -w' cannot change the default location.
490 See 'go help env' for details.
491
492 General-purpose environment variables:
493
494 GO111MODULE
495 Controls whether the go command runs in module-aware mode or GOPATH mode.
496 May be "off", "on", or "auto".
497 See https://golang.org/ref/mod#mod-commands.
498 GCCGO
499 The gccgo command to run for 'go build -compiler=gccgo'.
500 GOARCH
501 The architecture, or processor, for which to compile code.
502 Examples are amd64, 386, arm, ppc64.
503 GOAUTH
504 A semicolon-separated list of authentication commands for go-import and
505 HTTPS module mirror interactions. Currently supports
506 "off" (disables authentication),
507 "netrc" (uses credentials from NETRC or the .netrc file in your home directory),
508 "git dir" (runs 'git credential fill' in dir and uses its credentials).
509 The default is netrc.
510 GOBIN
511 The directory where 'go install' will install a command.
512 GOCACHE
513 The directory where the go command will store cached
514 information for reuse in future builds.
515 GOMODCACHE
516 The directory where the go command will store downloaded modules.
517 GODEBUG
518 Enable various debugging facilities. See https://go.dev/doc/godebug
519 for details.
520 GOENV
521 The location of the Go environment configuration file.
522 Cannot be set using 'go env -w'.
523 Setting GOENV=off in the environment disables the use of the
524 default configuration file.
525 GOFLAGS
526 A space-separated list of -flag=value settings to apply
527 to go commands by default, when the given flag is known by
528 the current command. Each entry must be a standalone flag.
529 Because the entries are space-separated, flag values must
530 not contain spaces. Flags listed on the command line
531 are applied after this list and therefore override it.
532 GOINSECURE
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 in an insecure
535 manner. Only applies to dependencies that are being fetched directly.
536 GOINSECURE does not disable checksum database validation. GOPRIVATE or
537 GONOSUMDB may be used to achieve that.
538 GOOS
539 The operating system for which to compile code.
540 Examples are linux, darwin, windows, netbsd.
541 GOPATH
542 Controls where various files are stored. See: 'go help gopath'.
543 GOPROXY
544 URL of Go module proxy. See https://golang.org/ref/mod#environment-variables
545 and https://golang.org/ref/mod#module-proxy for details.
546 GOPRIVATE, GONOPROXY, GONOSUMDB
547 Comma-separated list of glob patterns (in the syntax of Go's path.Match)
548 of module path prefixes that should always be fetched directly
549 or that should not be compared against the checksum database.
550 See https://golang.org/ref/mod#private-modules.
551 GOROOT
552 The root of the go tree.
553 GOSUMDB
554 The name of checksum database to use and optionally its public key and
555 URL. See https://golang.org/ref/mod#authenticating.
556 GOTOOLCHAIN
557 Controls which Go toolchain is used. See https://go.dev/doc/toolchain.
558 GOTMPDIR
559 The directory where the go command will write
560 temporary source files, packages, and binaries.
561 GOVCS
562 Lists version control commands that may be used with matching servers.
563 See 'go help vcs'.
564 GOWORK
565 In module aware mode, use the given go.work file as a workspace file.
566 By default or when GOWORK is "auto", the go command searches for a
567 file named go.work in the current directory and then containing directories
568 until one is found. If a valid go.work file is found, the modules
569 specified will collectively be used as the main modules. If GOWORK
570 is "off", or a go.work file is not found in "auto" mode, workspace
571 mode is disabled.
572
573 Environment variables for use with cgo:
574
575 AR
576 The command to use to manipulate library archives when
577 building with the gccgo compiler.
578 The default is 'ar'.
579 CC
580 The command to use to compile C code.
581 CGO_ENABLED
582 Whether the cgo command is supported. Either 0 or 1.
583 CGO_CFLAGS
584 Flags that cgo will pass to the compiler when compiling
585 C code.
586 CGO_CFLAGS_ALLOW
587 A regular expression specifying additional flags to allow
588 to appear in #cgo CFLAGS source code directives.
589 Does not apply to the CGO_CFLAGS environment variable.
590 CGO_CFLAGS_DISALLOW
591 A regular expression specifying flags that must be disallowed
592 from appearing in #cgo CFLAGS source code directives.
593 Does not apply to the CGO_CFLAGS environment variable.
594 CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
595 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
596 but for the C preprocessor.
597 CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
598 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
599 but for the C++ compiler.
600 CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
601 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
602 but for the Fortran compiler.
603 CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
604 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
605 but for the linker.
606 CXX
607 The command to use to compile C++ code.
608 FC
609 The command to use to compile Fortran code.
610 PKG_CONFIG
611 Path to pkg-config tool.
612
613 Architecture-specific environment variables:
614
615 GOARM
616 For GOARCH=arm, the ARM architecture for which to compile.
617 Valid values are 5, 6, 7.
618 The value can be followed by an option specifying how to implement floating point instructions.
619 Valid options are ,softfloat (default for 5) and ,hardfloat (default for 6 and 7).
620 GOARM64
621 For GOARCH=arm64, the ARM64 architecture for which to compile.
622 Valid values are v8.0 (default), v8.{1-9}, v9.{0-5}.
623 The value can be followed by an option specifying extensions implemented by target hardware.
624 Valid options are ,lse and ,crypto.
625 Note that some extensions are enabled by default starting from a certain GOARM64 version;
626 for example, lse is enabled by default starting from v8.1.
627 GO386
628 For GOARCH=386, how to implement floating point instructions.
629 Valid values are sse2 (default), softfloat.
630 GOAMD64
631 For GOARCH=amd64, the microarchitecture level for which to compile.
632 Valid values are v1 (default), v2, v3, v4.
633 See https://golang.org/wiki/MinimumRequirements#amd64
634 GOMIPS
635 For GOARCH=mips{,le}, whether to use floating point instructions.
636 Valid values are hardfloat (default), softfloat.
637 GOMIPS64
638 For GOARCH=mips64{,le}, whether to use floating point instructions.
639 Valid values are hardfloat (default), softfloat.
640 GOPPC64
641 For GOARCH=ppc64{,le}, the target ISA (Instruction Set Architecture).
642 Valid values are power8 (default), power9, power10.
643 GORISCV64
644 For GOARCH=riscv64, the RISC-V user-mode application profile for which
645 to compile. Valid values are rva20u64 (default), rva22u64.
646 See https://github.com/riscv/riscv-profiles/blob/main/src/profiles.adoc
647 GOWASM
648 For GOARCH=wasm, comma-separated list of experimental WebAssembly features to use.
649 Valid values are satconv, signext.
650
651 Environment variables for use with code coverage:
652
653 GOCOVERDIR
654 Directory into which to write code coverage data files
655 generated by running a "go build -cover" binary.
656 Requires that GOEXPERIMENT=coverageredesign is enabled.
657
658 Special-purpose environment variables:
659
660 GCCGOTOOLDIR
661 If set, where to find gccgo tools, such as cgo.
662 The default is based on how gccgo was configured.
663 GOEXPERIMENT
664 Comma-separated list of toolchain experiments to enable or disable.
665 The list of available experiments may change arbitrarily over time.
666 See src/internal/goexperiment/flags.go for currently valid values.
667 Warning: This variable is provided for the development and testing
668 of the Go toolchain itself. Use beyond that purpose is unsupported.
669 GO_EXTLINK_ENABLED
670 Whether the linker should use external linking mode
671 when using -linkmode=auto with code that uses cgo.
672 Set to 0 to disable external linking mode, 1 to enable it.
673 GIT_ALLOW_PROTOCOL
674 Defined by Git. A colon-separated list of schemes that are allowed
675 to be used with git fetch/clone. If set, any scheme not explicitly
676 mentioned will be considered insecure by 'go get'.
677 Because the variable is defined by Git, the default value cannot
678 be set using 'go env -w'.
679
680 Additional information available from 'go env' but not read from the environment:
681
682 GOEXE
683 The executable file name suffix (".exe" on Windows, "" on other systems).
684 GOGCCFLAGS
685 A space-separated list of arguments supplied to the CC command.
686 GOHOSTARCH
687 The architecture (GOARCH) of the Go toolchain binaries.
688 GOHOSTOS
689 The operating system (GOOS) of the Go toolchain binaries.
690 GOMOD
691 The absolute path to the go.mod of the main module.
692 If module-aware mode is enabled, but there is no go.mod, GOMOD will be
693 os.DevNull ("/dev/null" on Unix-like systems, "NUL" on Windows).
694 If module-aware mode is disabled, GOMOD will be the empty string.
695 GOTELEMETRY
696 The current Go telemetry mode ("off", "local", or "on").
697 See "go help telemetry" for more information.
698 GOTELEMETRYDIR
699 The directory Go telemetry data is written is written to.
700 GOTOOLDIR
701 The directory where the go tools (compile, cover, doc, etc...) are installed.
702 GOVERSION
703 The version of the installed Go tree, as reported by runtime.Version.
704 `,
705 }
706
707 var HelpFileType = &base.Command{
708 UsageLine: "filetype",
709 Short: "file types",
710 Long: `
711 The go command examines the contents of a restricted set of files
712 in each directory. It identifies which files to examine based on
713 the extension of the file name. These extensions are:
714
715 .go
716 Go source files.
717 .c, .h
718 C source files.
719 If the package uses cgo or SWIG, these will be compiled with the
720 OS-native compiler (typically gcc); otherwise they will
721 trigger an error.
722 .cc, .cpp, .cxx, .hh, .hpp, .hxx
723 C++ source files. Only useful with cgo or SWIG, and always
724 compiled with the OS-native compiler.
725 .m
726 Objective-C source files. Only useful with cgo, and always
727 compiled with the OS-native compiler.
728 .s, .S, .sx
729 Assembler source files.
730 If the package uses cgo or SWIG, these will be assembled with the
731 OS-native assembler (typically gcc (sic)); otherwise they
732 will be assembled with the Go assembler.
733 .swig, .swigcxx
734 SWIG definition files.
735 .syso
736 System object files.
737
738 Files of each of these types except .syso may contain build
739 constraints, but the go command stops scanning for build constraints
740 at the first item in the file that is not a blank line or //-style
741 line comment. See the go/build package documentation for
742 more details.
743 `,
744 }
745
746 var HelpBuildmode = &base.Command{
747 UsageLine: "buildmode",
748 Short: "build modes",
749 Long: `
750 The 'go build' and 'go install' commands take a -buildmode argument which
751 indicates which kind of object file is to be built. Currently supported values
752 are:
753
754 -buildmode=archive
755 Build the listed non-main packages into .a files. Packages named
756 main are ignored.
757
758 -buildmode=c-archive
759 Build the listed main package, plus all packages it imports,
760 into a C archive file. The only callable symbols will be those
761 functions exported using a cgo //export comment. Requires
762 exactly one main package to be listed.
763
764 -buildmode=c-shared
765 Build the listed main package, plus all packages it imports,
766 into a C shared library. The only callable symbols will
767 be those functions exported using a cgo //export comment.
768 Requires exactly one main package to be listed.
769
770 -buildmode=default
771 Listed main packages are built into executables and listed
772 non-main packages are built into .a files (the default
773 behavior).
774
775 -buildmode=shared
776 Combine all the listed non-main packages into a single shared
777 library that will be used when building with the -linkshared
778 option. Packages named main are ignored.
779
780 -buildmode=exe
781 Build the listed main packages and everything they import into
782 executables. Packages not named main are ignored.
783
784 -buildmode=pie
785 Build the listed main packages and everything they import into
786 position independent executables (PIE). Packages not named
787 main are ignored.
788
789 -buildmode=plugin
790 Build the listed main packages, plus all packages that they
791 import, into a Go plugin. Packages not named main are ignored.
792
793 On AIX, when linking a C program that uses a Go archive built with
794 -buildmode=c-archive, you must pass -Wl,-bnoobjreorder to the C compiler.
795 `,
796 }
797
798 var HelpCache = &base.Command{
799 UsageLine: "cache",
800 Short: "build and test caching",
801 Long: `
802 The go command caches build outputs for reuse in future builds.
803 The default location for cache data is a subdirectory named go-build
804 in the standard user cache directory for the current operating system.
805 Setting the GOCACHE environment variable overrides this default,
806 and running 'go env GOCACHE' prints the current cache directory.
807
808 The go command periodically deletes cached data that has not been
809 used recently. Running 'go clean -cache' deletes all cached data.
810
811 The build cache correctly accounts for changes to Go source files,
812 compilers, compiler options, and so on: cleaning the cache explicitly
813 should not be necessary in typical use. However, the build cache
814 does not detect changes to C libraries imported with cgo.
815 If you have made changes to the C libraries on your system, you
816 will need to clean the cache explicitly or else use the -a build flag
817 (see 'go help build') to force rebuilding of packages that
818 depend on the updated C libraries.
819
820 The go command also caches successful package test results.
821 See 'go help test' for details. Running 'go clean -testcache' removes
822 all cached test results (but not cached build results).
823
824 The go command also caches values used in fuzzing with 'go test -fuzz',
825 specifically, values that expanded code coverage when passed to a
826 fuzz function. These values are not used for regular building and
827 testing, but they're stored in a subdirectory of the build cache.
828 Running 'go clean -fuzzcache' removes all cached fuzzing values.
829 This may make fuzzing less effective, temporarily.
830
831 The GODEBUG environment variable can enable printing of debugging
832 information about the state of the cache:
833
834 GODEBUG=gocacheverify=1 causes the go command to bypass the
835 use of any cache entries and instead rebuild everything and check
836 that the results match existing cache entries.
837
838 GODEBUG=gocachehash=1 causes the go command to print the inputs
839 for all of the content hashes it uses to construct cache lookup keys.
840 The output is voluminous but can be useful for debugging the cache.
841
842 GODEBUG=gocachetest=1 causes the go command to print details of its
843 decisions about whether to reuse a cached test result.
844 `,
845 }
846
847 var HelpBuildConstraint = &base.Command{
848 UsageLine: "buildconstraint",
849 Short: "build constraints",
850 Long: `
851 A build constraint, also known as a build tag, is a condition under which a
852 file should be included in the package. Build constraints are given by a
853 line comment that begins
854
855 //go:build
856
857 Build constraints can also be used to downgrade the language version
858 used to compile a file.
859
860 Constraints may appear in any kind of source file (not just Go), but
861 they must appear near the top of the file, preceded
862 only by blank lines and other comments. These rules mean that in Go
863 files a build constraint must appear before the package clause.
864
865 To distinguish build constraints from package documentation,
866 a build constraint should be followed by a blank line.
867
868 A build constraint comment is evaluated as an expression containing
869 build tags combined by ||, &&, and ! operators and parentheses.
870 Operators have the same meaning as in Go.
871
872 For example, the following build constraint constrains a file to
873 build when the "linux" and "386" constraints are satisfied, or when
874 "darwin" is satisfied and "cgo" is not:
875
876 //go:build (linux && 386) || (darwin && !cgo)
877
878 It is an error for a file to have more than one //go:build line.
879
880 During a particular build, the following build tags are satisfied:
881
882 - the target operating system, as spelled by runtime.GOOS, set with the
883 GOOS environment variable.
884 - the target architecture, as spelled by runtime.GOARCH, set with the
885 GOARCH environment variable.
886 - any architecture features, in the form GOARCH.feature
887 (for example, "amd64.v2"), as detailed below.
888 - "unix", if GOOS is a Unix or Unix-like system.
889 - the compiler being used, either "gc" or "gccgo"
890 - "cgo", if the cgo command is supported (see CGO_ENABLED in
891 'go help environment').
892 - a term for each Go major release, through the current version:
893 "go1.1" from Go version 1.1 onward, "go1.12" from Go 1.12, and so on.
894 - any additional tags given by the -tags flag (see 'go help build').
895
896 There are no separate build tags for beta or minor releases.
897
898 If a file's name, after stripping the extension and a possible _test suffix,
899 matches any of the following patterns:
900 *_GOOS
901 *_GOARCH
902 *_GOOS_GOARCH
903 (example: source_windows_amd64.go) where GOOS and GOARCH represent
904 any known operating system and architecture values respectively, then
905 the file is considered to have an implicit build constraint requiring
906 those terms (in addition to any explicit constraints in the file).
907
908 Using GOOS=android matches build tags and files as for GOOS=linux
909 in addition to android tags and files.
910
911 Using GOOS=illumos matches build tags and files as for GOOS=solaris
912 in addition to illumos tags and files.
913
914 Using GOOS=ios matches build tags and files as for GOOS=darwin
915 in addition to ios tags and files.
916
917 The defined architecture feature build tags are:
918
919 - For GOARCH=386, GO386=387 and GO386=sse2
920 set the 386.387 and 386.sse2 build tags, respectively.
921 - For GOARCH=amd64, GOAMD64=v1, v2, and v3
922 correspond to the amd64.v1, amd64.v2, and amd64.v3 feature build tags.
923 - For GOARCH=arm, GOARM=5, 6, and 7
924 correspond to the arm.5, arm.6, and arm.7 feature build tags.
925 - For GOARCH=arm64, GOARM64=v8.{0-9} and v9.{0-5}
926 correspond to the arm64.v8.{0-9} and arm64.v9.{0-5} feature build tags.
927 - For GOARCH=mips or mipsle,
928 GOMIPS=hardfloat and softfloat
929 correspond to the mips.hardfloat and mips.softfloat
930 (or mipsle.hardfloat and mipsle.softfloat) feature build tags.
931 - For GOARCH=mips64 or mips64le,
932 GOMIPS64=hardfloat and softfloat
933 correspond to the mips64.hardfloat and mips64.softfloat
934 (or mips64le.hardfloat and mips64le.softfloat) feature build tags.
935 - For GOARCH=ppc64 or ppc64le,
936 GOPPC64=power8, power9, and power10 correspond to the
937 ppc64.power8, ppc64.power9, and ppc64.power10
938 (or ppc64le.power8, ppc64le.power9, and ppc64le.power10)
939 feature build tags.
940 - For GOARCH=riscv64,
941 GORISCV64=rva20u64 and rva22u64 correspond to the riscv64.rva20u64
942 and riscv64.rva22u64 build tags.
943 - For GOARCH=wasm, GOWASM=satconv and signext
944 correspond to the wasm.satconv and wasm.signext feature build tags.
945
946 For GOARCH=amd64, arm, ppc64, ppc64le, and riscv64, a particular feature level
947 sets the feature build tags for all previous levels as well.
948 For example, GOAMD64=v2 sets the amd64.v1 and amd64.v2 feature flags.
949 This ensures that code making use of v2 features continues to compile
950 when, say, GOAMD64=v4 is introduced.
951 Code handling the absence of a particular feature level
952 should use a negation:
953
954 //go:build !amd64.v2
955
956 To keep a file from being considered for any build:
957
958 //go:build ignore
959
960 (Any other unsatisfied word will work as well, but "ignore" is conventional.)
961
962 To build a file only when using cgo, and only on Linux and OS X:
963
964 //go:build cgo && (linux || darwin)
965
966 Such a file is usually paired with another file implementing the
967 default functionality for other systems, which in this case would
968 carry the constraint:
969
970 //go:build !(cgo && (linux || darwin))
971
972 Naming a file dns_windows.go will cause it to be included only when
973 building the package for Windows; similarly, math_386.s will be included
974 only when building the package for 32-bit x86.
975
976 Go versions 1.16 and earlier used a different syntax for build constraints,
977 with a "// +build" prefix. The gofmt command will add an equivalent //go:build
978 constraint when encountering the older syntax.
979
980 In modules with a Go version of 1.21 or later, if a file's build constraint
981 has a term for a Go major release, the language version used when compiling
982 the file will be the minimum version implied by the build constraint.
983 `,
984 }
985
View as plain text