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