github.com/c0deoo1/golang1.5@v0.0.0-20220525150107-c87c805d4593/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 'code.google.com/p/project'. 81 82 As a special case, if the package list is a list of .go files from a 83 single directory, the command is applied to a single synthesized 84 package made up of exactly those files, ignoring any build constraints 85 in those files and ignoring any other files in the directory. 86 87 Directory and file names that begin with "." or "_" are ignored 88 by the go tool, as are directories named "testdata". 89 `, 90 } 91 92 var helpImportPath = &Command{ 93 UsageLine: "importpath", 94 Short: "import path syntax", 95 Long: ` 96 97 An import path (see 'go help packages') denotes a package 98 stored in the local file system. In general, an import path denotes 99 either a standard package (such as "unicode/utf8") or a package 100 found in one of the work spaces (see 'go help gopath'). 101 102 Relative import paths 103 104 An import path beginning with ./ or ../ is called a relative path. 105 The toolchain supports relative import paths as a shortcut in two ways. 106 107 First, a relative path can be used as a shorthand on the command line. 108 If you are working in the directory containing the code imported as 109 "unicode" and want to run the tests for "unicode/utf8", you can type 110 "go test ./utf8" instead of needing to specify the full path. 111 Similarly, in the reverse situation, "go test .." will test "unicode" from 112 the "unicode/utf8" directory. Relative patterns are also allowed, like 113 "go test ./..." to test all subdirectories. See 'go help packages' for details 114 on the pattern syntax. 115 116 Second, if you are compiling a Go program not in a work space, 117 you can use a relative path in an import statement in that program 118 to refer to nearby code also not in a work space. 119 This makes it easy to experiment with small multipackage programs 120 outside of the usual work spaces, but such programs cannot be 121 installed with "go install" (there is no work space in which to install them), 122 so they are rebuilt from scratch each time they are built. 123 To avoid ambiguity, Go programs cannot use relative import paths 124 within a work space. 125 126 Remote import paths 127 128 Certain import paths also 129 describe how to obtain the source code for the package using 130 a revision control system. 131 132 A few common code hosting sites have special syntax: 133 134 Bitbucket (Git, Mercurial) 135 136 import "bitbucket.org/user/project" 137 import "bitbucket.org/user/project/sub/directory" 138 139 GitHub (Git) 140 141 import "github.com/user/project" 142 import "github.com/user/project/sub/directory" 143 144 Google Code Project Hosting (Git, Mercurial, Subversion) 145 146 import "code.google.com/p/project" 147 import "code.google.com/p/project/sub/directory" 148 149 import "code.google.com/p/project.subrepository" 150 import "code.google.com/p/project.subrepository/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 the vendoring experiment is enabled (see 'go help gopath'), 265 then import path checking is disabled for code found within vendor trees. 266 This makes it possible to copy code into alternate locations in vendor trees 267 without needing to update import 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. 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.5 includes experimental support for using local copies 369 of external dependencies to satisfy imports of those dependencies, 370 often referred to as vendoring. Setting the environment variable 371 GO15VENDOREXPERIMENT=1 enables that experimental support. 372 373 When the vendor experiment is enabled, 374 code below a directory named "vendor" is importable only 375 by code in the directory tree rooted at the parent of "vendor", 376 and only using an import path that omits the prefix up to and 377 including the vendor element. 378 379 Here's the example from the previous section, 380 but with the "internal" directory renamed to "vendor" 381 and a new foo/vendor/crash/bang directory added: 382 383 /home/user/gocode/ 384 src/ 385 crash/ 386 bang/ (go code in package bang) 387 b.go 388 foo/ (go code in package foo) 389 f.go 390 bar/ (go code in package bar) 391 x.go 392 vendor/ 393 crash/ 394 bang/ (go code in package bang) 395 b.go 396 baz/ (go code in package baz) 397 z.go 398 quux/ (go code in package main) 399 y.go 400 401 The same visibility rules apply as for internal, but the code 402 in z.go is imported as "baz", not as "foo/vendor/baz". 403 404 Code in vendor directories deeper in the source tree shadows 405 code in higher directories. Within the subtree rooted at foo, an import 406 of "crash/bang" resolves to "foo/vendor/crash/bang", not the 407 top-level "crash/bang". 408 409 Code in vendor directories is not subject to import path 410 checking (see 'go help importpath'). 411 412 When the vendor experiment is enabled, 'go get' checks out 413 submodules when checking out or updating a git repository 414 (see 'go help get'). 415 416 The vendoring semantics are an experiment, and they may change 417 in future releases. Once settled, they will be on by default. 418 419 See https://golang.org/s/go15vendor for details. 420 `, 421 } 422 423 var helpEnvironment = &Command{ 424 UsageLine: "environment", 425 Short: "environment variables", 426 Long: ` 427 428 The go command, and the tools it invokes, examine a few different 429 environment variables. For many of these, you can see the default 430 value of on your system by running 'go env NAME', where NAME is the 431 name of the variable. 432 433 General-purpose environment variables: 434 435 GCCGO 436 The gccgo command to run for 'go build -compiler=gccgo'. 437 GOARCH 438 The architecture, or processor, for which to compile code. 439 Examples are amd64, 386, arm, ppc64. 440 GOBIN 441 The directory where 'go install' will install a command. 442 GOOS 443 The operating system for which to compile code. 444 Examples are linux, darwin, windows, netbsd. 445 GOPATH 446 See 'go help gopath'. 447 GORACE 448 Options for the race detector. 449 See https://golang.org/doc/articles/race_detector.html. 450 GOROOT 451 The root of the go tree. 452 453 Environment variables for use with cgo: 454 455 CC 456 The command to use to compile C code. 457 CGO_ENABLED 458 Whether the cgo command is supported. Either 0 or 1. 459 CGO_CFLAGS 460 Flags that cgo will pass to the compiler when compiling 461 C code. 462 CGO_CPPFLAGS 463 Flags that cgo will pass to the compiler when compiling 464 C or C++ code. 465 CGO_CXXFLAGS 466 Flags that cgo will pass to the compiler when compiling 467 C++ code. 468 CGO_LDFLAGS 469 Flags that cgo will pass to the compiler when linking. 470 CXX 471 The command to use to compile C++ code. 472 473 Architecture-specific environment variables: 474 475 GOARM 476 For GOARCH=arm, the ARM architecture for which to compile. 477 Valid values are 5, 6, 7. 478 GO386 479 For GOARCH=386, the floating point instruction set. 480 Valid values are 387, sse2. 481 482 Special-purpose environment variables: 483 484 GOROOT_FINAL 485 The root of the installed Go tree, when it is 486 installed in a location other than where it is built. 487 File names in stack traces are rewritten from GOROOT to 488 GOROOT_FINAL. 489 GO15VENDOREXPERIMENT 490 Set to 1 to enable the Go 1.5 vendoring experiment. 491 GO_EXTLINK_ENABLED 492 Whether the linker should use external linking mode 493 when using -linkmode=auto with code that uses cgo. 494 Set to 0 to disable external linking mode, 1 to enable it. 495 `, 496 } 497 498 var helpFileType = &Command{ 499 UsageLine: "filetype", 500 Short: "file types", 501 Long: ` 502 The go command examines the contents of a restricted set of files 503 in each directory. It identifies which files to examine based on 504 the extension of the file name. These extensions are: 505 506 .go 507 Go source files. 508 .c, .h 509 C source files. 510 If the package uses cgo or SWIG, these will be compiled with the 511 OS-native compiler (typically gcc); otherwise they will 512 trigger an error. 513 .cc, .cpp, .cxx, .hh, .hpp, .hxx 514 C++ source files. Only useful with cgo or SWIG, and always 515 compiled with the OS-native compiler. 516 .m 517 Objective-C source files. Only useful with cgo, and always 518 compiled with the OS-native compiler. 519 .s, .S 520 Assembler source files. 521 If the package uses cgo or SWIG, these will be assembled with the 522 OS-native assembler (typically gcc (sic)); otherwise they 523 will be assembled with the Go assembler. 524 .swig, .swigcxx 525 SWIG definition files. 526 .syso 527 System object files. 528 529 Files of each of these types except .syso may contain build 530 constraints, but the go command stops scanning for build constraints 531 at the first item in the file that is not a blank line or //-style 532 line comment. 533 `, 534 } 535 536 var helpBuildmode = &Command{ 537 UsageLine: "buildmode", 538 Short: "description of build modes", 539 Long: ` 540 The 'go build' and 'go install' commands take a -buildmode argument which 541 indicates which kind of object file is to be built. Currently supported values 542 are: 543 544 -buildmode=archive 545 Build the listed non-main packages into .a files. Packages named 546 main are ignored. 547 548 -buildmode=c-archive 549 Build the listed main package, plus all packages it imports, 550 into a C archive file. The only callable symbols will be those 551 functions exported using a cgo //export comment. Requires 552 exactly one main package to be listed. 553 554 -buildmode=c-shared 555 Build the listed main packages, plus all packages that they 556 import, into C shared libraries. The only callable symbols will 557 be those functions exported using a cgo //export comment. 558 Non-main packages are ignored. 559 560 -buildmode=default 561 Listed main packages are built into executables and listed 562 non-main packages are built into .a files (the default 563 behavior). 564 565 -buildmode=shared 566 Combine all the listed non-main packages into a single shared 567 library that will be used when building with the -linkshared 568 option. Packages named main are ignored. 569 570 -buildmode=exe 571 Build the listed main packages and everything they import into 572 executables. Packages not named main are ignored. 573 `, 574 }