From 74628a8b9f102bddd5078ee426efe0fd57033115 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Wed, 30 Nov 2016 14:56:58 -0500 Subject: [PATCH] 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 Reviewed-by: Brad Fitzpatrick --- doc/articles/go_command.html | 48 +++++++++----------------- doc/code.html | 37 +++++++++++++------- doc/go_faq.html | 2 +- doc/install-source.html | 4 +-- doc/install.html | 66 +++++++++++++++--------------------- src/cmd/go/alldocs.go | 14 ++++---- src/cmd/go/help.go | 14 ++++---- 7 files changed, 87 insertions(+), 98 deletions(-) diff --git a/doc/articles/go_command.html b/doc/articles/go_command.html index 002c034367..0fd83cb53a 100644 --- a/doc/articles/go_command.html +++ b/doc/articles/go_command.html @@ -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.

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 $GOPATH/src/<import-path>. If $GOPATH is -unset, the go command will fall back to storing source code alongside the -standard Go packages, in $GOROOT/src/<import-path>. +in a known way from the import path, specifically +$GOPATH/src/<import-path>. +If unset, $GOPATH defaults to a subdirectory +named go in the user's home directory. If $GOPATH is set to a list of paths, the go command tries <dir>/src/<import-path> for each of the directories in -that list.

+that list. +

Each of those trees contains, by convention, a top-level directory named "bin", for holding compiled executables, and a top-level directory @@ -137,28 +138,13 @@ to the use of a specific tool chain.

Getting started with the go command

-

Finally, a quick tour of how to use the go command, to supplement -the information in How to Write Go Code, -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 $GOPATH, the one piece of global -configuration that the go command needs. The $GOPATH 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 -$GOPATH for each of your projects. One $GOPATH can -support many projects.

- -

Here’s an example. Let’s say we decide to keep our Go code in the directory -$HOME/mygo. We need to create that directory and set -$GOPATH accordingly.

+

Finally, a quick tour of how to use the go command. +As mentioned above, the default $GOPATH on Unix is $HOME/go. +We'll store our programs there. +To use a different location, you can set $GOPATH; +see How to Write Go Code for details. -

-$ mkdir $HOME/mygo
-$ export GOPATH=$HOME/mygo
-$
-
- -

Into this directory, we now add some source code. Suppose we want to use +

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 "go get" subcommand:

@@ -169,8 +155,8 @@ $ go get github.com/petar/GoLLRB/llrb $ -

Both of these projects are now downloaded and installed into our -$GOPATH directory. The one tree now contains the two directories +

Both of these projects are now downloaded and installed into $HOME/go, +which contains the two directories src/github.com/google/codesearch/index/ and src/github.com/petar/GoLLRB/llrb/, along with the compiled packages (in pkg/) for those libraries and their dependencies.

@@ -184,6 +170,7 @@ the pattern "./..." means start in the current directory ("..."):

+$ cd $HOME/go/src
 $ go list ./...
 github.com/google/codesearch/cmd/cgrep
 github.com/google/codesearch/cmd/cindex
@@ -215,7 +202,7 @@ $
 current directory:

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

 
-
As the example shows, it’s fine to work with packages from many different
-projects at once within a single $GOPATH root directory.

-
 
Limitations

 
 
As mentioned above, the go command is not a general-purpose build
diff --git a/doc/code.html b/doc/code.html
index b64bc1a142..9978b523b4 100644
--- a/doc/code.html
+++ b/doc/code.html
@@ -120,30 +120,43 @@ We will discuss the distinction later.
 
 

 The GOPATH 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 go inside your home directory,
+so $HOME/go on Unix,
+$home/go on Plan 9,
+and %USERPROFILE%\go (usually C:\Users\YourName\go) on Windows.
+If you would like to work in a different location, you will need to set
+GOPATH to the path to that directory.
+(Another common setup is to set GOPATH=$HOME.)
+Note that GOPATH must not be the
+same path as your Go installation.
 

 
 

-To get started, create a workspace directory and set GOPATH
-accordingly. Your workspace can be located wherever you like, but we'll use
-$HOME/work in this document. Note that this must not be the
-same path as your Go installation.
-(Another common setup is to set GOPATH=$HOME.)
+The command go env GOPATH
+prints the effective current GOPATH;
+it prints the default location if the environment variable is unset.
+

+
+

+For convenience, add the workspace's bin subdirectory
+to your PATH:
 

 
 
-$ mkdir $HOME/work
-$ export GOPATH=$HOME/work
+$ export PATH=$PATH:$(go env GOPATH)/bin
 

 
 

