Skip to content

Commit

Permalink
doc, cmd/go: adjust documentation for default GOPATH
Browse files Browse the repository at this point in the history
Replaces CL 33356.

Fixes #17262.

Change-Id: Idfb2343e90771775e51a66c63760f458737a288c
Reviewed-on: https://go-review.googlesource.com/33730
Run-TryBot: Russ Cox <[email protected]>
Reviewed-by: Brad Fitzpatrick <[email protected]>
  • Loading branch information
rsc committed Nov 30, 2016
1 parent 5d1b53a commit 74628a8
Show file tree
Hide file tree
Showing 7 changed files with 87 additions and 98 deletions.
48 changes: 16 additions & 32 deletions doc/articles/go_command.html
Original file line number Diff line number Diff line change
Expand Up @@ -97,13 +97,14 @@ <h2>Go's conventions</h2>
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/&lt;import-path&gt;</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/&lt;import-path&gt;</code>.
in a known way from the import path, specifically
<code>$GOPATH/src/&lt;import-path&gt;</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>&lt;dir&gt;/src/&lt;import-path&gt;</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
Expand Down Expand Up @@ -137,28 +138,13 @@ <h2>Go's conventions</h2>

<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>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>
<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.

<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>
Expand All @@ -169,8 +155,8 @@ <h2>Getting started with the go command</h2>
$
</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>
Expand All @@ -184,6 +170,7 @@ <h2>Getting started with the go command</h2>
("<code>...</code>"):</p>

<pre>
$ cd $HOME/go/src
$ go list ./...
github.com/google/codesearch/cmd/cgrep
github.com/google/codesearch/cmd/cindex
Expand Down Expand Up @@ -215,7 +202,7 @@ <h2>Getting started with the go command</h2>
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
Expand Down Expand Up @@ -244,9 +231,6 @@ <h2>Getting started with the go command</h2>
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
Expand Down
37 changes: 25 additions & 12 deletions doc/code.html
Original file line number Diff line number Diff line change
Expand Up @@ -120,30 +120,43 @@ <h3 id="GOPATH">The <code>GOPATH</code> environment variable</h3>

<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>

<p>
For convenience, add the workspace's <code>bin</code> subdirectory
to your <code>PATH</code>:
</p>

<pre>
$ <b>mkdir $HOME/work</b>
$ <b>export GOPATH=$HOME/work</b>
$ <b>export PATH=$PATH:$(go env GOPATH)/bin</b>
</pre>

<p>
For convenience, add the workspace's <code>bin</code> subdirectory
to your <code>PATH</code>:
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 PATH=$PATH:$GOPATH/bin</b>
$ <b>export GOPATH=$(go env GOPATH)</b>
</pre>

<p>
Expand Down
2 changes: 1 addition & 1 deletion doc/go_faq.html
Original file line number Diff line number Diff line change
Expand Up @@ -1094,7 +1094,7 @@ <h3 id="git_https">
<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 [email protected]:username/package.git
</pre>
</li>
Expand Down
4 changes: 2 additions & 2 deletions doc/install-source.html
Original file line number Diff line number Diff line change
Expand Up @@ -430,7 +430,7 @@ <h2 id="environment">Optional environment variables</h2>
<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
Expand Down Expand Up @@ -632,7 +632,7 @@ <h2 id="environment">Optional environment variables</h2>
</p>

<pre>
export GOROOT=$HOME/go
export GOROOT=$HOME/go1.X
export GOARCH=amd64
export GOOS=linux
</pre>
Expand Down
66 changes: 27 additions & 39 deletions doc/install.html
Original file line number Diff line number Diff line change
Expand Up @@ -117,12 +117,12 @@ <h4 id="tarball_non_standard">Installing to a custom location</h4>
</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>

Expand Down Expand Up @@ -219,37 +219,16 @@ <h2 id="testing">Test your installation</h2>
</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.
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>

<pre class="testUnix">
$ <b>export GOPATH=$HOME/work</b>
</pre>

<pre class="testWindows" style="display: none">
C:\&gt; <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>
</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>
Expand All @@ -263,37 +242,46 @@ <h2 id="testing">Test your installation</h2>
</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:\&gt; <b>go install github.com/user/hello</b>
C:\&gt; <b>cd %USERPROFILE%\go\src\hello<b>
C:\Users\Gopher\go\src\hello&gt; <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:\&gt; <b>%GOPATH%\bin\hello</b>
C:\Users\Gopher\go\src\hello&gt; <b>hello</b>
hello, world
</pre>

<p>
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,
Expand Down
14 changes: 8 additions & 6 deletions src/cmd/go/alldocs.go
Original file line number Diff line number Diff line change
Expand Up @@ -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:
//
Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
14 changes: 8 additions & 6 deletions src/cmd/go/help.go
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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)
Expand Down

0 comments on commit 74628a8

Please sign in to comment.