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