github.com/gocuntian/go@v0.0.0-20160610041250-fee02d270bf8/src/cmd/go/help.go (about) 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 main 6 7 var helpC = &Command{ 8 UsageLine: "c", 9 Short: "calling between Go and C", 10 Long: ` 11 There are two different ways to call between Go and C/C++ code. 12 13 The first is the cgo tool, which is part of the Go distribution. For 14 information on how to use it see the cgo documentation (go doc cmd/cgo). 15 16 The second is the SWIG program, which is a general tool for 17 interfacing between languages. For information on SWIG see 18 http://swig.org/. When running go build, any file with a .swig 19 extension will be passed to SWIG. Any file with a .swigcxx extension 20 will be passed to SWIG with the -c++ option. 21 22 When either cgo or SWIG is used, go build will pass any .c, .m, .s, 23 or .S files to the C compiler, and any .cc, .cpp, .cxx files to the C++ 24 compiler. The CC or CXX environment variables may be set to determine 25 the C or C++ compiler, respectively, to use. 26 `, 27 } 28 29 var helpPackages = &Command{ 30 UsageLine: "packages", 31 Short: "description of package lists", 32 Long: ` 33 Many commands apply to a set of packages: 34 35 go action [packages] 36 37 Usually, [packages] is a list of import paths. 38 39 An import path that is a rooted path or that begins with 40 a . or .. element is interpreted as a file system path and 41 denotes the package in that directory. 42 43 Otherwise, the import path P denotes the package found in 44 the directory DIR/src/P for some DIR listed in the GOPATH 45 environment variable (see 'go help gopath'). 46 47 If no import paths are given, the action applies to the 48 package in the current directory. 49 50 There are four reserved names for paths that should not be used 51 for packages to be built with the go tool: 52 53 - "main" denotes the top-level package in a stand-alone executable. 54 55 - "all" expands to all package directories found in all the GOPATH 56 trees. For example, 'go list all' lists all the packages on the local 57 system. 58 59 - "std" is like all but expands to just the packages in the standard 60 Go library. 61 62 - "cmd" expands to the Go repository's commands and their 63 internal libraries. 64 65 An import path is a pattern if it includes one or more "..." wildcards, 66 each of which can match any string, including the empty string and 67 strings containing slashes. Such a pattern expands to all package 68 directories found in the GOPATH trees with names matching the 69 patterns. As a special case, x/... matches x as well as x's subdirectories. 70 For example, net/... expands to net and packages in its subdirectories. 71 72 An import path can also name a package to be downloaded from 73 a remote repository. Run 'go help importpath' for details. 74 75 Every package in a program must have a unique import path. 76 By convention, this is arranged by starting each path with a 77 unique prefix that belongs to you. For example, paths used 78 internally at Google all begin with 'google', and paths 79 denoting remote repositories begin with the path to the code, 80 such as 'github.com/user/repo'. 81 82 Packages in a program need not have unique package names, 83 but there are two reserved package names with special meaning. 84 The name main indicates a command, not a library. 85 Commands are built into binaries and cannot be imported. 86 The name documentation indicates documentation for 87 a non-Go program in the directory. Files in package documentation 88 are ignored by the go command. 89 90 As a special case, if the package list is a list of .go files from a 91 single directory, the command is applied to a single synthesized 92 package made up of exactly those files, ignoring any build constraints 93 in those files and ignoring any other files in the directory. 94 95 Directory and file names that begin with "." or "_" are ignored 96 by the go tool, as are directories named "testdata". 97 `, 98 } 99 100 var helpImportPath = &Command{ 101 UsageLine: "importpath", 102 Short: "import path syntax", 103 Long: ` 104 105 An import path (see 'go help packages') denotes a package 106 stored in the local file system. In general, an import path denotes 107 either a standard package (such as "unicode/utf8") or a package 108 found in one of the work spaces (see 'go help gopath'). 109 110 Relative import paths 111 112 An import path beginning with ./ or ../ is called a relative path. 113 The toolchain supports relative import paths as a shortcut in two ways. 114 115 First, a relative path can be used as a shorthand on the command line. 116 If you are working in the directory containing the code imported as 117 "unicode" and want to run the tests for "unicode/utf8", you can type 118 "go test ./utf8" instead of needing to specify the full path. 119 Similarly, in the reverse situation, "go test .." will test "unicode" from 120 the "unicode/utf8" directory. Relative patterns are also allowed, like 121 "go test ./..." to test all subdirectories. See 'go help packages' for details 122 on the pattern syntax. 123 124 Second, if you are compiling a Go program not in a work space, 125 you can use a relative path in an import statement in that program 126 to refer to nearby code also not in a work space. 127 This makes it easy to experiment with small multipackage programs 128 outside of the usual work spaces, but such programs cannot be 129 installed with "go install" (there is no work space in which to install them), 130 so they are rebuilt from scratch each time they are built. 131 To avoid ambiguity, Go programs cannot use relative import paths 132 within a work space. 133 134 Remote import paths 135 136 Certain import paths also 137 describe how to obtain the source code for the package using 138 a revision control system. 139 140 A few common code hosting sites have special syntax: 141 142 Bitbucket (Git, Mercurial) 143 144 import "bitbucket.org/user/project" 145 import "bitbucket.org/user/project/sub/directory" 146 147 GitHub (Git) 148 149 import "github.com/user/project" 150 import "github.com/user/project/sub/directory" 151 152 Launchpad (Bazaar) 153 154 import "launchpad.net/project" 155 import "launchpad.net/project/series" 156 import "launchpad.net/project/series/sub/directory" 157 158 import "launchpad.net/~user/project/branch" 159 import "launchpad.net/~user/project/branch/sub/directory" 160 161 IBM DevOps Services (Git) 162 163 import "hub.jazz.net/git/user/project" 164 import "hub.jazz.net/git/user/project/sub/directory" 165 166 For code hosted on other servers, import paths may either be qualified 167 with the version control type, or the go tool can dynamically fetch 168 the import path over https/http and discover where the code resides 169 from a <meta> tag in the HTML. 170 171 To declare the code location, an import path of the form 172 173 repository.vcs/path 174 175 specifies the given repository, with or without the .vcs suffix, 176 using the named version control system, and then the path inside 177 that repository. The supported version control systems are: 178 179 Bazaar .bzr 180 Git .git 181 Mercurial .hg 182 Subversion .svn 183 184 For example, 185 186 import "example.org/user/foo.hg" 187 188 denotes the root directory of the Mercurial repository at 189 example.org/user/foo or foo.hg, and 190 191 import "example.org/repo.git/foo/bar" 192 193 denotes the foo/bar directory of the Git repository at 194 example.org/repo or repo.git. 195 196 When a version control system supports multiple protocols, 197 each is tried in turn when downloading. For example, a Git 198 download tries https://, then git+ssh://. 199 200 If the import path is not a known code hosting site and also lacks a 201 version control qualifier, the go tool attempts to fetch the import 202 over https/http and looks for a <meta> tag in the document's HTML 203 <head>. 204 205 The meta tag has the form: 206 207 <meta name="go-import" content="import-prefix vcs repo-root"> 208 209 The import-prefix is the import path corresponding to the repository 210 root. It must be a prefix or an exact match of the package being 211 fetched with "go get". If it's not an exact match, another http 212 request is made at the prefix to verify the <meta> tags match. 213 214 The meta tag should appear as early in the file as possible. 215 In particular, it should appear before any raw JavaScript or CSS, 216 to avoid confusing the go command's restricted parser. 217 218 The vcs is one of "git", "hg", "svn", etc, 219 220 The repo-root is the root of the version control system 221 containing a scheme and not containing a .vcs qualifier. 222 223 For example, 224 225 import "example.org/pkg/foo" 226 227 will result in the following requests: 228 229 https://example.org/pkg/foo?go-get=1 (preferred) 230 http://example.org/pkg/foo?go-get=1 (fallback, only with -insecure) 231 232 If that page contains the meta tag 233 234 <meta name="go-import" content="example.org git https://code.org/r/p/exproj"> 235 236 the go tool will verify that https://example.org/?go-get=1 contains the 237 same meta tag and then git clone https://code.org/r/p/exproj into 238 GOPATH/src/example.org. 239 240 New downloaded packages are written to the first directory 241 listed in the GOPATH environment variable (see 'go help gopath'). 242 243 The go command attempts to download the version of the 244 package appropriate for the Go release being used. 245 Run 'go help get' for more. 246 247 Import path checking 248 249 When the custom import path feature described above redirects to a 250 known code hosting site, each of the resulting packages has two possible 251 import paths, using the custom domain or the known hosting site. 252 253 A package statement is said to have an "import comment" if it is immediately 254 followed (before the next newline) by a comment of one of these two forms: 255 256 package math // import "path" 257 package math /* import "path" */ 258 259 The go command will refuse to install a package with an import comment 260 unless it is being referred to by that import path. In this way, import comments 261 let package authors make sure the custom import path is used and not a 262 direct path to the underlying code hosting site. 263 264 If vendoring is enabled (see 'go help gopath'), then import path checking is 265 disabled for code found within vendor trees. This makes it possible to copy 266 code into alternate locations in vendor trees without needing to update import 267 comments. 268 269 See https://golang.org/s/go14customimport for details. 270 `, 271 } 272 273 var helpGopath = &Command{ 274 UsageLine: "gopath", 275 Short: "GOPATH environment variable", 276 Long: ` 277 The Go path is used to resolve import statements. 278 It is implemented by and documented in the go/build package. 279 280 The GOPATH environment variable lists places to look for Go code. 281 On Unix, the value is a colon-separated string. 282 On Windows, the value is a semicolon-separated string. 283 On Plan 9, the value is a list. 284 285 GOPATH must be set to get, build and install packages outside the 286 standard Go tree. 287 288 Each directory listed in GOPATH must have a prescribed structure: 289 290 The src directory holds source code. The path below src 291 determines the import path or executable name. 292 293 The pkg directory holds installed package objects. 294 As in the Go tree, each target operating system and 295 architecture pair has its own subdirectory of pkg 296 (pkg/GOOS_GOARCH). 297 298 If DIR is a directory listed in the GOPATH, a package with 299 source in DIR/src/foo/bar can be imported as "foo/bar" and 300 has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a". 301 302 The bin directory holds compiled commands. 303 Each command is named for its source directory, but only 304 the final element, not the entire path. That is, the 305 command with source in DIR/src/foo/quux is installed into 306 DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped 307 so that you can add DIR/bin to your PATH to get at the 308 installed commands. If the GOBIN environment variable is 309 set, commands are installed to the directory it names instead 310 of DIR/bin. GOBIN must be an absolute path. 311 312 Here's an example directory layout: 313 314 GOPATH=/home/user/gocode 315 316 /home/user/gocode/ 317 src/ 318 foo/ 319 bar/ (go code in package bar) 320 x.go 321 quux/ (go code in package main) 322 y.go 323 bin/ 324 quux (installed command) 325 pkg/ 326 linux_amd64/ 327 foo/ 328 bar.a (installed package object) 329 330 Go searches each directory listed in GOPATH to find source code, 331 but new packages are always downloaded into the first directory 332 in the list. 333 334 See https://golang.org/doc/code.html for an example. 335 336 Internal Directories 337 338 Code in or below a directory named "internal" is importable only 339 by code in the directory tree rooted at the parent of "internal". 340 Here's an extended version of the directory layout above: 341 342 /home/user/gocode/ 343 src/ 344 crash/ 345 bang/ (go code in package bang) 346 b.go 347 foo/ (go code in package foo) 348 f.go 349 bar/ (go code in package bar) 350 x.go 351 internal/ 352 baz/ (go code in package baz) 353 z.go 354 quux/ (go code in package main) 355 y.go 356 357 358 The code in z.go is imported as "foo/internal/baz", but that 359 import statement can only appear in source files in the subtree 360 rooted at foo. The source files foo/f.go, foo/bar/x.go, and 361 foo/quux/y.go can all import "foo/internal/baz", but the source file 362 crash/bang/b.go cannot. 363 364 See https://golang.org/s/go14internal for details. 365 366 Vendor Directories 367 368 Go 1.6 includes support for using local copies of external dependencies 369 to satisfy imports of those dependencies, often referred to as vendoring. 370 371 Code below a directory named "vendor" is importable only 372 by code in the directory tree rooted at the parent of "vendor", 373 and only using an import path that omits the prefix up to and 374 including the vendor element. 375 376 Here's the example from the previous section, 377 but with the "internal" directory renamed to "vendor" 378 and a new foo/vendor/crash/bang directory added: 379 380 /home/user/gocode/ 381 src/ 382 crash/ 383 bang/ (go code in package bang) 384 b.go 385 foo/ (go code in package foo) 386 f.go 387 bar/ (go code in package bar) 388 x.go 389 vendor/ 390 crash/ 391 bang/ (go code in package bang) 392 b.go 393 baz/ (go code in package baz) 394 z.go 395 quux/ (go code in package main) 396 y.go 397 398 The same visibility rules apply as for internal, but the code 399 in z.go is imported as "baz", not as "foo/vendor/baz". 400 401 Code in vendor directories deeper in the source tree shadows 402 code in higher directories. Within the subtree rooted at foo, an import 403 of "crash/bang" resolves to "foo/vendor/crash/bang", not the 404 top-level "crash/bang". 405 406 Code in vendor directories is not subject to import path 407 checking (see 'go help importpath'). 408 409 When 'go get' checks out or updates a git repository, it now also 410 updates submodules. 411 412 Vendor directories do not affect the placement of new repositories 413 being checked out for the first time by 'go get': those are always 414 placed in the main GOPATH, never in a vendor subtree. 415 416 See https://golang.org/s/go15vendor for details. 417 `, 418 } 419 420 var helpEnvironment = &Command{ 421 UsageLine: "environment", 422 Short: "environment variables", 423 Long: ` 424 425 The go command, and the tools it invokes, examine a few different 426 environment variables. For many of these, you can see the default 427 value of on your system by running 'go env NAME', where NAME is the 428 name of the variable. 429 430 General-purpose environment variables: 431 432 GCCGO 433 The gccgo command to run for 'go build -compiler=gccgo'. 434 GOARCH 435 The architecture, or processor, for which to compile code. 436 Examples are amd64, 386, arm, ppc64. 437 GOBIN 438 The directory where 'go install' will install a command. 439 GOOS 440 The operating system for which to compile code. 441 Examples are linux, darwin, windows, netbsd. 442 GOPATH 443 See 'go help gopath'. 444 GORACE 445 Options for the race detector. 446 See https://golang.org/doc/articles/race_detector.html. 447 GOROOT 448 The root of the go tree. 449 450 Environment variables for use with cgo: 451 452 CC 453 The command to use to compile C code. 454 CGO_ENABLED 455 Whether the cgo command is supported. Either 0 or 1. 456 CGO_CFLAGS 457 Flags that cgo will pass to the compiler when compiling 458 C code. 459 CGO_CPPFLAGS 460 Flags that cgo will pass to the compiler when compiling 461 C or C++ code. 462 CGO_CXXFLAGS 463 Flags that cgo will pass to the compiler when compiling 464 C++ code. 465 CGO_LDFLAGS 466 Flags that cgo will pass to the compiler when linking. 467 CXX 468 The command to use to compile C++ code. 469 470 Architecture-specific environment variables: 471 472 GOARM 473 For GOARCH=arm, the ARM architecture for which to compile. 474 Valid values are 5, 6, 7. 475 GO386 476 For GOARCH=386, the floating point instruction set. 477 Valid values are 387, sse2. 478 479 Special-purpose environment variables: 480 481 GOROOT_FINAL 482 The root of the installed Go tree, when it is 483 installed in a location other than where it is built. 484 File names in stack traces are rewritten from GOROOT to 485 GOROOT_FINAL. 486 GO_EXTLINK_ENABLED 487 Whether the linker should use external linking mode 488 when using -linkmode=auto with code that uses cgo. 489 Set to 0 to disable external linking mode, 1 to enable it. 490 `, 491 } 492 493 var helpFileType = &Command{ 494 UsageLine: "filetype", 495 Short: "file types", 496 Long: ` 497 The go command examines the contents of a restricted set of files 498 in each directory. It identifies which files to examine based on 499 the extension of the file name. These extensions are: 500 501 .go 502 Go source files. 503 .c, .h 504 C source files. 505 If the package uses cgo or SWIG, these will be compiled with the 506 OS-native compiler (typically gcc); otherwise they will 507 trigger an error. 508 .cc, .cpp, .cxx, .hh, .hpp, .hxx 509 C++ source files. Only useful with cgo or SWIG, and always 510 compiled with the OS-native compiler. 511 .m 512 Objective-C source files. Only useful with cgo, and always 513 compiled with the OS-native compiler. 514 .s, .S 515 Assembler source files. 516 If the package uses cgo or SWIG, these will be assembled with the 517 OS-native assembler (typically gcc (sic)); otherwise they 518 will be assembled with the Go assembler. 519 .swig, .swigcxx 520 SWIG definition files. 521 .syso 522 System object files. 523 524 Files of each of these types except .syso may contain build 525 constraints, but the go command stops scanning for build constraints 526 at the first item in the file that is not a blank line or //-style 527 line comment. See the go/build package documentation for 528 more details. 529 530 Non-test Go source files can also include a //go:binary-only-package 531 comment, indicating that the package sources are included 532 for documentation only and must not be used to build the 533 package binary. This enables distribution of Go packages in 534 their compiled form alone. See the go/build package documentation 535 for more details. 536 `, 537 } 538 539 var helpBuildmode = &Command{ 540 UsageLine: "buildmode", 541 Short: "description of build modes", 542 Long: ` 543 The 'go build' and 'go install' commands take a -buildmode argument which 544 indicates which kind of object file is to be built. Currently supported values 545 are: 546 547 -buildmode=archive 548 Build the listed non-main packages into .a files. Packages named 549 main are ignored. 550 551 -buildmode=c-archive 552 Build the listed main package, plus all packages it imports, 553 into a C archive file. The only callable symbols will be those 554 functions exported using a cgo //export comment. Requires 555 exactly one main package to be listed. 556 557 -buildmode=c-shared 558 Build the listed main packages, plus all packages that they 559 import, into C shared libraries. The only callable symbols will 560 be those functions exported using a cgo //export comment. 561 Non-main packages are ignored. 562 563 -buildmode=default 564 Listed main packages are built into executables and listed 565 non-main packages are built into .a files (the default 566 behavior). 567 568 -buildmode=shared 569 Combine all the listed non-main packages into a single shared 570 library that will be used when building with the -linkshared 571 option. Packages named main are ignored. 572 573 -buildmode=exe 574 Build the listed main packages and everything they import into 575 executables. Packages not named main are ignored. 576 577 -buildmode=pie 578 Build the listed main packages and everything they import into 579 position independent executables (PIE). Packages not named 580 main are ignored. 581 `, 582 }