-For convenience, add the workspace's bin subdirectory
-to your PATH:
+The scripts in the rest of this document use $GOPATH
+instead of $(go env GOPATH) 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:
 

 
 
-$ export PATH=$PATH:$GOPATH/bin
+$ export GOPATH=$(go env GOPATH)
 

 
 

diff --git a/doc/go_faq.html b/doc/go_faq.html
index 884d98ba6e..3006b3d3d4 100644
--- a/doc/go_faq.html
+++ b/doc/go_faq.html
@@ -1094,7 +1094,7 @@ it's easy to work around this. For GitHub, try one of these solutions:
 
    
 
  • Manually clone the repository in the expected package directory:
 
    -$ cd $GOPATH/src/github.com/username
+$ cd src/github.com/username
 $ git clone git@github.com:username/package.git
 
    
 
    • 
diff --git a/doc/install-source.html b/doc/install-source.html
index 22cc1d5dec..4a25e37d22 100644
--- a/doc/install-source.html
+++ b/doc/install-source.html
@@ -430,7 +430,7 @@ to override the defaults.
 
      
 
    • $GOROOT
 
      
-The root of the Go tree, often $HOME/go.
+The root of the Go tree, often $HOME/go1.X.
 Its value is built into the tree when it is compiled, and
 defaults to the parent of the directory where all.bash was run.
 There is no need to set this unless you want to switch between multiple
@@ -632,7 +632,7 @@ something like this:
 
      
 
 
      -export GOROOT=$HOME/go
+export GOROOT=$HOME/go1.X
 export GOARCH=amd64
 export GOOS=linux
 
      
diff --git a/doc/install.html b/doc/install.html
index 1305c970e3..ebe66c0205 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -117,12 +117,12 @@ to point to the directory in which it was installed.
 
      
 
 
      
-For example, if you installed Go to your home directory you should add the
-following commands to $HOME/.profile:
+For example, if you installed Go to your home directory you should add
+commands like the following to $HOME/.profile:
 
      
 
 
      -export GOROOT=$HOME/go
+export GOROOT=$HOME/go1.X
 export PATH=$PATH:$GOROOT/bin
 
      
 
@@ -219,37 +219,16 @@ and building a simple program, as follows.
 
      
 
 
      
-Create a directory to contain your workspace,
-$HOME/work
-
-for example, and set the GOPATH environment
-variable to point to that location.
+Create your workspace directory,
+$HOME/go%USERPROFILE%\go.
+(If you'd like to use a different directory,
+you will need to set the GOPATH environment variable;
+see How to Write Go Code for details.)
 
      
 
-
      -$ export GOPATH=$HOME/work
-
      
-
-
-
 
      
-
-You should put the above command in your shell startup script
-($HOME/.profile for example).
-
-
-On Windows, follow the instructions above to set the
-GOPATH environment variable on your system.
-
-
      
-
-
      
-Next, make the directories src/github.com/user/hello inside your
-workspace (if you use GitHub, substitute your user name for user),
-and inside the hello directory create a file named hello.go
-with the following contents:
+Next, make the directory src/hello inside your workspace,
+and in that directory create a file named hello.go that looks like:
 
      
 
 
      @@ -263,30 +242,33 @@ func main() {
 
      
 
 
      
-Then compile it with the go tool:
+Then build it with the go tool:
 
      
 
 
      -$ go install github.com/user/hello
+$ cd $HOME/go/src/hello
+$ go build
 
      
 
 
 
 
      
-The command above will put an executable command named hello 
-(or hello.exe) inside the bin directory of your workspace.
-Execute the command to see the greeting:
+The command above will build an executable named
+hellohello.exe
+in the directory alongside your source code.
+Execute it to see the greeting:
 
      
 
 
      -$ $GOPATH/bin/hello
+$ ./hello
 hello, world
 
      
 
 
 
@@ -294,6 +276,12 @@ hello, world
 If you see the "hello, world" message then your Go installation is working.
 
      
 
+
      
+You can run go install to install the binary into
+your workspace's bin directory
+or go clean to remove it.
+
      
+
 
      
 Before rushing off to write Go code please read the
 How to Write Go Code document,
diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 3c909fed26..0272e185ab 100644
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -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)
diff --git a/src/cmd/go/help.go b/src/cmd/go/help.go
index f90cfcc7e9..183b27e7e6 100644
--- a/src/cmd/go/help.go
+++ b/src/cmd/go/help.go
@@ -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)
-- 
2.52.0