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 GCCGO
495 The gccgo command to run for 'go build -compiler=gccgo'.
496 GO111MODULE
497 Controls whether the go command runs in module-aware mode or GOPATH mode.
498 May be "off", "on", or "auto".
499 See https://golang.org/ref/mod#mod-commands.
500 GOARCH
501 The architecture, or processor, for which to compile code.
502 Examples are amd64, 386, arm, ppc64.
503 GOAUTH
504 Controls authentication for go-import and HTTPS module mirror interactions.
505 See 'go help goauth'.
506 GOBIN
507 The directory where 'go install' will install a command.
508 GOCACHE
509 The directory where the go command will store cached
510 information for reuse in future builds.
511 GODEBUG
512 Enable various debugging facilities. See https://go.dev/doc/godebug
513 for details.
514 GOENV
515 The location of the Go environment configuration file.
516 Cannot be set using 'go env -w'.
517 Setting GOENV=off in the environment disables the use of the
518 default configuration file.
519 GOFLAGS
520 A space-separated list of -flag=value settings to apply
521 to go commands by default, when the given flag is known by
522 the current command. Each entry must be a standalone flag.
523 Because the entries are space-separated, flag values must
524 not contain spaces. Flags listed on the command line
525 are applied after this list and therefore override it.
526 GOINSECURE
527 Comma-separated list of glob patterns (in the syntax of Go's path.Match)
528 of module path prefixes that should always be fetched in an insecure
529 manner. Only applies to dependencies that are being fetched directly.
530 GOINSECURE does not disable checksum database validation. GOPRIVATE or
531 GONOSUMDB may be used to achieve that.
532 GOMODCACHE
533 The directory where the go command will store downloaded modules.
534 GOOS
535 The operating system for which to compile code.
536 Examples are linux, darwin, windows, netbsd.
537 GOPATH
538 Controls where various files are stored. See: 'go help gopath'.
539 GOPRIVATE, GONOPROXY, GONOSUMDB
540 Comma-separated list of glob patterns (in the syntax of Go's path.Match)
541 of module path prefixes that should always be fetched directly
542 or that should not be compared against the checksum database.
543 See https://golang.org/ref/mod#private-modules.
544 GOPROXY
545 URL of Go module proxy. See https://golang.org/ref/mod#environment-variables
546 and https://golang.org/ref/mod#module-proxy for details.
547 GOROOT
548 The root of the go tree.
549 GOSUMDB
550 The name of checksum database to use and optionally its public key and
551 URL. See https://golang.org/ref/mod#authenticating.
552 GOTMPDIR
553 The directory where the go command will write
554 temporary source files, packages, and binaries.
555 GOTOOLCHAIN
556 Controls which Go toolchain is used. See https://go.dev/doc/toolchain.
557 GOVCS
558 Lists version control commands that may be used with matching servers.
559 See 'go help vcs'.
560 GOWORK
561 In module aware mode, use the given go.work file as a workspace file.
562 By default or when GOWORK is "auto", the go command searches for a
563 file named go.work in the current directory and then containing directories
564 until one is found. If a valid go.work file is found, the modules
565 specified will collectively be used as the main modules. If GOWORK
566 is "off", or a go.work file is not found in "auto" mode, workspace
567 mode is disabled.
568
569 Environment variables for use with cgo:
570
571 AR
572 The command to use to manipulate library archives when
573 building with the gccgo compiler.
574 The default is 'ar'.
575 CC
576 The command to use to compile C code.
577 CGO_CFLAGS
578 Flags that cgo will pass to the compiler when compiling
579 C code.
580 CGO_CFLAGS_ALLOW
581 A regular expression specifying additional flags to allow
582 to appear in #cgo CFLAGS source code directives.
583 Does not apply to the CGO_CFLAGS environment variable.
584 CGO_CFLAGS_DISALLOW
585 A regular expression specifying flags that must be disallowed
586 from appearing in #cgo CFLAGS source code directives.
587 Does not apply to the CGO_CFLAGS environment variable.
588 CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
589 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
590 but for the C preprocessor.
591 CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
592 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
593 but for the C++ compiler.
594 CGO_ENABLED
595 Whether the cgo command is supported. Either 0 or 1.
596 CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
597 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
598 but for the Fortran compiler.
599 CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
600 Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
601 but for the linker.
602 CXX
603 The command to use to compile C++ code.
604 FC
605 The command to use to compile Fortran code.
606 PKG_CONFIG
607 Path to pkg-config tool.
608
609 Architecture-specific environment variables:
610
611 GO386
612 For GOARCH=386, how to implement floating point instructions.
613 Valid values are sse2 (default), softfloat.
614 GOAMD64
615 For GOARCH=amd64, the microarchitecture level for which to compile.
616 Valid values are v1 (default), v2, v3, v4.
617 See https://golang.org/wiki/MinimumRequirements#amd64
618 GOARM
619 For GOARCH=arm, the ARM architecture for which to compile.
620 Valid values are 5, 6, 7.
621 The value can be followed by an option specifying how to implement floating point instructions.
622 Valid options are ,softfloat (default for 5) and ,hardfloat (default for 6 and 7).
623 GOARM64
624 For GOARCH=arm64, the ARM64 architecture for which to compile.
625 Valid values are v8.0 (default), v8.{1-9}, v9.{0-5}.
626 The value can be followed by an option specifying extensions implemented by target hardware.
627 Valid options are ,lse and ,crypto.
628 Note that some extensions are enabled by default starting from a certain GOARM64 version;
629 for example, lse is enabled by default starting from v8.1.
630 GOMIPS
631 For GOARCH=mips{,le}, whether to use floating point instructions.
632 Valid values are hardfloat (default), softfloat.
633 GOMIPS64
634 For GOARCH=mips64{,le}, whether to use floating point instructions.
635 Valid values are hardfloat (default), softfloat.
636 GOPPC64
637 For GOARCH=ppc64{,le}, the target ISA (Instruction Set Architecture).
638 Valid values are power8 (default), power9, power10.
639 GORISCV64
640 For GOARCH=riscv64, the RISC-V user-mode application profile for which
641 to compile. Valid values are rva20u64 (default), rva22u64.
642 See https://github.com/riscv/riscv-profiles/blob/main/src/profiles.adoc
643 GOWASM
644 For GOARCH=wasm, comma-separated list of experimental WebAssembly features to use.
645 Valid values are satconv, signext.
646
647 Environment variables for use with code coverage:
648
649 GOCOVERDIR
650 Directory into which to write code coverage data files
651 generated by running a "go build -cover" binary.
652 Requires that GOEXPERIMENT=coverageredesign is enabled.
653
654 Special-purpose environment variables:
655
656 GCCGOTOOLDIR
657 If set, where to find gccgo tools, such as cgo.
658 The default is based on how gccgo was configured.
659 GOEXPERIMENT
660 Comma-separated list of toolchain experiments to enable or disable.
661 The list of available experiments may change arbitrarily over time.
662 See GOROOT/src/internal/goexperiment/flags.go for currently valid values.
663 Warning: This variable is provided for the development and testing
664 of the Go toolchain itself. Use beyond that purpose is unsupported.
665 GOFIPS140
666 The FIPS-140 cryptography mode to use when building binaries.
667 The default is GOFIPS140=off, which makes no FIPS-140 changes at all.
668 Other values enable FIPS-140 compliance measures and select alternate
669 versions of the cryptography source code.
670 See https://go.dev/security/fips140 for details.
671 GO_EXTLINK_ENABLED
672 Whether the linker should use external linking mode
673 when using -linkmode=auto with code that uses cgo.
674 Set to 0 to disable external linking mode, 1 to enable it.
675 GIT_ALLOW_PROTOCOL
676 Defined by Git. A colon-separated list of schemes that are allowed
677 to be used with git fetch/clone. If set, any scheme not explicitly
678 mentioned will be considered insecure by 'go get'.
679 Because the variable is defined by Git, the default value cannot
680 be set using 'go env -w'.
681
682 Additional information available from 'go env' but not read from the environment:
683
684 GOEXE
685 The executable file name suffix (".exe" on Windows, "" on other systems).
686 GOGCCFLAGS
687 A space-separated list of arguments supplied to the CC command.
688 GOHOSTARCH
689 The architecture (GOARCH) of the Go toolchain binaries.
690 GOHOSTOS
691 The operating system (GOOS) of the Go toolchain binaries.
692 GOMOD
693 The absolute path to the go.mod of the main module.
694 If module-aware mode is enabled, but there is no go.mod, GOMOD will be
695 os.DevNull ("/dev/null" on Unix-like systems, "NUL" on Windows).
696 If module-aware mode is disabled, GOMOD will be the empty string.
697 GOTELEMETRY
698 The current Go telemetry mode ("off", "local", or "on").
699 See "go help telemetry" for more information.
700 GOTELEMETRYDIR
701 The directory Go telemetry data is written is written to.
702 GOTOOLDIR
703 The directory where the go tools (compile, cover, doc, etc...) are installed.
704 GOVERSION
705 The version of the installed Go tree, as reported by runtime.Version.
706 `,
707 }
708
709 var HelpFileType = &base.Command{
710 UsageLine: "filetype",
711 Short: "file types",
712 Long: `
713 The go command examines the contents of a restricted set of files
714 in each directory. It identifies which files to examine based on
715 the extension of the file name. These extensions are:
716
717 .go
718 Go source files.
719 .c, .h
720 C source files.
721 If the package uses cgo or SWIG, these will be compiled with the
722 OS-native compiler (typically gcc); otherwise they will
723 trigger an error.
724 .cc, .cpp, .cxx, .hh, .hpp, .hxx
725 C++ source files. Only useful with cgo or SWIG, and always
726 compiled with the OS-native compiler.
727 .m
728 Objective-C source files. Only useful with cgo, and always
729 compiled with the OS-native compiler.
730 .s, .S, .sx
731 Assembler source files.
732 If the package uses cgo or SWIG, these will be assembled with the
733 OS-native assembler (typically gcc (sic)); otherwise they
734 will be assembled with the Go assembler.
735 .swig, .swigcxx
736 SWIG definition files.
737 .syso
738 System object files.
739
740 Files of each of these types except .syso may contain build
741 constraints, but the go command stops scanning for build constraints
742 at the first item in the file that is not a blank line or //-style
743 line comment. See the go/build package documentation for
744 more details.
745 `,
746 }
747
748 var HelpBuildmode = &base.Command{
749 UsageLine: "buildmode",
750 Short: "build modes",
751 Long: `
752 The 'go build' and 'go install' commands take a -buildmode argument which
753 indicates which kind of object file is to be built. Currently supported values
754 are:
755
756 -buildmode=archive
757 Build the listed non-main packages into .a files. Packages named
758 main are ignored.
759
760 -buildmode=c-archive
761 Build the listed main package, plus all packages it imports,
762 into a C archive file. The only callable symbols will be those
763 functions exported using a cgo //export comment. Requires
764 exactly one main package to be listed.
765
766 -buildmode=c-shared
767 Build the listed main package, plus all packages it imports,
768 into a C shared library. The only callable symbols will
769 be those functions exported using a cgo //export comment.
770 Requires exactly one main package to be listed.
771
772 -buildmode=default
773 Listed main packages are built into executables and listed
774 non-main packages are built into .a files (the default
775 behavior).
776
777 -buildmode=shared
778 Combine all the listed non-main packages into a single shared
779 library that will be used when building with the -linkshared
780 option. Packages named main are ignored.
781
782 -buildmode=exe
783 Build the listed main packages and everything they import into
784 executables. Packages not named main are ignored.
785
786 -buildmode=pie
787 Build the listed main packages and everything they import into
788 position independent executables (PIE). Packages not named
789 main are ignored.
790
791 -buildmode=plugin
792 Build the listed main packages, plus all packages that they
793 import, into a Go plugin. Packages not named main are ignored.
794
795 On AIX, when linking a C program that uses a Go archive built with
796 -buildmode=c-archive, you must pass -Wl,-bnoobjreorder to the C compiler.
797 `,
798 }
799
800 var HelpCache = &base.Command{
801 UsageLine: "cache",
802 Short: "build and test caching",
803 Long: `
804 The go command caches build outputs for reuse in future builds.
805 The default location for cache data is a subdirectory named go-build
806 in the standard user cache directory for the current operating system.
807 Setting the GOCACHE environment variable overrides this default,
808 and running 'go env GOCACHE' prints the current cache directory.
809
810 The go command periodically deletes cached data that has not been
811 used recently. Running 'go clean -cache' deletes all cached data.
812
813 The build cache correctly accounts for changes to Go source files,
814 compilers, compiler options, and so on: cleaning the cache explicitly
815 should not be necessary in typical use. However, the build cache
816 does not detect changes to C libraries imported with cgo.
817 If you have made changes to the C libraries on your system, you
818 will need to clean the cache explicitly or else use the -a build flag
819 (see 'go help build') to force rebuilding of packages that
820 depend on the updated C libraries.
821
822 The go command also caches successful package test results.
823 See 'go help test' for details. Running 'go clean -testcache' removes
824 all cached test results (but not cached build results).
825
826 The go command also caches values used in fuzzing with 'go test -fuzz',
827 specifically, values that expanded code coverage when passed to a
828 fuzz function. These values are not used for regular building and
829 testing, but they're stored in a subdirectory of the build cache.
830 Running 'go clean -fuzzcache' removes all cached fuzzing values.
831 This may make fuzzing less effective, temporarily.
832
833 The GODEBUG environment variable can enable printing of debugging
834 information about the state of the cache:
835
836 GODEBUG=gocacheverify=1 causes the go command to bypass the
837 use of any cache entries and instead rebuild everything and check
838 that the results match existing cache entries.
839
840 GODEBUG=gocachehash=1 causes the go command to print the inputs
841 for all of the content hashes it uses to construct cache lookup keys.
842 The output is voluminous but can be useful for debugging the cache.
843
844 GODEBUG=gocachetest=1 causes the go command to print details of its
845 decisions about whether to reuse a cached test result.
846 `,
847 }
848
849 var HelpBuildConstraint = &base.Command{
850 UsageLine: "buildconstraint",
851 Short: "build constraints",
852 Long: `
853 A build constraint, also known as a build tag, is a condition under which a
854 file should be included in the package. Build constraints are given by a
855 line comment that begins
856
857 //go:build
858
859 Build constraints can also be used to downgrade the language version
860 used to compile a file.
861
862 Constraints may appear in any kind of source file (not just Go), but
863 they must appear near the top of the file, preceded
864 only by blank lines and other comments. These rules mean that in Go
865 files a build constraint must appear before the package clause.
866
867 To distinguish build constraints from package documentation,
868 a build constraint should be followed by a blank line.
869
870 A build constraint comment is evaluated as an expression containing
871 build tags combined by ||, &&, and ! operators and parentheses.
872 Operators have the same meaning as in Go.
873
874 For example, the following build constraint constrains a file to
875 build when the "linux" and "386" constraints are satisfied, or when
876 "darwin" is satisfied and "cgo" is not:
877
878 //go:build (linux && 386) || (darwin && !cgo)
879
880 It is an error for a file to have more than one //go:build line.
881
882 During a particular build, the following build tags are satisfied:
883
884 - the target operating system, as spelled by runtime.GOOS, set with the
885 GOOS environment variable.
886 - the target architecture, as spelled by runtime.GOARCH, set with the
887 GOARCH environment variable.
888 - any architecture features, in the form GOARCH.feature
889 (for example, "amd64.v2"), as detailed below.
890 - "unix", if GOOS is a Unix or Unix-like system.
891 - the compiler being used, either "gc" or "gccgo"
892 - "cgo", if the cgo command is supported (see CGO_ENABLED in
893 'go help environment').
894 - a term for each Go major release, through the current version:
895 "go1.1" from Go version 1.1 onward, "go1.12" from Go 1.12, and so on.
896 - any additional tags given by the -tags flag (see 'go help build').
897
898 There are no separate build tags for beta or minor releases.
899
900 If a file's name, after stripping the extension and a possible _test suffix,
901 matches any of the following patterns:
902 *_GOOS
903 *_GOARCH
904 *_GOOS_GOARCH
905 (example: source_windows_amd64.go) where GOOS and GOARCH represent
906 any known operating system and architecture values respectively, then
907 the file is considered to have an implicit build constraint requiring
908 those terms (in addition to any explicit constraints in the file).
909
910 Using GOOS=android matches build tags and files as for GOOS=linux
911 in addition to android tags and files.
912
913 Using GOOS=illumos matches build tags and files as for GOOS=solaris
914 in addition to illumos tags and files.
915
916 Using GOOS=ios matches build tags and files as for GOOS=darwin
917 in addition to ios tags and files.
918
919 The defined architecture feature build tags are:
920
921 - For GOARCH=386, GO386=387 and GO386=sse2
922 set the 386.387 and 386.sse2 build tags, respectively.
923 - For GOARCH=amd64, GOAMD64=v1, v2, and v3
924 correspond to the amd64.v1, amd64.v2, and amd64.v3 feature build tags.
925 - For GOARCH=arm, GOARM=5, 6, and 7
926 correspond to the arm.5, arm.6, and arm.7 feature build tags.
927 - For GOARCH=arm64, GOARM64=v8.{0-9} and v9.{0-5}
928 correspond to the arm64.v8.{0-9} and arm64.v9.{0-5} feature build tags.
929 - For GOARCH=mips or mipsle,
930 GOMIPS=hardfloat and softfloat
931 correspond to the mips.hardfloat and mips.softfloat
932 (or mipsle.hardfloat and mipsle.softfloat) feature build tags.
933 - For GOARCH=mips64 or mips64le,
934 GOMIPS64=hardfloat and softfloat
935 correspond to the mips64.hardfloat and mips64.softfloat
936 (or mips64le.hardfloat and mips64le.softfloat) feature build tags.
937 - For GOARCH=ppc64 or ppc64le,
938 GOPPC64=power8, power9, and power10 correspond to the
939 ppc64.power8, ppc64.power9, and ppc64.power10
940 (or ppc64le.power8, ppc64le.power9, and ppc64le.power10)
941 feature build tags.
942 - For GOARCH=riscv64,
943 GORISCV64=rva20u64 and rva22u64 correspond to the riscv64.rva20u64
944 and riscv64.rva22u64 build tags.
945 - For GOARCH=wasm, GOWASM=satconv and signext
946 correspond to the wasm.satconv and wasm.signext feature build tags.
947
948 For GOARCH=amd64, arm, ppc64, ppc64le, and riscv64, a particular feature level
949 sets the feature build tags for all previous levels as well.
950 For example, GOAMD64=v2 sets the amd64.v1 and amd64.v2 feature flags.
951 This ensures that code making use of v2 features continues to compile
952 when, say, GOAMD64=v4 is introduced.
953 Code handling the absence of a particular feature level
954 should use a negation:
955
956 //go:build !amd64.v2
957
958 To keep a file from being considered for any build:
959
960 //go:build ignore
961
962 (Any other unsatisfied word will work as well, but "ignore" is conventional.)
963
964 To build a file only when using cgo, and only on Linux and OS X:
965
966 //go:build cgo && (linux || darwin)
967
968 Such a file is usually paired with another file implementing the
969 default functionality for other systems, which in this case would
970 carry the constraint:
971
972 //go:build !(cgo && (linux || darwin))
973
974 Naming a file dns_windows.go will cause it to be included only when
975 building the package for Windows; similarly, math_386.s will be included
976 only when building the package for 32-bit x86.
977
978 Go versions 1.16 and earlier used a different syntax for build constraints,
979 with a "// +build" prefix. The gofmt command will add an equivalent //go:build
980 constraint when encountering the older syntax.
981
982 In modules with a Go version of 1.21 or later, if a file's build constraint
983 has a term for a Go major release, the language version used when compiling
984 the file will be the minimum version implied by the build constraint.
985 `,
986 }
987
988 var HelpGoAuth = &base.Command{
989 UsageLine: "goauth",
990 Short: "GOAUTH environment variable",
991 Long: `
992 GOAUTH is a semicolon-separated list of authentication commands for go-import and
993 HTTPS module mirror interactions. The default is netrc.
994
995 The supported authentication commands are:
996
997 off
998 Disables authentication.
999 netrc
1000 Uses credentials from NETRC or the .netrc file in your home directory.
1001 git dir
1002 Runs 'git credential fill' in dir and uses its credentials. The
1003 go command will run 'git credential approve/reject' to update
1004 the credential helper's cache.
1005 command
1006 Executes the given command (a space-separated argument list) and attaches
1007 the provided headers to HTTPS requests.
1008 The command must produce output in the following format:
1009 Response = { CredentialSet } .
1010 CredentialSet = URLLine { URLLine } BlankLine { HeaderLine } BlankLine .
1011 URLLine = /* URL that starts with "https://" */ '\n' .
1012 HeaderLine = /* HTTP Request header */ '\n' .
1013 BlankLine = '\n' .
1014
1015 Example:
1016 https://example.com/
1017 https://example.net/api/
1018
1019 Authorization: Basic <token>
1020
1021 https://another-example.org/
1022
1023 Example: Data
1024
1025 If the server responds with any 4xx code, the go command will write the
1026 following to the programs' stdin:
1027 Response = StatusLine { HeaderLine } BlankLine .
1028 StatusLine = Protocol Space Status '\n' .
1029 Protocol = /* HTTP protocol */ .
1030 Space = ' ' .
1031 Status = /* HTTP status code */ .
1032 BlankLine = '\n' .
1033 HeaderLine = /* HTTP Response's header */ '\n' .
1034
1035 Example:
1036 HTTP/1.1 401 Unauthorized
1037 Content-Length: 19
1038 Content-Type: text/plain; charset=utf-8
1039 Date: Thu, 07 Nov 2024 18:43:09 GMT
1040
1041 Note: at least for HTTP 1.1, the contents written to stdin can be parsed
1042 as an HTTP response.
1043
1044 Before the first HTTPS fetch, the go command will invoke each GOAUTH
1045 command in the list with no additional arguments and no input.
1046 If the server responds with any 4xx code, the go command will invoke the
1047 GOAUTH commands again with the URL as an additional command-line argument
1048 and the HTTP Response to the program's stdin.
1049 If the server responds with an error again, the fetch fails: a URL-specific
1050 GOAUTH will only be attempted once per fetch.
1051 `,
1052 }
1053
1054 var HelpBuildJSON = &base.Command{
1055 UsageLine: "buildjson",
1056 Short: "build -json encoding",
1057 Long: `
1058 The 'go build', 'go install', and 'go test' commands take a -json flag that
1059 reports build output and failures as structured JSON output on standard
1060 output.
1061
1062 The JSON stream is a newline-separated sequence of BuildEvent objects
1063 corresponding to the Go struct:
1064
1065 type BuildEvent struct {
1066 ImportPath string
1067 Action string
1068 Output string
1069 }
1070
1071 The ImportPath field gives the package ID of the package being built.
1072 This matches the Package.ImportPath field of go list -json and the
1073 TestEvent.FailedBuild field of go test -json. Note that it does not
1074 match TestEvent.Package.
1075
1076 The Action field is one of the following:
1077
1078 build-output - The toolchain printed output
1079 build-fail - The build failed
1080
1081 The Output field is set for Action == "build-output" and is a portion of
1082 the build's output. The concatenation of the Output fields of all output
1083 events is the exact output of the build. A single event may contain one
1084 or more lines of output and there may be more than one output event for
1085 a given ImportPath. This matches the definition of the TestEvent.Output
1086 field produced by go test -json.
1087
1088 For go test -json, this struct is designed so that parsers can distinguish
1089 interleaved TestEvents and BuildEvents by inspecting the Action field.
1090 Furthermore, as with TestEvent, parsers can simply concatenate the Output
1091 fields of all events to reconstruct the text format output, as it would
1092 have appeared from go build without the -json flag.
1093
1094 Note that there may also be non-JSON error text on stdnard error, even
1095 with the -json flag. Typically, this indicates an early, serious error.
1096 Consumers should be robust to this.
1097 `,
1098 }
1099
View as plain text