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