summaryrefslogtreecommitdiffstats
path: root/man/go-path.7
diff options
context:
space:
mode:
Diffstat (limited to 'man/go-path.7')
-rw-r--r--man/go-path.7177
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).