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.
     5  package help
     7  import "cmd/go/internal/base"
     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.
    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).
    18  The second is the SWIG program, which is a general tool for
    19  interfacing between languages. For information on SWIG see
    20 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.
    24  When either cgo or SWIG is used, go build will pass any .c, .m, .s,
    25  or .S 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  }
    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:
    37  	go action [packages]
    39  Usually, [packages] is a list of import paths.
    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.
    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').
    49  If no import paths are given, the action applies to the
    50  package in the current directory.
    52  There are four reserved names for paths that should not be used
    53  for packages to be built with the go tool:
    55  - "main" denotes the top-level package in a stand-alone executable.
    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.
    63  - "std" is like all but expands to just the packages in the standard
    64  Go library.
    66  - "cmd" expands to the Go repository's commands and their
    67  internal libraries.
    69  Import paths beginning with "cmd/" only match source code in
    70  the Go repository.
    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.
    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 for more about vendoring.
    90  An import path can also name a package to be downloaded from
    91  a remote repository. Run 'go help importpath' for details.
    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 ''.
   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.
   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.
   113  Directory and file names that begin with "." or "_" are ignored
   114  by the go tool, as are directories named "testdata".
   115  	`,
   116  }
   118  var HelpImportPath = &base.Command{
   119  	UsageLine: "importpath",
   120  	Short:     "import path syntax",
   121  	Long: `
   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').
   128  Relative import paths
   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.
   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.
   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.
   152  Remote import paths
   154  Certain import paths also
   155  describe how to obtain the source code for the package using
   156  a revision control system.
   158  A few common code hosting sites have special syntax:
   160  	Bitbucket (Git, Mercurial)
   162  		import ""
   163  		import ""
   165  	GitHub (Git)
   167  		import ""
   168  		import ""
   170  	Launchpad (Bazaar)
   172  		import ""
   173  		import ""
   174  		import ""
   176  		import ""
   177  		import ""
   179  	IBM DevOps Services (Git)
   181  		import ""
   182  		import ""
   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.
   189  To declare the code location, an import path of the form
   191  	repository.vcs/path
   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:
   197  	Bazaar      .bzr
   198  	Fossil      .fossil
   199  	Git         .git
   200  	Mercurial   .hg
   201  	Subversion  .svn
   203  For example,
   205  	import ""
   207  denotes the root directory of the Mercurial repository at
   208 or foo.hg, and
   210  	import ""
   212  denotes the foo/bar directory of the Git repository at
   213 or repo.git.
   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://.
   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').
   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>.
   229  The meta tag has the form:
   231  	<meta name="go-import" content="import-prefix vcs repo-root">
   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.
   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.
   242  The vcs is one of "bzr", "fossil", "git", "hg", "svn".
   244  The repo-root is the root of the version control system
   245  containing a scheme and not containing a .vcs qualifier.
   247  For example,
   249  	import ""
   251  will result in the following requests:
   253 (preferred)
   254  (fallback, only with -insecure)
   256  If that page contains the meta tag
   258  	<meta name="go-import" content=" git">
   260  the go tool will verify that contains the
   261  same meta tag and then git clone into
   262  GOPATH/src/
   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'.)
   268  When using modules, downloaded packages are stored in the module cache.
   269  (See 'go help module-get' and 'go help goproxy'.)
   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:
   275  	<meta name="go-import" content=" mod">
   277  This tag means to fetch modules with paths beginning with
   278  from the module proxy available at the URL
   279  See 'go help goproxy' for details about the proxy protocol.
   281  Import path checking
   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.
   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:
   290  	package math // import "path"
   291  	package math /* import "path" */
   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.
   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.
   302  Import path checking is also disabled when using modules.
   303  Import path comments are obsoleted by the go.mod file's module statement.
   305  See for details.
   306  	`,
   307  }
   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.
   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.
   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.
   327  See to set a custom GOPATH.
   329  Each directory listed in GOPATH must have a prescribed structure:
   331  The src directory holds source code. The path below src
   332  determines the import path or executable name.
   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).
   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".
   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.
   353  Here's an example directory layout:
   355      GOPATH=/home/user/go
   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)
   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.
   375  See for an example.
   377  GOPATH and Modules
   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).
   383  Internal Directories
   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:
   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
   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.
   411  See for details.
   413  Vendor Directories
   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.
   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.
   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:
   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
   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".
   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".
   453  Code in vendor directories is not subject to import path
   454  checking (see 'go help importpath').
   456  When 'go get' checks out or updates a git repository, it now also
   457  updates submodules.
   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.
   463  See for details.
   464  	`,
   465  }
   467  var HelpEnvironment = &base.Command{
   468  	UsageLine: "environment",
   469  	Short:     "environment variables",
   470  	Long: `
   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.
   484  General-purpose environment variables:
   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  	GOOS
   510  		The operating system for which to compile code.
   511  		Examples are linux, darwin, windows, netbsd.
   512  	GOPATH
   513  		For more details see: 'go help gopath'.
   514  	GOPROXY
   515  		URL of Go module proxy. See 'go help modules'.
   517  		Comma-separated list of glob patterns (in the syntax of Go's path.Match)
   518  		of module path prefixes that should always be fetched directly
   519  		or that should not be compared against the checksum database.
   520  		See 'go help module-private'.
   521  	GOROOT
   522  		The root of the go tree.
   523  	GOSUMDB
   524  		The name of checksum database to use and optionally its public key and
   525  		URL. See 'go help module-auth'.
   526  	GOTMPDIR
   527  		The directory where the go command will write
   528  		temporary source files, packages, and binaries.
   530  Environment variables for use with cgo:
   532  	AR
   533  		The command to use to manipulate library archives when
   534  		building with the gccgo compiler.
   535  		The default is 'ar'.
   536  	CC
   537  		The command to use to compile C code.
   538  	CGO_ENABLED
   539  		Whether the cgo command is supported. Either 0 or 1.
   540  	CGO_CFLAGS
   541  		Flags that cgo will pass to the compiler when compiling
   542  		C code.
   544  		A regular expression specifying additional flags to allow
   545  		to appear in #cgo CFLAGS source code directives.
   546  		Does not apply to the CGO_CFLAGS environment variable.
   548  		A regular expression specifying flags that must be disallowed
   549  		from appearing in #cgo CFLAGS source code directives.
   550  		Does not apply to the CGO_CFLAGS environment variable.
   553  		but for the C preprocessor.
   556  		but for the C++ compiler.
   559  		but for the Fortran compiler.
   562  		but for the linker.
   563  	CXX
   564  		The command to use to compile C++ code.
   565  	FC
   566  		The command to use to compile Fortran code.
   567  	PKG_CONFIG
   568  		Path to pkg-config tool.
   570  Architecture-specific environment variables:
   572  	GOARM
   573  		For GOARCH=arm, the ARM architecture for which to compile.
   574  		Valid values are 5, 6, 7.
   575  	GO386
   576  		For GOARCH=386, the floating point instruction set.
   577  		Valid values are 387, sse2.
   578  	GOMIPS
   579  		For GOARCH=mips{,le}, whether to use floating point instructions.
   580  		Valid values are hardfloat (default), softfloat.
   581  	GOMIPS64
   582  		For GOARCH=mips64{,le}, whether to use floating point instructions.
   583  		Valid values are hardfloat (default), softfloat.
   584  	GOWASM
   585  		For GOARCH=wasm, comma-separated list of experimental WebAssembly features to use.
   586  		Valid values are satconv, signext.
   588  Special-purpose environment variables:
   591  		If set, where to find gccgo tools, such as cgo.
   592  		The default is based on how gccgo was configured.
   594  		The root of the installed Go tree, when it is
   595  		installed in a location other than where it is built.
   596  		File names in stack traces are rewritten from GOROOT to
   597  		GOROOT_FINAL.
   599  		Whether the linker should use external linking mode
   600  		when using -linkmode=auto with code that uses cgo.
   601  		Set to 0 to disable external linking mode, 1 to enable it.
   603  		Defined by Git. A colon-separated list of schemes that are allowed
   604  		to be used with git fetch/clone. If set, any scheme not explicitly
   605  		mentioned will be considered insecure by 'go get'.
   606  		Because the variable is defined by Git, the default value cannot
   607  		be set using 'go env -w'.
   609  Additional information available from 'go env' but not read from the environment:
   611  	GOEXE
   612  		The executable file name suffix (".exe" on Windows, "" on other systems).
   614  		A space-separated list of arguments supplied to the CC command.
   616  		The architecture (GOARCH) of the Go toolchain binaries.
   617  	GOHOSTOS
   618  		The operating system (GOOS) of the Go toolchain binaries.
   619  	GOMOD
   620  		The absolute path to the go.mod of the main module,
   621  		or the empty string if not using modules.
   622  	GOTOOLDIR
   623  		The directory where the go tools (compile, cover, doc, etc...) are installed.
   624  	`,
   625  }
   627  var HelpFileType = &base.Command{
   628  	UsageLine: "filetype",
   629  	Short:     "file types",
   630  	Long: `
   631  The go command examines the contents of a restricted set of files
   632  in each directory. It identifies which files to examine based on
   633  the extension of the file name. These extensions are:
   635  	.go
   636  		Go source files.
   637  	.c, .h
   638  		C source files.
   639  		If the package uses cgo or SWIG, these will be compiled with the
   640  		OS-native compiler (typically gcc); otherwise they will
   641  		trigger an error.
   642  	.cc, .cpp, .cxx, .hh, .hpp, .hxx
   643  		C++ source files. Only useful with cgo or SWIG, and always
   644  		compiled with the OS-native compiler.
   645  	.m
   646  		Objective-C source files. Only useful with cgo, and always
   647  		compiled with the OS-native compiler.
   648  	.s, .S
   649  		Assembler source files.
   650  		If the package uses cgo or SWIG, these will be assembled with the
   651  		OS-native assembler (typically gcc (sic)); otherwise they
   652  		will be assembled with the Go assembler.
   653  	.swig, .swigcxx
   654  		SWIG definition files.
   655  	.syso
   656  		System object files.
   658  Files of each of these types except .syso may contain build
   659  constraints, but the go command stops scanning for build constraints
   660  at the first item in the file that is not a blank line or //-style
   661  line comment. See the go/build package documentation for
   662  more details.
   663  	`,
   664  }
   666  var HelpBuildmode = &base.Command{
   667  	UsageLine: "buildmode",
   668  	Short:     "build modes",
   669  	Long: `
   670  The 'go build' and 'go install' commands take a -buildmode argument which
   671  indicates which kind of object file is to be built. Currently supported values
   672  are:
   674  	-buildmode=archive
   675  		Build the listed non-main packages into .a files. Packages named
   676  		main are ignored.
   678  	-buildmode=c-archive
   679  		Build the listed main package, plus all packages it imports,
   680  		into a C archive file. The only callable symbols will be those
   681  		functions exported using a cgo //export comment. Requires
   682  		exactly one main package to be listed.
   684  	-buildmode=c-shared
   685  		Build the listed main package, plus all packages it imports,
   686  		into a C shared library. The only callable symbols will
   687  		be those functions exported using a cgo //export comment.
   688  		Requires exactly one main package to be listed.
   690  	-buildmode=default
   691  		Listed main packages are built into executables and listed
   692  		non-main packages are built into .a files (the default
   693  		behavior).
   695  	-buildmode=shared
   696  		Combine all the listed non-main packages into a single shared
   697  		library that will be used when building with the -linkshared
   698  		option. Packages named main are ignored.
   700  	-buildmode=exe
   701  		Build the listed main packages and everything they import into
   702  		executables. Packages not named main are ignored.
   704  	-buildmode=pie
   705  		Build the listed main packages and everything they import into
   706  		position independent executables (PIE). Packages not named
   707  		main are ignored.
   709  	-buildmode=plugin
   710  		Build the listed main packages, plus all packages that they
   711  		import, into a Go plugin. Packages not named main are ignored.
   713  On AIX, when linking a C program that uses a Go archive built with
   714  -buildmode=c-archive, you must pass -Wl,-bnoobjreorder to the C compiler.
   715  `,
   716  }
   718  var HelpCache = &base.Command{
   719  	UsageLine: "cache",
   720  	Short:     "build and test caching",
   721  	Long: `
   722  The go command caches build outputs for reuse in future builds.
   723  The default location for cache data is a subdirectory named go-build
   724  in the standard user cache directory for the current operating system.
   725  Setting the GOCACHE environment variable overrides this default,
   726  and running 'go env GOCACHE' prints the current cache directory.
   728  The go command periodically deletes cached data that has not been
   729  used recently. Running 'go clean -cache' deletes all cached data.
   731  The build cache correctly accounts for changes to Go source files,
   732  compilers, compiler options, and so on: cleaning the cache explicitly
   733  should not be necessary in typical use. However, the build cache
   734  does not detect changes to C libraries imported with cgo.
   735  If you have made changes to the C libraries on your system, you
   736  will need to clean the cache explicitly or else use the -a build flag
   737  (see 'go help build') to force rebuilding of packages that
   738  depend on the updated C libraries.
   740  The go command also caches successful package test results.
   741  See 'go help test' for details. Running 'go clean -testcache' removes
   742  all cached test results (but not cached build results).
   744  The GODEBUG environment variable can enable printing of debugging
   745  information about the state of the cache:
   747  GODEBUG=gocacheverify=1 causes the go command to bypass the
   748  use of any cache entries and instead rebuild everything and check
   749  that the results match existing cache entries.
   751  GODEBUG=gocachehash=1 causes the go command to print the inputs
   752  for all of the content hashes it uses to construct cache lookup keys.
   753  The output is voluminous but can be useful for debugging the cache.
   755  GODEBUG=gocachetest=1 causes the go command to print details of its
   756  decisions about whether to reuse a cached test result.
   757  `,
   758  }

View as plain text