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