mirror of
https://github.com/golang/go
synced 2024-09-05 07:54:46 +00:00
doc, cmd/go: adjust documentation for default GOPATH
Replaces CL 33356. Fixes #17262. Change-Id: Idfb2343e90771775e51a66c63760f458737a288c Reviewed-on: https://go-review.googlesource.com/33730 Run-TryBot: Russ Cox <rsc@golang.org> Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
This commit is contained in:
parent
5d1b53a944
commit
74628a8b9f
|
@ -97,13 +97,14 @@ a tool like the go command to look at an unfamiliar import path and
|
|||
deduce where to obtain the source code.</p>
|
||||
|
||||
<p>Second, the place to store sources in the local file system is derived
|
||||
in a known way from the import path. Specifically, the first choice
|
||||
is <code>$GOPATH/src/<import-path></code>. If <code>$GOPATH</code> is
|
||||
unset, the go command will fall back to storing source code alongside the
|
||||
standard Go packages, in <code>$GOROOT/src/<import-path></code>.
|
||||
in a known way from the import path, specifically
|
||||
<code>$GOPATH/src/<import-path></code>.
|
||||
If unset, <code>$GOPATH</code> defaults to a subdirectory
|
||||
named <code>go</code> in the user's home directory.
|
||||
If <code>$GOPATH</code> is set to a list of paths, the go command tries
|
||||
<code><dir>/src/<import-path></code> for each of the directories in
|
||||
that list.</p>
|
||||
that list.
|
||||
</p>
|
||||
|
||||
<p>Each of those trees contains, by convention, a top-level directory named
|
||||
"<code>bin</code>", for holding compiled executables, and a top-level directory
|
||||
|
@ -137,28 +138,13 @@ to the use of a specific tool chain.</p>
|
|||
|
||||
<h2>Getting started with the go command</h2>
|
||||
|
||||
<p>Finally, a quick tour of how to use the go command, to supplement
|
||||
the information in <a href="/doc/code.html">How to Write Go Code</a>,
|
||||
which you might want to read first. Assuming you want
|
||||
to keep your source code separate from the Go distribution source
|
||||
tree, the first step is to set <code>$GOPATH</code>, the one piece of global
|
||||
configuration that the go command needs. The <code>$GOPATH</code> can be a
|
||||
list of directories, but by far the most common usage should be to set it to a
|
||||
single directory. In particular, you do not need a separate entry in
|
||||
<code>$GOPATH</code> for each of your projects. One <code>$GOPATH</code> can
|
||||
support many projects.</p>
|
||||
<p>Finally, a quick tour of how to use the go command.
|
||||
As mentioned above, the default <code>$GOPATH</code> on Unix is <code>$HOME/go</code>.
|
||||
We'll store our programs there.
|
||||
To use a different location, you can set <code>$GOPATH</code>;
|
||||
see <a href="/doc/code.html">How to Write Go Code</a> for details.
|
||||
|
||||
<p>Here’s an example. Let’s say we decide to keep our Go code in the directory
|
||||
<code>$HOME/mygo</code>. We need to create that directory and set
|
||||
<code>$GOPATH</code> accordingly.</p>
|
||||
|
||||
<pre>
|
||||
$ mkdir $HOME/mygo
|
||||
$ export GOPATH=$HOME/mygo
|
||||
$
|
||||
</pre>
|
||||
|
||||
<p>Into this directory, we now add some source code. Suppose we want to use
|
||||
<p>We first add some source code. Suppose we want to use
|
||||
the indexing library from the codesearch project along with a left-leaning
|
||||
red-black tree. We can install both with the "<code>go get</code>"
|
||||
subcommand:</p>
|
||||
|
@ -169,8 +155,8 @@ $ go get github.com/petar/GoLLRB/llrb
|
|||
$
|
||||
</pre>
|
||||
|
||||
<p>Both of these projects are now downloaded and installed into our
|
||||
<code>$GOPATH</code> directory. The one tree now contains the two directories
|
||||
<p>Both of these projects are now downloaded and installed into <code>$HOME/go</code>,
|
||||
which contains the two directories
|
||||
<code>src/github.com/google/codesearch/index/</code> and
|
||||
<code>src/github.com/petar/GoLLRB/llrb/</code>, along with the compiled
|
||||
packages (in <code>pkg/</code>) for those libraries and their dependencies.</p>
|
||||
|
@ -184,6 +170,7 @@ the pattern "<code>./...</code>" means start in the current directory
|
|||
("<code>...</code>"):</p>
|
||||
|
||||
<pre>
|
||||
$ cd $HOME/go/src
|
||||
$ go list ./...
|
||||
github.com/google/codesearch/cmd/cgrep
|
||||
github.com/google/codesearch/cmd/cindex
|
||||
|
@ -215,7 +202,7 @@ $
|
|||
current directory:</p>
|
||||
|
||||
<pre>
|
||||
$ cd $GOPATH/src/github.com/google/codesearch/regexp
|
||||
$ cd github.com/google/codesearch/regexp
|
||||
$ go list
|
||||
github.com/google/codesearch/regexp
|
||||
$ go test -v
|
||||
|
@ -244,9 +231,6 @@ pick such a long name, but that ability would require additional configuration
|
|||
and complexity in the tool. Typing an extra directory name or two is a small
|
||||
price to pay for the increased simplicity and power.</p>
|
||||
|
||||
<p>As the example shows, it’s fine to work with packages from many different
|
||||
projects at once within a single <code>$GOPATH</code> root directory.</p>
|
||||
|
||||
<h2>Limitations</h2>
|
||||
|
||||
<p>As mentioned above, the go command is not a general-purpose build
|
||||
|
|
|
@ -120,30 +120,43 @@ We will discuss the distinction <a href="#PackageNames">later</a>.
|
|||
|
||||
<p>
|
||||
The <code>GOPATH</code> environment variable specifies the location of your
|
||||
workspace. It is likely the only environment variable you'll need to set
|
||||
when developing Go code.
|
||||
workspace. It defaults to a directory named <code>go</code> inside your home directory,
|
||||
so <code>$HOME/go</code> on Unix,
|
||||
<code>$home/go</code> on Plan 9,
|
||||
and <code>%USERPROFILE%\go</code> (usually <code>C:\Users\YourName\go</code>) on Windows.
|
||||
If you would like to work in a different location, you will need to set
|
||||
<code>GOPATH</code> to the path to that directory.
|
||||
(Another common setup is to set <code>GOPATH=$HOME</code>.)
|
||||
Note that <code>GOPATH</code> must <b>not</b> be the
|
||||
same path as your Go installation.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
To get started, create a workspace directory and set <code>GOPATH</code>
|
||||
accordingly. Your workspace can be located wherever you like, but we'll use
|
||||
<code>$HOME/work</code> in this document. Note that this must <b>not</b> be the
|
||||
same path as your Go installation.
|
||||
(Another common setup is to set <code>GOPATH=$HOME</code>.)
|
||||
The command <code>go</code> <code>env</code> <code>GOPATH</code>
|
||||
prints the effective current <code>GOPATH</code>;
|
||||
it prints the default location if the environment variable is unset.
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
$ <b>mkdir $HOME/work</b>
|
||||
$ <b>export GOPATH=$HOME/work</b>
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
For convenience, add the workspace's <code>bin</code> subdirectory
|
||||
to your <code>PATH</code>:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
$ <b>export PATH=$PATH:$GOPATH/bin</b>
|
||||
$ <b>export PATH=$PATH:$(go env GOPATH)/bin</b>
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
The scripts in the rest of this document use <code>$GOPATH</code>
|
||||
instead of <code>$(go env GOPATH)</code> for brevity.
|
||||
To make the scripts run as written
|
||||
if you have not set GOPATH,
|
||||
you can substitute $HOME/go in those commands
|
||||
or else run:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
$ <b>export GOPATH=$(go env GOPATH)</b>
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
|
|
|
@ -1094,7 +1094,7 @@ it's easy to work around this. For GitHub, try one of these solutions:
|
|||
<ul>
|
||||
<li>Manually clone the repository in the expected package directory:
|
||||
<pre>
|
||||
$ cd $GOPATH/src/github.com/username
|
||||
$ cd src/github.com/username
|
||||
$ git clone git@github.com:username/package.git
|
||||
</pre>
|
||||
</li>
|
||||
|
|
|
@ -430,7 +430,7 @@ to override the defaults.
|
|||
<ul>
|
||||
<li><code>$GOROOT</code>
|
||||
<p>
|
||||
The root of the Go tree, often <code>$HOME/go</code>.
|
||||
The root of the Go tree, often <code>$HOME/go1.X</code>.
|
||||
Its value is built into the tree when it is compiled, and
|
||||
defaults to the parent of the directory where <code>all.bash</code> was run.
|
||||
There is no need to set this unless you want to switch between multiple
|
||||
|
@ -632,7 +632,7 @@ something like this:
|
|||
</p>
|
||||
|
||||
<pre>
|
||||
export GOROOT=$HOME/go
|
||||
export GOROOT=$HOME/go1.X
|
||||
export GOARCH=amd64
|
||||
export GOOS=linux
|
||||
</pre>
|
||||
|
|
|
@ -117,12 +117,12 @@ to point to the directory in which it was installed.
|
|||
</p>
|
||||
|
||||
<p>
|
||||
For example, if you installed Go to your home directory you should add the
|
||||
following commands to <code>$HOME/.profile</code>:
|
||||
For example, if you installed Go to your home directory you should add
|
||||
commands like the following to <code>$HOME/.profile</code>:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
export GOROOT=$HOME/go
|
||||
export GOROOT=$HOME/go1.X
|
||||
export PATH=$PATH:$GOROOT/bin
|
||||
</pre>
|
||||
|
||||
|
@ -219,37 +219,16 @@ and building a simple program, as follows.
|
|||
</p>
|
||||
|
||||
<p>
|
||||
Create a directory to contain your <a href="code.html#Workspaces">workspace</a>,
|
||||
<code class="testUnix">$HOME/work</code>
|
||||
<code class="testWindows" style="display: none">C:\work</code>
|
||||
for example, and set the <code>GOPATH</code> environment
|
||||
variable to point to that location.
|
||||
</p>
|
||||
|
||||
<pre class="testUnix">
|
||||
$ <b>export GOPATH=$HOME/work</b>
|
||||
</pre>
|
||||
|
||||
<pre class="testWindows" style="display: none">
|
||||
C:\> <b>set GOPATH=C:\work</b>
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
<span class="testUnix">
|
||||
You should put the above command in your shell startup script
|
||||
(<code>$HOME/.profile</code> for example).
|
||||
</span>
|
||||
<span class="testWindows">
|
||||
On Windows, follow the <a href="#windows_env">instructions above</a> to set the
|
||||
<code>GOPATH</code> environment variable on your system.
|
||||
</span>
|
||||
Create your <a href="code.html#Workspaces">workspace</a> directory,
|
||||
<code class="testUnix">$HOME/go</code><code class="testWindows">%USERPROFILE%\go</code>.
|
||||
(If you'd like to use a different directory,
|
||||
you will need to set the <code>GOPATH</code> environment variable;
|
||||
see <a href="code.html#Workspaces">How to Write Go Code</a> for details.)
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Next, make the directories <code>src/github.com/user/hello</code> inside your
|
||||
workspace (if you use GitHub, substitute your user name for <code>user</code>),
|
||||
and inside the <code>hello</code> directory create a file named <code>hello.go</code>
|
||||
with the following contents:
|
||||
Next, make the directory <code>src/hello</code> inside your workspace,
|
||||
and in that directory create a file named <code>hello.go</code> that looks like:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
|
@ -263,30 +242,33 @@ func main() {
|
|||
</pre>
|
||||
|
||||
<p>
|
||||
Then compile it with the <code>go</code> tool:
|
||||
Then build it with the <code>go</code> tool:
|
||||
</p>
|
||||
|
||||
<pre class="testUnix">
|
||||
$ <b>go install github.com/user/hello</b>
|
||||
$ <b>cd $HOME/go/src/hello
|
||||
$ <b>go build</b>
|
||||
</pre>
|
||||
|
||||
<pre class="testWindows" style="display: none">
|
||||
C:\> <b>go install github.com/user/hello</b>
|
||||
C:\> <b>cd %USERPROFILE%\go\src\hello<b>
|
||||
C:\Users\Gopher\go\src\hello> <b>go build</b>
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
The command above will put an executable command named <code>hello</code>
|
||||
(or <code>hello.exe</code>) inside the <code>bin</code> directory of your workspace.
|
||||
Execute the command to see the greeting:
|
||||
The command above will build an executable named
|
||||
<code class="testUnix">hello</code><code class="testWindows">hello.exe</code>
|
||||
in the directory alongside your source code.
|
||||
Execute it to see the greeting:
|
||||
</p>
|
||||
|
||||
<pre class="testUnix">
|
||||
$ <b>$GOPATH/bin/hello</b>
|
||||
$ <b>./hello</b>
|
||||
hello, world
|
||||
</pre>
|
||||
|
||||
<pre class="testWindows" style="display: none">
|
||||
C:\> <b>%GOPATH%\bin\hello</b>
|
||||
C:\Users\Gopher\go\src\hello> <b>hello</b>
|
||||
hello, world
|
||||
</pre>
|
||||
|
||||
|
@ -294,6 +276,12 @@ hello, world
|
|||
If you see the "hello, world" message then your Go installation is working.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
You can run <code>go</code> <code>install</code> to install the binary into
|
||||
your workspace's <code>bin</code> directory
|
||||
or <code>go</code> <code>clean</code> to remove it.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Before rushing off to write Go code please read the
|
||||
<a href="/doc/code.html">How to Write Go Code</a> document,
|
||||
|
|
|
@ -929,8 +929,10 @@
|
|||
// On Windows, the value is a semicolon-separated string.
|
||||
// On Plan 9, the value is a list.
|
||||
//
|
||||
// GOPATH must be set to get, build and install packages outside the
|
||||
// standard Go tree.
|
||||
// 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).
|
||||
// Run "go env GOPATH" to see the current GOPATH.
|
||||
//
|
||||
// Each directory listed in GOPATH must have a prescribed structure:
|
||||
//
|
||||
|
@ -958,9 +960,9 @@
|
|||
//
|
||||
// Here's an example directory layout:
|
||||
//
|
||||
// GOPATH=/home/user/gocode
|
||||
// GOPATH=/home/user/go
|
||||
//
|
||||
// /home/user/gocode/
|
||||
// /home/user/go/
|
||||
// src/
|
||||
// foo/
|
||||
// bar/ (go code in package bar)
|
||||
|
@ -986,7 +988,7 @@
|
|||
// by code in the directory tree rooted at the parent of "internal".
|
||||
// Here's an extended version of the directory layout above:
|
||||
//
|
||||
// /home/user/gocode/
|
||||
// /home/user/go/
|
||||
// src/
|
||||
// crash/
|
||||
// bang/ (go code in package bang)
|
||||
|
@ -1024,7 +1026,7 @@
|
|||
// but with the "internal" directory renamed to "vendor"
|
||||
// and a new foo/vendor/crash/bang directory added:
|
||||
//
|
||||
// /home/user/gocode/
|
||||
// /home/user/go/
|
||||
// src/
|
||||
// crash/
|
||||
// bang/ (go code in package bang)
|
||||
|
|
|
@ -289,8 +289,10 @@ 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.
|
||||
|
||||
GOPATH must be set to get, build and install packages outside the
|
||||
standard Go tree.
|
||||
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).
|
||||
Run "go env GOPATH" to see the current GOPATH.
|
||||
|
||||
Each directory listed in GOPATH must have a prescribed structure:
|
||||
|
||||
|
@ -318,9 +320,9 @@ of DIR/bin. GOBIN must be an absolute path.
|
|||
|
||||
Here's an example directory layout:
|
||||
|
||||
GOPATH=/home/user/gocode
|
||||
GOPATH=/home/user/go
|
||||
|
||||
/home/user/gocode/
|
||||
/home/user/go/
|
||||
src/
|
||||
foo/
|
||||
bar/ (go code in package bar)
|
||||
|
@ -346,7 +348,7 @@ 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:
|
||||
|
||||
/home/user/gocode/
|
||||
/home/user/go/
|
||||
src/
|
||||
crash/
|
||||
bang/ (go code in package bang)
|
||||
|
@ -384,7 +386,7 @@ 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:
|
||||
|
||||
/home/user/gocode/
|
||||
/home/user/go/
|
||||
src/
|
||||
crash/
|
||||
bang/ (go code in package bang)
|
||||
|
|
Loading…
Reference in a new issue