github.com/rsc/go@v0.0.0-20150416155037-e040fd465409/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 (godoc 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 three 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 git://, then https://, then http://. 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 vcs is one of "git", "hg", "svn", etc, 215 216 The repo-root is the root of the version control system 217 containing a scheme and not containing a .vcs qualifier. 218 219 For example, 220 221 import "example.org/pkg/foo" 222 223 will result in the following request(s): 224 225 https://example.org/pkg/foo?go-get=1 (preferred) 226 http://example.org/pkg/foo?go-get=1 (fallback) 227 228 If that page contains the meta tag 229 230 <meta name="go-import" content="example.org git https://code.org/r/p/exproj"> 231 232 the go tool will verify that https://example.org/?go-get=1 contains the 233 same meta tag and then git clone https://code.org/r/p/exproj into 234 GOPATH/src/example.org. 235 236 New downloaded packages are written to the first directory 237 listed in the GOPATH environment variable (see 'go help gopath'). 238 239 The go command attempts to download the version of the 240 package appropriate for the Go release being used. 241 Run 'go help get' for more. 242 243 Import path checking 244 245 When the custom import path feature described above redirects to a 246 known code hosting site, each of the resulting packages has two possible 247 import paths, using the custom domain or the known hosting site. 248 249 A package statement is said to have an "import comment" if it is immediately 250 followed (before the next newline) by a comment of one of these two forms: 251 252 package math // import "path" 253 package math /* import "path" */ 254 255 The go command will refuse to install a package with an import comment 256 unless it is being referred to by that import path. In this way, import comments 257 let package authors make sure the custom import path is used and not a 258 direct path to the underlying code hosting site. 259 260 See https://golang.org/s/go14customimport for details. 261 `, 262 } 263 264 var helpGopath = &Command{ 265 UsageLine: "gopath", 266 Short: "GOPATH environment variable", 267 Long: ` 268 The Go path is used to resolve import statements. 269 It is implemented by and documented in the go/build package. 270 271 The GOPATH environment variable lists places to look for Go code. 272 On Unix, the value is a colon-separated string. 273 On Windows, the value is a semicolon-separated string. 274 On Plan 9, the value is a list. 275 276 GOPATH must be set to get, build and install packages outside the 277 standard Go tree. 278 279 Each directory listed in GOPATH must have a prescribed structure: 280 281 The src/ directory holds source code. The path below 'src' 282 determines the import path or executable name. 283 284 The pkg/ directory holds installed package objects. 285 As in the Go tree, each target operating system and 286 architecture pair has its own subdirectory of pkg 287 (pkg/GOOS_GOARCH). 288 289 If DIR is a directory listed in the GOPATH, a package with 290 source in DIR/src/foo/bar can be imported as "foo/bar" and 291 has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a". 292 293 The bin/ directory holds compiled commands. 294 Each command is named for its source directory, but only 295 the final element, not the entire path. That is, the 296 command with source in DIR/src/foo/quux is installed into 297 DIR/bin/quux, not DIR/bin/foo/quux. The foo/ is stripped 298 so that you can add DIR/bin to your PATH to get at the 299 installed commands. If the GOBIN environment variable is 300 set, commands are installed to the directory it names instead 301 of DIR/bin. 302 303 Here's an example directory layout: 304 305 GOPATH=/home/user/gocode 306 307 /home/user/gocode/ 308 src/ 309 foo/ 310 bar/ (go code in package bar) 311 x.go 312 quux/ (go code in package main) 313 y.go 314 bin/ 315 quux (installed command) 316 pkg/ 317 linux_amd64/ 318 foo/ 319 bar.a (installed package object) 320 321 Go searches each directory listed in GOPATH to find source code, 322 but new packages are always downloaded into the first directory 323 in the list. 324 `, 325 } 326 327 var helpFileType = &Command{ 328 UsageLine: "filetype", 329 Short: "file types", 330 Long: ` 331 The go command examines the contents of a restricted set of files 332 in each directory. It identifies which files to examine based on 333 the extension of the file name. These extensions are: 334 335 .go 336 Go source files. 337 .c, .h 338 C source files. 339 If the package uses cgo, these will be compiled with the 340 OS-native compiler (typically gcc); otherwise they will be 341 compiled with the Go-specific support compiler, 342 5c, 6c, or 8c, etc. as appropriate. 343 .cc, .cpp, .cxx, .hh, .hpp, .hxx 344 C++ source files. Only useful with cgo or SWIG, and always 345 compiled with the OS-native compiler. 346 .m 347 Objective-C source files. Only useful with cgo, and always 348 compiled with the OS-native compiler. 349 .s, .S 350 Assembler source files. 351 If the package uses cgo, these will be assembled with the 352 OS-native assembler (typically gcc (sic)); otherwise they 353 will be assembled with the Go-specific support assembler, 354 5a, 6a, or 8a, etc., as appropriate. 355 .swig, .swigcxx 356 SWIG definition files. 357 .syso 358 System object files. 359 360 Files of each of these types except .syso may contain build 361 constraints, but the go command stops scanning for build constraints 362 at the first item in the file that is not a blank line or //-style 363 line comment. 364 `, 365 } 366 367 var helpBuildmode = &Command{ 368 UsageLine: "buildmode", 369 Short: "description of build modes", 370 Long: ` 371 The 'go build' and 'go install' commands take a -buildmode argument which 372 indicates which kind of object file is to be built. Currently supported values 373 are: 374 375 -buildmode=archive 376 Build the listed non-main packages into .a files. Packages named 377 main are ignored. 378 379 -buildmode=c-archive 380 Build the listed main package, plus all packages it imports, 381 into a C archive file. The only callable symbols will be those 382 functions marked as exported. Requires exactly one main package 383 to be listed. 384 385 -buildmode=c-shared 386 Build the listed main packages, plus all packages that they 387 import, into C shared libraries. The only callable symbols will 388 be those functions marked as exported. Non-main packages are 389 ignored. 390 391 -buildmode=default 392 Listed main packages are built into executables and listed 393 non-main packages are built into .a files (the default 394 behavior). 395 396 -buildmode=shared 397 Combine all the listed non-main packages into a single shared 398 library that will be used when building with the -linkshared 399 option. Packages named main are ignored. 400 401 -buildmode=exe 402 Build the listed main packages and everything they import into 403 executables. Packages not named main are ignored. 404 `, 405 }