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

Documentation: cmd/go/internal/help

     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  http://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 four 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 found in all the GOPATH
    58  trees. For example, 'go list all' lists all the packages on the local
    59  system. When using modules, "all" expands to all packages in
    60  the main module and their dependencies, including dependencies
    61  needed by tests of any of those.
    62  
    63  - "std" is like all but expands to just the packages in the standard
    64  Go library.
    65  
    66  - "cmd" expands to the Go repository's commands and their
    67  internal libraries.
    68  
    69  Import paths beginning with "cmd/" only match source code in
    70  the Go repository.
    71  
    72  An import path is a pattern if it includes one or more "..." wildcards,
    73  each of which can match any string, including the empty string and
    74  strings containing slashes. Such a pattern expands to all package
    75  directories found in the GOPATH trees with names matching the
    76  patterns.
    77  
    78  To make common patterns more convenient, there are two special cases.
    79  First, /... at the end of the pattern can match an empty string,
    80  so that net/... matches both net and packages in its subdirectories, like net/http.
    81  Second, any slash-separated pattern element containing a wildcard never
    82  participates in a match of the "vendor" element in the path of a vendored
    83  package, so that ./... does not match packages in subdirectories of
    84  ./vendor or ./mycode/vendor, but ./vendor/... and ./mycode/vendor/... do.
    85  Note, however, that a directory named vendor that itself contains code
    86  is not a vendored package: cmd/vendor would be a command named vendor,
    87  and the pattern cmd/... matches it.
    88  See golang.org/s/go15vendor for more about vendoring.
    89  
    90  An import path can also name a package to be downloaded from
    91  a remote repository. Run 'go help importpath' for details.
    92  
    93  Every package in a program must have a unique import path.
    94  By convention, this is arranged by starting each path with a
    95  unique prefix that belongs to you. For example, paths used
    96  internally at Google all begin with 'google', and paths
    97  denoting remote repositories begin with the path to the code,
    98  such as 'github.com/user/repo'.
    99  
   100  Packages in a program need not have unique package names,
   101  but there are two reserved package names with special meaning.
   102  The name main indicates a command, not a library.
   103  Commands are built into binaries and cannot be imported.
   104  The name documentation indicates documentation for
   105  a non-Go program in the directory. Files in package documentation
   106  are ignored by the go command.
   107  
   108  As a special case, if the package list is a list of .go files from a
   109  single directory, the command is applied to a single synthesized
   110  package made up of exactly those files, ignoring any build constraints
   111  in those files and ignoring any other files in the directory.
   112  
   113  Directory and file names that begin with "." or "_" are ignored
   114  by the go tool, as are directories named "testdata".
   115  	`,
   116  }
   117  
   118  var HelpImportPath = &base.Command{
   119  	UsageLine: "importpath",
   120  	Short:     "import path syntax",
   121  	Long: `
   122  
   123  An import path (see 'go help packages') denotes a package stored in the local
   124  file system. In general, an import path denotes either a standard package (such
   125  as "unicode/utf8") or a package found in one of the work spaces (For more
   126  details see: 'go help gopath').
   127  
   128  Relative import paths
   129  
   130  An import path beginning with ./ or ../ is called a relative path.
   131  The toolchain supports relative import paths as a shortcut in two ways.
   132  
   133  First, a relative path can be used as a shorthand on the command line.
   134  If you are working in the directory containing the code imported as
   135  "unicode" and want to run the tests for "unicode/utf8", you can type
   136  "go test ./utf8" instead of needing to specify the full path.
   137  Similarly, in the reverse situation, "go test .." will test "unicode" from
   138  the "unicode/utf8" directory. Relative patterns are also allowed, like
   139  "go test ./..." to test all subdirectories. See 'go help packages' for details
   140  on the pattern syntax.
   141  
   142  Second, if you are compiling a Go program not in a work space,
   143  you can use a relative path in an import statement in that program
   144  to refer to nearby code also not in a work space.
   145  This makes it easy to experiment with small multipackage programs
   146  outside of the usual work spaces, but such programs cannot be
   147  installed with "go install" (there is no work space in which to install them),
   148  so they are rebuilt from scratch each time they are built.
   149  To avoid ambiguity, Go programs cannot use relative import paths
   150  within a work space.
   151  
   152  Remote import paths
   153  
   154  Certain import paths also
   155  describe how to obtain the source code for the package using
   156  a revision control system.
   157  
   158  A few common code hosting sites have special syntax:
   159  
   160  	Bitbucket (Git, Mercurial)
   161  
   162  		import "bitbucket.org/user/project"
   163  		import "bitbucket.org/user/project/sub/directory"
   164  
   165  	GitHub (Git)
   166  
   167  		import "github.com/user/project"
   168  		import "github.com/user/project/sub/directory"
   169  
   170  	Launchpad (Bazaar)
   171  
   172  		import "launchpad.net/project"
   173  		import "launchpad.net/project/series"
   174  		import "launchpad.net/project/series/sub/directory"
   175  
   176  		import "launchpad.net/~user/project/branch"
   177  		import "launchpad.net/~user/project/branch/sub/directory"
   178  
   179  	IBM DevOps Services (Git)
   180  
   181  		import "hub.jazz.net/git/user/project"
   182  		import "hub.jazz.net/git/user/project/sub/directory"
   183  
   184  For code hosted on other servers, import paths may either be qualified
   185  with the version control type, or the go tool can dynamically fetch
   186  the import path over https/http and discover where the code resides
   187  from a <meta> tag in the HTML.
   188  
   189  To declare the code location, an import path of the form
   190  
   191  	repository.vcs/path
   192  
   193  specifies the given repository, with or without the .vcs suffix,
   194  using the named version control system, and then the path inside
   195  that repository. The supported version control systems are:
   196  
   197  	Bazaar      .bzr
   198  	Fossil      .fossil
   199  	Git         .git
   200  	Mercurial   .hg
   201  	Subversion  .svn
   202  
   203  For example,
   204  
   205  	import "example.org/user/foo.hg"
   206  
   207  denotes the root directory of the Mercurial repository at
   208  example.org/user/foo or foo.hg, and
   209  
   210  	import "example.org/repo.git/foo/bar"
   211  
   212  denotes the foo/bar directory of the Git repository at
   213  example.org/repo or repo.git.
   214  
   215  When a version control system supports multiple protocols,
   216  each is tried in turn when downloading. For example, a Git
   217  download tries https://, then git+ssh://.
   218  
   219  By default, downloads are restricted to known secure protocols
   220  (e.g. https, ssh). To override this setting for Git downloads, the
   221  GIT_ALLOW_PROTOCOL environment variable can be set (For more details see:
   222  'go help environment').
   223  
   224  If the import path is not a known code hosting site and also lacks a
   225  version control qualifier, the go tool attempts to fetch the import
   226  over https/http and looks for a <meta> tag in the document's HTML
   227  <head>.
   228  
   229  The meta tag has the form:
   230  
   231  	<meta name="go-import" content="import-prefix vcs repo-root">
   232  
   233  The import-prefix is the import path corresponding to the repository
   234  root. It must be a prefix or an exact match of the package being
   235  fetched with "go get". If it's not an exact match, another http
   236  request is made at the prefix to verify the <meta> tags match.
   237  
   238  The meta tag should appear as early in the file as possible.
   239  In particular, it should appear before any raw JavaScript or CSS,
   240  to avoid confusing the go command's restricted parser.
   241  
   242  The vcs is one of "bzr", "fossil", "git", "hg", "svn".
   243  
   244  The repo-root is the root of the version control system
   245  containing a scheme and not containing a .vcs qualifier.
   246  
   247  For example,
   248  
   249  	import "example.org/pkg/foo"
   250  
   251  will result in the following requests:
   252  
   253  	https://example.org/pkg/foo?go-get=1 (preferred)
   254  	http://example.org/pkg/foo?go-get=1  (fallback, only with -insecure)
   255  
   256  If that page contains the meta tag
   257  
   258  	<meta name="go-import" content="example.org git https://code.org/r/p/exproj">
   259  
   260  the go tool will verify that https://example.org/?go-get=1 contains the
   261  same meta tag and then git clone https://code.org/r/p/exproj into
   262  GOPATH/src/example.org.
   263  
   264  When using GOPATH, downloaded packages are written to the first directory
   265  listed in the GOPATH environment variable.
   266  (See 'go help gopath-get' and 'go help gopath'.)
   267  
   268  When using modules, downloaded packages are stored in the module cache.
   269  (See 'go help module-get' and 'go help goproxy'.)
   270  
   271  When using modules, an additional variant of the go-import meta tag is
   272  recognized and is preferred over those listing version control systems.
   273  That variant uses "mod" as the vcs in the content value, as in:
   274  
   275  	<meta name="go-import" content="example.org mod https://code.org/moduleproxy">
   276  
   277  This tag means to fetch modules with paths beginning with example.org
   278  from the module proxy available at the URL https://code.org/moduleproxy.
   279  See 'go help goproxy' for details about the proxy protocol.
   280  
   281  Import path checking
   282  
   283  When the custom import path feature described above redirects to a
   284  known code hosting site, each of the resulting packages has two possible
   285  import paths, using the custom domain or the known hosting site.
   286  
   287  A package statement is said to have an "import comment" if it is immediately
   288  followed (before the next newline) by a comment of one of these two forms:
   289  
   290  	package math // import "path"
   291  	package math /* import "path" */
   292  
   293  The go command will refuse to install a package with an import comment
   294  unless it is being referred to by that import path. In this way, import comments
   295  let package authors make sure the custom import path is used and not a
   296  direct path to the underlying code hosting site.
   297  
   298  Import path checking is disabled for code found within vendor trees.
   299  This makes it possible to copy code into alternate locations in vendor trees
   300  without needing to update import comments.
   301  
   302  Import path checking is also disabled when using modules.
   303  Import path comments are obsoleted by the go.mod file's module statement.
   304  
   305  See https://golang.org/s/go14customimport for details.
   306  	`,
   307  }
   308  
   309  var HelpGopath = &base.Command{
   310  	UsageLine: "gopath",
   311  	Short:     "GOPATH environment variable",
   312  	Long: `
   313  The Go path is used to resolve import statements.
   314  It is implemented by and documented in the go/build package.
   315  
   316  The GOPATH environment variable lists places to look for Go code.
   317  On Unix, the value is a colon-separated string.
   318  On Windows, the value is a semicolon-separated string.
   319  On Plan 9, the value is a list.
   320  
   321  If the environment variable is unset, GOPATH defaults
   322  to a subdirectory named "go" in the user's home directory
   323  ($HOME/go on Unix, %USERPROFILE%\go on Windows),
   324  unless that directory holds a Go distribution.
   325  Run "go env GOPATH" to see the current GOPATH.
   326  
   327  See https://golang.org/wiki/SettingGOPATH to set a custom GOPATH.
   328  
   329  Each directory listed in GOPATH must have a prescribed structure:
   330  
   331  The src directory holds source code. The path below src
   332  determines the import path or executable name.
   333  
   334  The pkg directory holds installed package objects.
   335  As in the Go tree, each target operating system and
   336  architecture pair has its own subdirectory of pkg
   337  (pkg/GOOS_GOARCH).
   338  
   339  If DIR is a directory listed in the GOPATH, a package with
   340  source in DIR/src/foo/bar can be imported as "foo/bar" and
   341  has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a".
   342  
   343  The bin directory holds compiled commands.
   344  Each command is named for its source directory, but only
   345  the final element, not the entire path. That is, the
   346  command with source in DIR/src/foo/quux is installed into
   347  DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped
   348  so that you can add DIR/bin to your PATH to get at the
   349  installed commands. If the GOBIN environment variable is
   350  set, commands are installed to the directory it names instead
   351  of DIR/bin. GOBIN must be an absolute path.
   352  
   353  Here's an example directory layout:
   354  
   355      GOPATH=/home/user/go
   356  
   357      /home/user/go/
   358          src/
   359              foo/
   360                  bar/               (go code in package bar)
   361                      x.go
   362                  quux/              (go code in package main)
   363                      y.go
   364          bin/
   365              quux                   (installed command)
   366          pkg/
   367              linux_amd64/
   368                  foo/
   369                      bar.a          (installed package object)
   370  
   371  Go searches each directory listed in GOPATH to find source code,
   372  but new packages are always downloaded into the first directory
   373  in the list.
   374  
   375  See https://golang.org/doc/code.html for an example.
   376  
   377  GOPATH and Modules
   378  
   379  When using modules, GOPATH is no longer used for resolving imports.
   380  However, it is still used to store downloaded source code (in GOPATH/pkg/mod)
   381  and compiled commands (in GOPATH/bin).
   382  
   383  Internal Directories
   384  
   385  Code in or below a directory named "internal" is importable only
   386  by code in the directory tree rooted at the parent of "internal".
   387  Here's an extended version of the directory layout above:
   388  
   389      /home/user/go/
   390          src/
   391              crash/
   392                  bang/              (go code in package bang)
   393                      b.go
   394              foo/                   (go code in package foo)
   395                  f.go
   396                  bar/               (go code in package bar)
   397                      x.go
   398                  internal/
   399                      baz/           (go code in package baz)
   400                          z.go
   401                  quux/              (go code in package main)
   402                      y.go
   403  
   404  
   405  The code in z.go is imported as "foo/internal/baz", but that
   406  import statement can only appear in source files in the subtree
   407  rooted at foo. The source files foo/f.go, foo/bar/x.go, and
   408  foo/quux/y.go can all import "foo/internal/baz", but the source file
   409  crash/bang/b.go cannot.
   410  
   411  See https://golang.org/s/go14internal for details.
   412  
   413  Vendor Directories
   414  
   415  Go 1.6 includes support for using local copies of external dependencies
   416  to satisfy imports of those dependencies, often referred to as vendoring.
   417  
   418  Code below a directory named "vendor" is importable only
   419  by code in the directory tree rooted at the parent of "vendor",
   420  and only using an import path that omits the prefix up to and
   421  including the vendor element.
   422  
   423  Here's the example from the previous section,
   424  but with the "internal" directory renamed to "vendor"
   425  and a new foo/vendor/crash/bang directory added:
   426  
   427      /home/user/go/
   428          src/
   429              crash/
   430                  bang/              (go code in package bang)
   431                      b.go
   432              foo/                   (go code in package foo)
   433                  f.go
   434                  bar/               (go code in package bar)
   435                      x.go
   436                  vendor/
   437                      crash/
   438                          bang/      (go code in package bang)
   439                              b.go
   440                      baz/           (go code in package baz)
   441                          z.go
   442                  quux/              (go code in package main)
   443                      y.go
   444  
   445  The same visibility rules apply as for internal, but the code
   446  in z.go is imported as "baz", not as "foo/vendor/baz".
   447  
   448  Code in vendor directories deeper in the source tree shadows
   449  code in higher directories. Within the subtree rooted at foo, an import
   450  of "crash/bang" resolves to "foo/vendor/crash/bang", not the
   451  top-level "crash/bang".
   452  
   453  Code in vendor directories is not subject to import path
   454  checking (see 'go help importpath').
   455  
   456  When 'go get' checks out or updates a git repository, it now also
   457  updates submodules.
   458  
   459  Vendor directories do not affect the placement of new repositories
   460  being checked out for the first time by 'go get': those are always
   461  placed in the main GOPATH, never in a vendor subtree.
   462  
   463  See https://golang.org/s/go15vendor for details.
   464  	`,
   465  }
   466  
   467  var HelpEnvironment = &base.Command{
   468  	UsageLine: "environment",
   469  	Short:     "environment variables",
   470  	Long: `
   471  
   472  The go command and the tools it invokes consult environment variables
   473  for configuration. If an environment variable is unset, the go command
   474  uses a sensible default setting. To see the effective setting of the
   475  variable <NAME>, run 'go env <NAME>'. To change the default setting,
   476  run 'go env -w <NAME>=<VALUE>'. Defaults changed using 'go env -w'
   477  are recorded in a Go environment configuration file stored in the
   478  per-user configuration directory, as reported by os.UserConfigDir.
   479  The location of the configuration file can be changed by setting
   480  the environment variable GOENV, and 'go env GOENV' prints the
   481  effective location, but 'go env -w' cannot change the default location.
   482  See 'go help env' for details.
   483  
   484  General-purpose environment variables:
   485  
   486  	GCCGO
   487  		The gccgo command to run for 'go build -compiler=gccgo'.
   488  	GOARCH
   489  		The architecture, or processor, for which to compile code.
   490  		Examples are amd64, 386, arm, ppc64.
   491  	GOBIN
   492  		The directory where 'go install' will install a command.
   493  	GOCACHE
   494  		The directory where the go command will store cached
   495  		information for reuse in future builds.
   496  	GODEBUG
   497  		Enable various debugging facilities. See 'go doc runtime'
   498  		for details.
   499  	GOENV
   500  		The location of the Go environment configuration file.
   501  		Cannot be set using 'go env -w'.
   502  	GOFLAGS
   503  		A space-separated list of -flag=value settings to apply
   504  		to go commands by default, when the given flag is known by
   505  		the current command. Each entry must be a standalone flag.
   506  		Because the entries are space-separated, flag values must
   507  		not contain spaces. Flags listed on the command line
   508  		are applied after this list and therefore override it.
   509  	GOINSECURE
   510  		Comma-separated list of glob patterns (in the syntax of Go's path.Match)
   511  		of module path prefixes that should always be fetched in an insecure
   512  		manner. Only applies to dependencies that are being fetched directly.
   513  	GOOS
   514  		The operating system for which to compile code.
   515  		Examples are linux, darwin, windows, netbsd.
   516  	GOPATH
   517  		For more details see: 'go help gopath'.
   518  	GOPROXY
   519  		URL of Go module proxy. See 'go help modules'.
   520  	GOPRIVATE, GONOPROXY, GONOSUMDB
   521  		Comma-separated list of glob patterns (in the syntax of Go's path.Match)
   522  		of module path prefixes that should always be fetched directly
   523  		or that should not be compared against the checksum database.
   524  		See 'go help module-private'.
   525  	GOROOT
   526  		The root of the go tree.
   527  	GOSUMDB
   528  		The name of checksum database to use and optionally its public key and
   529  		URL. See 'go help module-auth'.
   530  	GOTMPDIR
   531  		The directory where the go command will write
   532  		temporary source files, packages, and binaries.
   533  
   534  Environment variables for use with cgo:
   535  
   536  	AR
   537  		The command to use to manipulate library archives when
   538  		building with the gccgo compiler.
   539  		The default is 'ar'.
   540  	CC
   541  		The command to use to compile C code.
   542  	CGO_ENABLED
   543  		Whether the cgo command is supported. Either 0 or 1.
   544  	CGO_CFLAGS
   545  		Flags that cgo will pass to the compiler when compiling
   546  		C code.
   547  	CGO_CFLAGS_ALLOW
   548  		A regular expression specifying additional flags to allow
   549  		to appear in #cgo CFLAGS source code directives.
   550  		Does not apply to the CGO_CFLAGS environment variable.
   551  	CGO_CFLAGS_DISALLOW
   552  		A regular expression specifying flags that must be disallowed
   553  		from appearing in #cgo CFLAGS source code directives.
   554  		Does not apply to the CGO_CFLAGS environment variable.
   555  	CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
   556  		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
   557  		but for the C preprocessor.
   558  	CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
   559  		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
   560  		but for the C++ compiler.
   561  	CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
   562  		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
   563  		but for the Fortran compiler.
   564  	CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
   565  		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
   566  		but for the linker.
   567  	CXX
   568  		The command to use to compile C++ code.
   569  	FC
   570  		The command to use to compile Fortran code.
   571  	PKG_CONFIG
   572  		Path to pkg-config tool.
   573  
   574  Architecture-specific environment variables:
   575  
   576  	GOARM
   577  		For GOARCH=arm, the ARM architecture for which to compile.
   578  		Valid values are 5, 6, 7.
   579  	GO386
   580  		For GOARCH=386, the floating point instruction set.
   581  		Valid values are 387, sse2.
   582  	GOMIPS
   583  		For GOARCH=mips{,le}, whether to use floating point instructions.
   584  		Valid values are hardfloat (default), softfloat.
   585  	GOMIPS64
   586  		For GOARCH=mips64{,le}, whether to use floating point instructions.
   587  		Valid values are hardfloat (default), softfloat.
   588  	GOWASM
   589  		For GOARCH=wasm, comma-separated list of experimental WebAssembly features to use.
   590  		Valid values are satconv, signext.
   591  
   592  Special-purpose environment variables:
   593  
   594  	GCCGOTOOLDIR
   595  		If set, where to find gccgo tools, such as cgo.
   596  		The default is based on how gccgo was configured.
   597  	GOROOT_FINAL
   598  		The root of the installed Go tree, when it is
   599  		installed in a location other than where it is built.
   600  		File names in stack traces are rewritten from GOROOT to
   601  		GOROOT_FINAL.
   602  	GO_EXTLINK_ENABLED
   603  		Whether the linker should use external linking mode
   604  		when using -linkmode=auto with code that uses cgo.
   605  		Set to 0 to disable external linking mode, 1 to enable it.
   606  	GIT_ALLOW_PROTOCOL
   607  		Defined by Git. A colon-separated list of schemes that are allowed
   608  		to be used with git fetch/clone. If set, any scheme not explicitly
   609  		mentioned will be considered insecure by 'go get'.
   610  		Because the variable is defined by Git, the default value cannot
   611  		be set using 'go env -w'.
   612  
   613  Additional information available from 'go env' but not read from the environment:
   614  
   615  	GOEXE
   616  		The executable file name suffix (".exe" on Windows, "" on other systems).
   617  	GOGCCFLAGS
   618  		A space-separated list of arguments supplied to the CC command.
   619  	GOHOSTARCH
   620  		The architecture (GOARCH) of the Go toolchain binaries.
   621  	GOHOSTOS
   622  		The operating system (GOOS) of the Go toolchain binaries.
   623  	GOMOD
   624  		The absolute path to the go.mod of the main module.
   625  		If module-aware mode is enabled, but there is no go.mod, GOMOD will be
   626  		os.DevNull ("/dev/null" on Unix-like systems, "NUL" on Windows).
   627  		If module-aware mode is disabled, GOMOD will be the empty string.
   628  	GOTOOLDIR
   629  		The directory where the go tools (compile, cover, doc, etc...) are installed.
   630  	`,
   631  }
   632  
   633  var HelpFileType = &base.Command{
   634  	UsageLine: "filetype",
   635  	Short:     "file types",
   636  	Long: `
   637  The go command examines the contents of a restricted set of files
   638  in each directory. It identifies which files to examine based on
   639  the extension of the file name. These extensions are:
   640  
   641  	.go
   642  		Go source files.
   643  	.c, .h
   644  		C source files.
   645  		If the package uses cgo or SWIG, these will be compiled with the
   646  		OS-native compiler (typically gcc); otherwise they will
   647  		trigger an error.
   648  	.cc, .cpp, .cxx, .hh, .hpp, .hxx
   649  		C++ source files. Only useful with cgo or SWIG, and always
   650  		compiled with the OS-native compiler.
   651  	.m
   652  		Objective-C source files. Only useful with cgo, and always
   653  		compiled with the OS-native compiler.
   654  	.s, .S, .sx
   655  		Assembler source files.
   656  		If the package uses cgo or SWIG, these will be assembled with the
   657  		OS-native assembler (typically gcc (sic)); otherwise they
   658  		will be assembled with the Go assembler.
   659  	.swig, .swigcxx
   660  		SWIG definition files.
   661  	.syso
   662  		System object files.
   663  
   664  Files of each of these types except .syso may contain build
   665  constraints, but the go command stops scanning for build constraints
   666  at the first item in the file that is not a blank line or //-style
   667  line comment. See the go/build package documentation for
   668  more details.
   669  	`,
   670  }
   671  
   672  var HelpBuildmode = &base.Command{
   673  	UsageLine: "buildmode",
   674  	Short:     "build modes",
   675  	Long: `
   676  The 'go build' and 'go install' commands take a -buildmode argument which
   677  indicates which kind of object file is to be built. Currently supported values
   678  are:
   679  
   680  	-buildmode=archive
   681  		Build the listed non-main packages into .a files. Packages named
   682  		main are ignored.
   683  
   684  	-buildmode=c-archive
   685  		Build the listed main package, plus all packages it imports,
   686  		into a C archive file. The only callable symbols will be those
   687  		functions exported using a cgo //export comment. Requires
   688  		exactly one main package to be listed.
   689  
   690  	-buildmode=c-shared
   691  		Build the listed main package, plus all packages it imports,
   692  		into a C shared library. The only callable symbols will
   693  		be those functions exported using a cgo //export comment.
   694  		Requires exactly one main package to be listed.
   695  
   696  	-buildmode=default
   697  		Listed main packages are built into executables and listed
   698  		non-main packages are built into .a files (the default
   699  		behavior).
   700  
   701  	-buildmode=shared
   702  		Combine all the listed non-main packages into a single shared
   703  		library that will be used when building with the -linkshared
   704  		option. Packages named main are ignored.
   705  
   706  	-buildmode=exe
   707  		Build the listed main packages and everything they import into
   708  		executables. Packages not named main are ignored.
   709  
   710  	-buildmode=pie
   711  		Build the listed main packages and everything they import into
   712  		position independent executables (PIE). Packages not named
   713  		main are ignored.
   714  
   715  	-buildmode=plugin
   716  		Build the listed main packages, plus all packages that they
   717  		import, into a Go plugin. Packages not named main are ignored.
   718  
   719  On AIX, when linking a C program that uses a Go archive built with
   720  -buildmode=c-archive, you must pass -Wl,-bnoobjreorder to the C compiler.
   721  `,
   722  }
   723  
   724  var HelpCache = &base.Command{
   725  	UsageLine: "cache",
   726  	Short:     "build and test caching",
   727  	Long: `
   728  The go command caches build outputs for reuse in future builds.
   729  The default location for cache data is a subdirectory named go-build
   730  in the standard user cache directory for the current operating system.
   731  Setting the GOCACHE environment variable overrides this default,
   732  and running 'go env GOCACHE' prints the current cache directory.
   733  
   734  The go command periodically deletes cached data that has not been
   735  used recently. Running 'go clean -cache' deletes all cached data.
   736  
   737  The build cache correctly accounts for changes to Go source files,
   738  compilers, compiler options, and so on: cleaning the cache explicitly
   739  should not be necessary in typical use. However, the build cache
   740  does not detect changes to C libraries imported with cgo.
   741  If you have made changes to the C libraries on your system, you
   742  will need to clean the cache explicitly or else use the -a build flag
   743  (see 'go help build') to force rebuilding of packages that
   744  depend on the updated C libraries.
   745  
   746  The go command also caches successful package test results.
   747  See 'go help test' for details. Running 'go clean -testcache' removes
   748  all cached test results (but not cached build results).
   749  
   750  The GODEBUG environment variable can enable printing of debugging
   751  information about the state of the cache:
   752  
   753  GODEBUG=gocacheverify=1 causes the go command to bypass the
   754  use of any cache entries and instead rebuild everything and check
   755  that the results match existing cache entries.
   756  
   757  GODEBUG=gocachehash=1 causes the go command to print the inputs
   758  for all of the content hashes it uses to construct cache lookup keys.
   759  The output is voluminous but can be useful for debugging the cache.
   760  
   761  GODEBUG=gocachetest=1 causes the go command to print details of its
   762  decisions about whether to reuse a cached test result.
   763  `,
   764  }
   765  

View as plain text