...
Run Format

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,
    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  }
    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, examine a few different
   473  environment variables. For many of these, you can see the default
   474  value of on your system by running 'go env NAME', where NAME is the
   475  name of the variable.
   476  
   477  General-purpose environment variables:
   478  
   479  	GCCGO
   480  		The gccgo command to run for 'go build -compiler=gccgo'.
   481  	GOARCH
   482  		The architecture, or processor, for which to compile code.
   483  		Examples are amd64, 386, arm, ppc64.
   484  	GOBIN
   485  		The directory where 'go install' will install a command.
   486  	GOCACHE
   487  		The directory where the go command will store cached
   488  		information for reuse in future builds.
   489  	GOFLAGS
   490  		A space-separated list of -flag=value settings to apply
   491  		to go commands by default, when the given flag is known by
   492  		the current command. Flags listed on the command-line
   493  		are applied after this list and therefore override it.
   494  	GOOS
   495  		The operating system for which to compile code.
   496  		Examples are linux, darwin, windows, netbsd.
   497  	GOPATH
   498  		For more details see: 'go help gopath'.
   499  	GOPROXY
   500  		URL of Go module proxy. See 'go help goproxy'.
   501  	GORACE
   502  		Options for the race detector.
   503  		See https://golang.org/doc/articles/race_detector.html.
   504  	GOROOT
   505  		The root of the go tree.
   506  	GOTMPDIR
   507  		The directory where the go command will write
   508  		temporary source files, packages, and binaries.
   509  
   510  Each entry in the GOFLAGS list must be a standalone flag.
   511  Because the entries are space-separated, flag values must
   512  not contain spaces.
   513  
   514  Environment variables for use with cgo:
   515  
   516  	CC
   517  		The command to use to compile C code.
   518  	CGO_ENABLED
   519  		Whether the cgo command is supported. Either 0 or 1.
   520  	CGO_CFLAGS
   521  		Flags that cgo will pass to the compiler when compiling
   522  		C code.
   523  	CGO_CFLAGS_ALLOW
   524  		A regular expression specifying additional flags to allow
   525  		to appear in #cgo CFLAGS source code directives.
   526  		Does not apply to the CGO_CFLAGS environment variable.
   527  	CGO_CFLAGS_DISALLOW
   528  		A regular expression specifying flags that must be disallowed
   529  		from appearing in #cgo CFLAGS source code directives.
   530  		Does not apply to the CGO_CFLAGS environment variable.
   531  	CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
   532  		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
   533  		but for the C preprocessor.
   534  	CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
   535  		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
   536  		but for the C++ compiler.
   537  	CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
   538  		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
   539  		but for the Fortran compiler.
   540  	CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
   541  		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
   542  		but for the linker.
   543  	CXX
   544  		The command to use to compile C++ code.
   545  	PKG_CONFIG
   546  		Path to pkg-config tool.
   547  	AR
   548  		The command to use to manipulate library archives when
   549  		building with the gccgo compiler.
   550  		The default is 'ar'.
   551  
   552  Architecture-specific environment variables:
   553  
   554  	GOARM
   555  		For GOARCH=arm, the ARM architecture for which to compile.
   556  		Valid values are 5, 6, 7.
   557  	GO386
   558  		For GOARCH=386, the floating point instruction set.
   559  		Valid values are 387, sse2.
   560  	GOMIPS
   561  		For GOARCH=mips{,le}, whether to use floating point instructions.
   562  		Valid values are hardfloat (default), softfloat.
   563  	GOMIPS64
   564  		For GOARCH=mips64{,le}, whether to use floating point instructions.
   565  		Valid values are hardfloat (default), softfloat.
   566  
   567  Special-purpose environment variables:
   568  
   569  	GCCGOTOOLDIR
   570  		If set, where to find gccgo tools, such as cgo.
   571  		The default is based on how gccgo was configured.
   572  	GOROOT_FINAL
   573  		The root of the installed Go tree, when it is
   574  		installed in a location other than where it is built.
   575  		File names in stack traces are rewritten from GOROOT to
   576  		GOROOT_FINAL.
   577  	GO_EXTLINK_ENABLED
   578  		Whether the linker should use external linking mode
   579  		when using -linkmode=auto with code that uses cgo.
   580  		Set to 0 to disable external linking mode, 1 to enable it.
   581  	GIT_ALLOW_PROTOCOL
   582  		Defined by Git. A colon-separated list of schemes that are allowed to be used
   583  		with git fetch/clone. If set, any scheme not explicitly mentioned will be
   584  		considered insecure by 'go get'.
   585  
   586  Additional information available from 'go env' but not read from the environment:
   587  
   588  	GOEXE
   589  		The executable file name suffix (".exe" on Windows, "" on other systems).
   590  	GOHOSTARCH
   591  		The architecture (GOARCH) of the Go toolchain binaries.
   592  	GOHOSTOS
   593  		The operating system (GOOS) of the Go toolchain binaries.
   594  	GOMOD
   595  		The absolute path to the go.mod of the main module,
   596  		or the empty string if not using modules.
   597  	GOTOOLDIR
   598  		The directory where the go tools (compile, cover, doc, etc...) are installed.
   599  	`,
   600  }
   601  
   602  var HelpFileType = &base.Command{
   603  	UsageLine: "filetype",
   604  	Short:     "file types",
   605  	Long: `
   606  The go command examines the contents of a restricted set of files
   607  in each directory. It identifies which files to examine based on
   608  the extension of the file name. These extensions are:
   609  
   610  	.go
   611  		Go source files.
   612  	.c, .h
   613  		C source files.
   614  		If the package uses cgo or SWIG, these will be compiled with the
   615  		OS-native compiler (typically gcc); otherwise they will
   616  		trigger an error.
   617  	.cc, .cpp, .cxx, .hh, .hpp, .hxx
   618  		C++ source files. Only useful with cgo or SWIG, and always
   619  		compiled with the OS-native compiler.
   620  	.m
   621  		Objective-C source files. Only useful with cgo, and always
   622  		compiled with the OS-native compiler.
   623  	.s, .S
   624  		Assembler source files.
   625  		If the package uses cgo or SWIG, these will be assembled with the
   626  		OS-native assembler (typically gcc (sic)); otherwise they
   627  		will be assembled with the Go assembler.
   628  	.swig, .swigcxx
   629  		SWIG definition files.
   630  	.syso
   631  		System object files.
   632  
   633  Files of each of these types except .syso may contain build
   634  constraints, but the go command stops scanning for build constraints
   635  at the first item in the file that is not a blank line or //-style
   636  line comment. See the go/build package documentation for
   637  more details.
   638  
   639  Through the Go 1.12 release, non-test Go source files can also include
   640  a //go:binary-only-package comment, indicating that the package
   641  sources are included for documentation only and must not be used to
   642  build the package binary. This enables distribution of Go packages in
   643  their compiled form alone. Even binary-only packages require accurate
   644  import blocks listing required dependencies, so that those
   645  dependencies can be supplied when linking the resulting command.
   646  Note that this feature is scheduled to be removed after the Go 1.12 release.
   647  	`,
   648  }
   649  
   650  var HelpBuildmode = &base.Command{
   651  	UsageLine: "buildmode",
   652  	Short:     "build modes",
   653  	Long: `
   654  The 'go build' and 'go install' commands take a -buildmode argument which
   655  indicates which kind of object file is to be built. Currently supported values
   656  are:
   657  
   658  	-buildmode=archive
   659  		Build the listed non-main packages into .a files. Packages named
   660  		main are ignored.
   661  
   662  	-buildmode=c-archive
   663  		Build the listed main package, plus all packages it imports,
   664  		into a C archive file. The only callable symbols will be those
   665  		functions exported using a cgo //export comment. Requires
   666  		exactly one main package to be listed.
   667  
   668  	-buildmode=c-shared
   669  		Build the listed main package, plus all packages it imports,
   670  		into a C shared library. The only callable symbols will
   671  		be those functions exported using a cgo //export comment.
   672  		Requires exactly one main package to be listed.
   673  
   674  	-buildmode=default
   675  		Listed main packages are built into executables and listed
   676  		non-main packages are built into .a files (the default
   677  		behavior).
   678  
   679  	-buildmode=shared
   680  		Combine all the listed non-main packages into a single shared
   681  		library that will be used when building with the -linkshared
   682  		option. Packages named main are ignored.
   683  
   684  	-buildmode=exe
   685  		Build the listed main packages and everything they import into
   686  		executables. Packages not named main are ignored.
   687  
   688  	-buildmode=pie
   689  		Build the listed main packages and everything they import into
   690  		position independent executables (PIE). Packages not named
   691  		main are ignored.
   692  
   693  	-buildmode=plugin
   694  		Build the listed main packages, plus all packages that they
   695  		import, into a Go plugin. Packages not named main are ignored.
   696  `,
   697  }
   698  
   699  var HelpCache = &base.Command{
   700  	UsageLine: "cache",
   701  	Short:     "build and test caching",
   702  	Long: `
   703  The go command caches build outputs for reuse in future builds.
   704  The default location for cache data is a subdirectory named go-build
   705  in the standard user cache directory for the current operating system.
   706  Setting the GOCACHE environment variable overrides this default,
   707  and running 'go env GOCACHE' prints the current cache directory.
   708  
   709  The go command periodically deletes cached data that has not been
   710  used recently. Running 'go clean -cache' deletes all cached data.
   711  
   712  The build cache correctly accounts for changes to Go source files,
   713  compilers, compiler options, and so on: cleaning the cache explicitly
   714  should not be necessary in typical use. However, the build cache
   715  does not detect changes to C libraries imported with cgo.
   716  If you have made changes to the C libraries on your system, you
   717  will need to clean the cache explicitly or else use the -a build flag
   718  (see 'go help build') to force rebuilding of packages that
   719  depend on the updated C libraries.
   720  
   721  The go command also caches successful package test results.
   722  See 'go help test' for details. Running 'go clean -testcache' removes
   723  all cached test results (but not cached build results).
   724  
   725  The GODEBUG environment variable can enable printing of debugging
   726  information about the state of the cache:
   727  
   728  GODEBUG=gocacheverify=1 causes the go command to bypass the
   729  use of any cache entries and instead rebuild everything and check
   730  that the results match existing cache entries.
   731  
   732  GODEBUG=gocachehash=1 causes the go command to print the inputs
   733  for all of the content hashes it uses to construct cache lookup keys.
   734  The output is voluminous but can be useful for debugging the cache.
   735  
   736  GODEBUG=gocachetest=1 causes the go command to print details of its
   737  decisions about whether to reuse a cached test result.
   738  `,
   739  }
   740  

View as plain text