diff options
Diffstat (limited to 'man/go-path.7')
| -rw-r--r-- | man/go-path.7 | 177 |
1 files changed, 177 insertions, 0 deletions
diff --git a/man/go-path.7 b/man/go-path.7 new file mode 100644 index 0000000..9b8be48 --- /dev/null +++ b/man/go-path.7 @@ -0,0 +1,177 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-PATH 7 "2021-09-06" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH DESCRIPTION +The Go path is used to resolve import statements. +It is implemented by and documented in the go/build package. + +The GOPATH environment variable lists places to look for Go code. +On Unix, the value is a colon-separated string. +On Windows, the value is a semicolon-separated string. +On Plan 9, the value is a list. + +If the environment variable is unset, GOPATH defaults +to a subdirectory named "go" in the user's home directory +($HOME/go on Unix, %USERPROFILE%\go on Windows), +unless that directory holds a Go distribution. +Run "go env GOPATH" to see the current GOPATH. + +See https://golang.org/wiki/SettingGOPATH to set a custom GOPATH. + +Each directory listed in GOPATH must have a prescribed structure: + +The src directory holds source code. The path below src +determines the import path or executable name. + +The pkg directory holds installed package objects. +As in the Go tree, each target operating system and +architecture pair has its own subdirectory of pkg +(pkg/GOOS_GOARCH). + +If DIR is a directory listed in the GOPATH, a package with +source in DIR/src/foo/bar can be imported as "foo/bar" and +has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a". + +The bin directory holds compiled commands. +Each command is named for its source directory, but only +the final element, not the entire path. That is, the +command with source in DIR/src/foo/quux is installed into +DIR/bin/quux, not DIR/bin/foo/quux. The "foo/" prefix is stripped +so that you can add DIR/bin to your PATH to get at the +installed commands. If the GOBIN environment variable is +set, commands are installed to the directory it names instead +of DIR/bin. GOBIN must be an absolute path. + +Here's an example directory layout: + +.Vb 4 +\& GOPATH=/home/user/gocode +\& +\& /home/user/gocode/ +\& src/ +\& foo/ +\& bar/ (go code in package bar) +\& x.go +\& quux/ (go code in package main) +\& y.go +\& bin/ +\& quux (installed command) +\& pkg/ +\& linux_amd64/ +\& foo/ +\& bar.a (installed package object) +.Ve + +Go searches each directory listed in GOPATH to find source code, +but new packages are always downloaded into the first directory +in the list. + +See https://golang.org/doc/code.html for an example. +. +.SS GOPATH and Modules +. +When using modules, GOPATH is no longer used for resolving imports. +However, it is still used to store downloaded source code (in GOPATH/pkg/mod) +and compiled commands (in GOPATH/bin). +. +.SS Internal Directories +. +Code in or below a directory named "internal" is importable only +by code in the directory tree rooted at the parent of "internal". +Here's an extended version of the directory layout above: + +.Vb 4 +\& /home/user/go/ +\& src/ +\& crash/ +\& bang/ (go code in package bang) +\& b.go +\& foo/ (go code in package foo) +\& f.go +\& bar/ (go code in package bar) +\& x.go +\& internal/ +\& baz/ (go code in package baz) +\& z.go +\& quux/ (go code in package main) +\& y.go +.Ve + +The code in z.go is imported as "foo/internal/baz", but that +import statement can only appear in source files in the subtree +rooted at foo. The source files foo/f.go, foo/bar/x.go, and +foo/quux/y.go can all import "foo/internal/baz", but the source file +crash/bang/b.go cannot. + +See https://golang.org/s/go14internal for details. +. +.SS Vendor Directories + +Go 1.6 includes support for using local copies of external dependencies +to satisfy imports of those dependencies, often referred to as vendoring. + +Code below a directory named "vendor" is importable only +by code in the directory tree rooted at the parent of "vendor", +and only using an import path that omits the prefix up to and +including the vendor element. + +Here's the example from the previous section, +but with the "internal" directory renamed to "vendor" +and a new foo/vendor/crash/bang directory added: + +.Vb 4 +\& /home/user/go/ +\& src/ +\& crash/ +\& bang/ (go code in package bang) +\& b.go +\& foo/ (go code in package foo) +\& f.go +\& bar/ (go code in package bar) +\& x.go +\& vendor/ +\& crash/ +\& bang/ (go code in package bang) +\& b.go +\& baz/ (go code in package baz) +\& z.go +\& quux/ (go code in package main) +\& y.go +.Ve + +The same visibility rules apply as for internal, but the code +in z.go is imported as "baz", not as "foo/vendor/baz". + +Code in vendor directories deeper in the source tree shadows +code in higher directories. Within the subtree rooted at foo, an import +of "crash/bang" resolves to "foo/vendor/crash/bang", not the +top-level "crash/bang". + +Code in vendor directories is not subject to import path +checking (see 'go help importpath'). + +When 'go get' checks out or updates a git repository, it now also +updates submodules. + +Vendor directories do not affect the placement of new repositories +being checked out for the first time by 'go get': those are always +placed in the main GOPATH, never in a vendor subtree. + +See https://golang.org/s/go15vendor for details. +.SH AUTHOR +This manual page was written by Michael Stapelberg <stapelberg@debian.org> +and is maintained by the +Debian Go Compiler Team <team+go-compiler@tracker.debian.org> +based on the output of 'go help gopath' +for the Debian project (and may be used by others). |