1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
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).
|
