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