Source file src/cmd/go/internal/help/helpdoc.go

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

View as plain text