content/static/doc: rewrite code.html for go modules
Fixes golang/go#28215
Change-Id: I4be63c2408bb117c6ee2d3a02327f6d277d35828
Reviewed-on: https://go-review.googlesource.com/c/website/+/199417
Run-TryBot: Jean de Klerk <deklerk@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Jay Conrod <jayconrod@google.com>
diff --git a/content/static/doc/code.html b/content/static/doc/code.html
index a2adc82..b86f300 100644
--- a/content/static/doc/code.html
+++ b/content/static/doc/code.html
@@ -1,226 +1,96 @@
<!--{
- "Title": "How to Write Go Code"
+ "Title": "How to Write Go Code",
+ "Template": true
}-->
<h2 id="Introduction">Introduction</h2>
<p>
-This document demonstrates the development of a simple Go package and
-introduces the <a href="/cmd/go/">go tool</a>, the standard way to fetch,
-build, and install Go packages and commands.
+This document demonstrates the development of a simple Go package inside a
+module and introduces the <a href="/cmd/go/">go tool</a>, the standard way to
+fetch, build, and install Go modules, packages, and commands.
</p>
<p>
-The <code>go</code> tool requires you to organize your code in a specific
-way. Please read this document carefully.
-It explains the simplest way to get up and running with your Go installation.
+Note: This document assumes that you are using Go 1.13 or later and the
+<code>GO111MODULE</code> environment variable is not set. If you are looking for
+the older, pre-modules version of this document, it is archived
+<a href="gopath_code.html">here</a>.
</p>
-<p>
-A similar explanation is available as a
-<a href="//www.youtube.com/watch?v=XCsL89YtqCs">screencast</a>.
-</p>
-
-
<h2 id="Organization">Code organization</h2>
-<h3 id="Overview">Overview</h3>
-
-<ul>
- <li>Go programmers typically keep all their Go code in a single <i>workspace</i>.</li>
- <li>A workspace contains many version control <i>repositories</i>
- (managed by Git, for example).</li>
- <li>Each repository contains one or more <i>packages</i>.</li>
- <li>Each package consists of one or more Go source files in a single directory.</li>
- <li>The path to a package's directory determines its <i>import path</i>.</li>
-</ul>
-
<p>
-Note that this differs from other programming environments in which every
-project has a separate workspace and workspaces are closely tied to version
-control repositories.
-</p>
-
-<h3 id="Workspaces">Workspaces</h3>
-
-<p>
-A workspace is a directory hierarchy with two directories at its root:
-</p>
-
-<ul>
-<li><code>src</code> contains Go source files, and
-<li><code>bin</code> contains executable commands.
-</ul>
-
-<p>
-The <code>go</code> tool builds and installs binaries to the <code>bin</code> directory.
+Go programs are organized into packages. A <dfn>package</dfn> is a collection
+of source files in the same directory that are compiled together. Functions,
+types, variables, and constants defined in one source file are visible to all
+other source files within the same package.
</p>
<p>
-The <code>src</code> subdirectory typically contains multiple version control
-repositories (such as for Git or Mercurial) that track the development of one
-or more source packages.
-</p>
-
-<p>
-To give you an idea of how a workspace looks in practice, here's an example:
-</p>
-
-<pre>
-bin/
- hello # command executable
- outyet # command executable
-src/
- <a href="https://github.com/golang/example/">github.com/golang/example/</a>
- .git/ # Git repository metadata
- hello/
- hello.go # command source
- outyet/
- main.go # command source
- main_test.go # test source
- stringutil/
- reverse.go # package source
- reverse_test.go # test source
- <a href="https://golang.org/x/image/">golang.org/x/image/</a>
- .git/ # Git repository metadata
- bmp/
- reader.go # package source
- writer.go # package source
- ... (many more repositories and packages omitted) ...
-</pre>
-
-<p>
-The tree above shows a workspace containing two repositories
-(<code>example</code> and <code>image</code>).
-The <code>example</code> repository contains two commands (<code>hello</code>
-and <code>outyet</code>) and one library (<code>stringutil</code>).
-The <code>image</code> repository contains the <code>bmp</code> package
-and <a href="https://godoc.org/golang.org/x/image">several others</a>.
-</p>
-
-<p>
-A typical workspace contains many source repositories containing many
-packages and commands. Most Go programmers keep <i>all</i> their Go source code
-and dependencies in a single workspace.
-</p>
-
-<p>
-Note that symbolic links should <b>not</b> be used to link files or directories into your workspace.
-</p>
-
-<p>
-Commands and libraries are built from different kinds of source packages.
-We will discuss the distinction <a href="#PackageNames">later</a>.
-</p>
-
-
-<h3 id="GOPATH">The <code>GOPATH</code> environment variable</h3>
-
-<p>
-The <code>GOPATH</code> environment variable specifies the location of your
-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.
-</p>
-
-<p>
-If you would like to work in a different location, you will need to
-<a href="https://golang.org/wiki/SettingGOPATH">set <code>GOPATH</code></a>
-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>
-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>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>
-To learn more about the <code>GOPATH</code> environment variable, see
-<a href="/cmd/go/#hdr-GOPATH_environment_variable"><code>'go help gopath'</code></a>.
-</p>
-
-<h3 id="ImportPaths">Import paths</h3>
-
-<p>
-An <i>import path</i> is a string that uniquely identifies a package.
-A package's import path corresponds to its location inside a workspace
-or in a remote repository (explained below).
-</p>
-
-<p>
-The packages from the standard library are given short import paths such as
-<code>"fmt"</code> and <code>"net/http"</code>.
-For your own packages, you must choose a base path that is unlikely to
-collide with future additions to the standard library or other external
-libraries.
-</p>
-
-<p>
-If you keep your code in a source repository somewhere, then you should use the
-root of that source repository as your base path.
-For instance, if you have a <a href="https://github.com/">GitHub</a> account at
-<code>github.com/user</code>, that should be your base path.
+A repository contains one or more modules. A <dfn>module</dfn> is a collection
+of related Go packages that are released together. A Go repository typically
+contains only one module, located at the root of the repository. A file named
+<code>go.mod</code> there declares the <dfn>module path</dfn>: the import path
+prefix for all packages within the module. The module contains the packages in
+the directory containing its <code>go.mod</code> file as well as subdirectories
+of that directory, up to the next subdirectory containing another
+<code>go.mod</code> file (if any).
</p>
<p>
Note that you don't need to publish your code to a remote repository before you
-can build it. It's just a good habit to organize your code as if you will
-publish it someday. In practice you can choose any arbitrary path name,
-as long as it is unique to the standard library and greater Go ecosystem.
+can build it. A module can be defined locally without belonging to a repository.
+However, it's a good habit to organize your code as if you will publish it
+someday.
</p>
<p>
-We'll use <code>github.com/user</code> as our base path. Create a directory
-inside your workspace in which to keep source code:
+Each module's path not only serves as an import path prefix for its packages,
+but also indicates where the <code>go</code> command should look to download it.
+For example, in order to download the module <code>golang.org/x/tools</code>,
+the <code>go</code> command would consult the repository indicated by
+<code>https://golang.org/x/tools</code> (described more <a href="https://golang.org/cmd/go/#hdr-Relative_import_paths">here</a>).
+</p>
+
+<p>
+An <dfn>import path</dfn> is a string used to import a package. A package's
+import path is its module path joined with its subdirectory within the module.
+For example, the module <code>github.com/google/go-cmp</code> contains a package
+in the directory <code>cmp/</code>. That package's import path is
+<code>github.com/google/go-cmp/cmp</code>. Packages in the standard library do
+not have a module path prefix.
+</p>
+
+<h2 id="Command">Your first program</h2>
+
+<p>
+To compile and run a simple program, first choose a module path (we'll use
+<code>github.com/user/hello</code>) and create a <code>go.mod</code> file that
+declares it:
</p>
<pre>
-$ <b>mkdir -p $GOPATH/src/github.com/user</b>
+$ mkdir hello # Alternatively, clone it if it already exists in version control.
+$ cd hello
+$ <b>go mod init github.com/user/hello</b>
+go: creating new go.mod: module github.com/user/hello
+$ cat go.mod
+module github.com/user/hello
+
+go 1.13
+$
</pre>
-
-<h3 id="Command">Your first program</h3>
-
<p>
-To compile and run a simple program, first choose a package path (we'll use
-<code>github.com/user/hello</code>) and create a corresponding package directory
-inside your workspace:
+The first statement in a Go source file must be
+<code>package <dfn>name</dfn></code>. Executable commands must always use
+<code>package main</code>.
</p>
-<pre>
-$ <b>mkdir $GOPATH/src/github.com/user/hello</b>
-</pre>
-
<p>
-Next, create a file named <code>hello.go</code> inside that directory,
-containing the following Go code.
+Next, create a file named <code>hello.go</code> inside that directory containing
+the following Go code:
</p>
<pre>
@@ -239,55 +109,60 @@
<pre>
$ <b>go install github.com/user/hello</b>
-</pre>
-
-<p>
-Note that you can run this command from anywhere on your system. The
-<code>go</code> tool finds the source code by looking for the
-<code>github.com/user/hello</code> package inside the workspace specified by
-<code>GOPATH</code>.
-</p>
-
-<p>
-You can also omit the package path if you run <code>go install</code> from the
-package directory:
-</p>
-
-<pre>
-$ <b>cd $GOPATH/src/github.com/user/hello</b>
-$ <b>go install</b>
+$
</pre>
<p>
This command builds the <code>hello</code> command, producing an executable
-binary. It then installs that binary to the workspace's <code>bin</code>
-directory as <code>hello</code> (or, under Windows, <code>hello.exe</code>).
-In our example, that will be <code>$GOPATH/bin/hello</code>, which is
-<code>$HOME/go/bin/hello</code>.
-</p>
-
-<p>
-The <code>go</code> tool will only print output when an error occurs, so if
-these commands produce no output they have executed successfully.
-</p>
-
-<p>
-You can now run the program by typing its full path at the command line:
+binary. It then installs that binary as <code>$HOME/go/bin/hello</code> (or,
+under Windows, <code>%USERPROFILE%\go\bin\hello.exe</code>). You can change the
+install directory by setting the <code>GOBIN</code>
+<a href="/cmd/go/#hdr-Environment_variables">environment variable</a>.
</p>
<pre>
-$ <b>$GOPATH/bin/hello</b>
-Hello, world.
+$ go env -w GOBIN=/somewhere/else/bin
+$
</pre>
<p>
-Or, as you have added <code>$GOPATH/bin</code> to your <code>PATH</code>,
-just type the binary name:
+Commands like <code>go install</code> apply within the context of the module
+containing the current working directory. If the working directory is not within
+the <code>github.com/user/hello</code> module, <code>go install</code> may fail.
+</p>
+
+<p>
+For convenience, <code>go</code> commands accept paths relative
+to the working directory, and default to the package in the
+current working directory if no other path is given.
+So in our working directory, the following commands are all equivalent:
</p>
<pre>
+$ go install github.com/user/hello
+</pre>
+
+<pre>
+$ go install .
+</pre>
+
+<pre>
+$ go install
+</pre>
+
+<p>
+Next, let's run the program to ensure it works. For added convenience, we'll
+add the install directory to our <code>PATH</code> to make running binaries
+easy:
+</p>
+
+<pre>
+# Windows users should consult https://github.com/golang/go/wiki/SettingGOPATH
+# for setting %PATH%.
+$ <b>export PATH=$PATH:$(go env GOBIN)</b>
$ <b>hello</b>
Hello, world.
+$
</pre>
<p>
@@ -297,47 +172,32 @@
</p>
<pre>
-$ <b>cd $GOPATH/src/github.com/user/hello</b>
$ <b>git init</b>
-Initialized empty Git repository in /home/user/go/src/github.com/user/hello/.git/
-$ <b>git add hello.go</b>
+Initialized empty Git repository in /home/user/hello/.git/
+$ <b>git add go.mod hello.go</b>
$ <b>git commit -m "initial commit"</b>
[master (root-commit) 0b4507d] initial commit
1 file changed, 7 insertion(+)
- create mode 100644 hello.go
+ create mode 100644 go.mod hello.go
+$
</pre>
-<p>
-Pushing the code to a remote repository is left as an exercise for the reader.
-</p>
-
-
-<h3 id="Library">Your first library</h3>
+<h3 id="ImportingLocal">Importing packages from your module</h3>
<p>
-Let's write a library and use it from the <code>hello</code> program.
-</p>
-
-<p>
-Again, the first step is to choose a package path (we'll use
-<code>github.com/user/stringutil</code>) and create the package directory:
+Let's write a <code>morestrings</code> package and use it from the <code>hello</code> program.
+First, create a directory for the package named
+<code>$HOME/hello/morestrings</code>, and then a file named
+<code>reverse.go</code> in that directory with the following contents:
</p>
<pre>
-$ <b>mkdir $GOPATH/src/github.com/user/stringutil</b>
-</pre>
+// Package morestrings implements additional functions to manipulate UTF-8
+// encoded strings, beyond what is provided in the standard "strings" package.
+package morestrings
-<p>
-Next, create a file named <code>reverse.go</code> in that directory with the
-following contents.
-</p>
-
-<pre>
-// Package stringutil contains utility functions for working with strings.
-package stringutil
-
-// Reverse returns its argument string reversed rune-wise left to right.
-func Reverse(s string) string {
+// ReverseRunes returns its argument string reversed rune-wise left to right.
+func ReverseRunes(s string) string {
r := []rune(s)
for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
r[i], r[j] = r[j], r[i]
@@ -347,30 +207,31 @@
</pre>
<p>
-Now, test that the package compiles with <code>go build</code>:
+Because our <code>ReverseRunes</code> function begins with an upper-case
+letter, it is <a href="/ref/spec#Exported_identifiers"><dfn>exported</dfn></a>,
+and can be used in other packages that import our <code>morestrings</code>
+package.
</p>
-<pre>
-$ <b>go build github.com/user/stringutil</b>
-</pre>
-
<p>
-Or, if you are working in the package's source directory, just:
+Let's test that the package compiles with <code>go build</code>:
</p>
<pre>
+$ cd $HOME/hello/morestrings
$ <b>go build</b>
+$
</pre>
<p>
-This won't produce an output file.
-Instead it saves the compiled package in the local build cache.
+This won't produce an output file. Instead it saves the compiled package in the
+local build cache.
</p>
<p>
-After confirming that the <code>stringutil</code> package builds,
-modify your original <code>hello.go</code> (which is in
-<code>$GOPATH/src/github.com/user/hello</code>) to use it:
+After confirming that the <code>morestrings</code> package builds, let's use it
+from the <code>hello</code> program. To do so, modify your original
+<code>$HOME/hello/hello.go</code> to use the morestrings package:
</p>
<pre>
@@ -379,11 +240,11 @@
import (
"fmt"
- <b>"github.com/user/stringutil"</b>
+ <b>"github.com/user/hello/morestrings"</b>
)
func main() {
- fmt.Println(stringutil.Reverse("!oG ,olleH"))
+ fmt.Println(morestrings.ReverseRunes("!oG ,olleH"))
}
</pre>
@@ -404,58 +265,61 @@
Hello, Go!
</pre>
+<h3 id="ImportingRemote">Importing packages from remote modules</h3>
+
<p>
-After the steps above, your workspace should look like this:
+An import path can describe how to obtain the package source code using a
+revision control system such as Git or Mercurial. The <code>go</code> tool uses
+this property to automatically fetch packages from remote repositories.
+For instance, to use <code>github.com/google/go-cmp/cmp</code> in your program:
</p>
<pre>
-bin/
- hello # command executable
-src/
- github.com/user/
- hello/
- hello.go # command source
- stringutil/
- reverse.go # package source
+package main
+
+import (
+ "fmt"
+
+ "github.com/user/hello/morestrings"
+ "github.com/google/go-cmp/cmp"
+)
+
+func main() {
+ fmt.Println(morestrings.ReverseRunes("!oG ,olleH"))
+ fmt.Println(cmp.Diff("Hello World", "Hello Go"))
+}
</pre>
-<h3 id="PackageNames">Package names</h3>
-
<p>
-The first statement in a Go source file must be
-</p>
+When you run commands like <code>go install</code>, <code>go build</code>, or
+<code>go run</code>, the remote module will automatically be added to your
+<code>go.mod</code> file (and downloaded):
<pre>
-package <i>name</i>
+$ go install github.com/user/hello
+$ hello
+Hello, Go!
+ string(
+- "Hello World",
++ "Hello Go",
+ )
+$ cat go.mod
+module github.com/user/hello
+
+go 1.13
+
+<b>require github.com/google/go-cmp v0.3.1</b>
+$
</pre>
<p>
-where <code><i>name</i></code> is the package's default name for imports.
-(All files in a package must use the same <code><i>name</i></code>.)
+A module's path doesn't have to match the URL for its repository, but this
+convention is the easiest way to make your Go packages available for others to
+use. For more information on using remote modules with the <code>go</code> tool, see
+<code><a href="/cmd/go/#hdr-Remote_import_paths">go help importpath</a></code>
+and <a href="https://blog.golang.org/using-go-modules">Using Go Modules</a>.
</p>
-<p>
-Go's convention is that the package name is the last element of the
-import path: the package imported as "<code>crypto/rot13</code>"
-should be named <code>rot13</code>.
-</p>
-
-<p>
-Executable commands must always use <code>package main</code>.
-</p>
-
-<p>
-There is no requirement that package names be unique
-across all packages linked into a single binary,
-only that the import paths (their full file names) be unique.
-</p>
-
-<p>
-See <a href="/doc/effective_go.html#names">Effective Go</a> to learn more about
-Go's naming conventions.
-</p>
-
-
<h2 id="Testing">Testing</h2>
<p>
@@ -473,17 +337,17 @@
</p>
<p>
-Add a test to the <code>stringutil</code> package by creating the file
-<code>$GOPATH/src/github.com/user/stringutil/reverse_test.go</code> containing
+Add a test to the <code>morestrings</code> package by creating the file
+<code>$HOME/hello/morestrings/reverse_test.go</code> containing
the following Go code.
</p>
<pre>
-package stringutil
+package morestrings
import "testing"
-func TestReverse(t *testing.T) {
+func TestReverseRunes(t *testing.T) {
cases := []struct {
in, want string
}{
@@ -492,9 +356,9 @@
{"", ""},
}
for _, c := range cases {
- got := Reverse(c.in)
+ got := ReverseRunes(c.in)
if got != c.want {
- t.Errorf("Reverse(%q) == %q, want %q", c.in, got, c.want)
+ t.Errorf("ReverseRunes(%q) == %q, want %q", c.in, got, c.want)
}
}
}
@@ -505,18 +369,10 @@
</p>
<pre>
-$ <b>go test github.com/user/stringutil</b>
-ok github.com/user/stringutil 0.165s
-</pre>
-
-<p>
-As always, if you are running the <code>go</code> tool from the package
-directory, you can omit the package path:
-</p>
-
-<pre>
$ <b>go test</b>
-ok github.com/user/stringutil 0.165s
+PASS
+ok github.com/user/morestrings 0.165s
+$
</pre>
<p>
@@ -524,83 +380,6 @@
<a href="/pkg/testing/">testing package documentation</a> for more detail.
</p>
-
-<h2 id="remote">Remote packages</h2>
-
-<p>
-An import path can describe how to obtain the package source code using a
-revision control system such as Git or Mercurial. The <code>go</code> tool uses
-this property to automatically fetch packages from remote repositories.
-For instance, the examples described in this document are also kept in a
-Git repository hosted at GitHub
-<code><a href="https://github.com/golang/example">github.com/golang/example</a></code>.
-If you include the repository URL in the package's import path,
-<code>go get</code> will fetch, build, and install it automatically:
-</p>
-
-<pre>
-$ <b>go get github.com/golang/example/hello</b>
-$ <b>$GOPATH/bin/hello</b>
-Hello, Go examples!
-</pre>
-
-<p>
-If the specified package is not present in a workspace, <code>go get</code>
-will place it inside the first workspace specified by <code>GOPATH</code>.
-(If the package does already exist, <code>go get</code> skips the remote
-fetch and behaves the same as <code>go install</code>.)
-</p>
-
-<p>
-After issuing the above <code>go get</code> command, the workspace directory
-tree should now look like this:
-</p>
-
-<pre>
-bin/
- hello # command executable
-src/
- github.com/golang/example/
- .git/ # Git repository metadata
- hello/
- hello.go # command source
- stringutil/
- reverse.go # package source
- reverse_test.go # test source
- github.com/user/
- hello/
- hello.go # command source
- stringutil/
- reverse.go # package source
- reverse_test.go # test source
-</pre>
-
-<p>
-The <code>hello</code> command hosted at GitHub depends on the
-<code>stringutil</code> package within the same repository. The imports in
-<code>hello.go</code> file use the same import path convention, so the
-<code>go get</code> command is able to locate and install the dependent
-package, too.
-</p>
-
-<pre>
-import "github.com/golang/example/stringutil"
-</pre>
-
-<p>
-This convention is the easiest way to make your Go packages available for
-others to use.
-The <a href="//golang.org/wiki/Projects">Go Wiki</a>
-and <a href="//godoc.org/">godoc.org</a>
-provide lists of external Go projects.
-</p>
-
-<p>
-For more information on using remote repositories with the <code>go</code> tool, see
-<code><a href="/cmd/go/#hdr-Remote_import_paths">go help importpath</a></code>.
-</p>
-
-
<h2 id="next">What's next</h2>
<p>
@@ -615,7 +394,11 @@
</p>
<p>
-Take <a href="//tour.golang.org/">A Tour of Go</a> to learn the language
+Take {{if $.GoogleCN}}
+A Tour of Go
+{{else}}
+<a href="//tour.golang.org/">A Tour of Go</a>
+{{end}} to learn the language
proper.
</p>
@@ -624,12 +407,12 @@
articles about the Go language and its libraries and tools.
</p>
-
<h2 id="help">Getting help</h2>
<p>
-For real-time help, ask the helpful gophers in <code>#go-nuts</code> on the
-<a href="https://freenode.net/">Freenode</a> IRC server.
+For real-time help, ask the helpful gophers in the community-run
+<a href="https://gophers.slack.com/messages/general/">gophers Slack server</a>
+(grab an invite <a href="https://invite.slack.golangbridge.org/">here</a>).
</p>
<p>
diff --git a/content/static/doc/gopath_code.html b/content/static/doc/gopath_code.html
new file mode 100644
index 0000000..c587ca6
--- /dev/null
+++ b/content/static/doc/gopath_code.html
@@ -0,0 +1,650 @@
+<!--{
+ "Title": "How to Write Go Code (with GOPATH)"
+}-->
+
+<h2 id="Introduction">Introduction</h2>
+
+<p><b>
+If you are new to Go, please see the more recent
+<a href="code.html">How to Write Go Code</a>.
+</b></p>
+
+<p>
+This document demonstrates the development of a simple Go package and
+introduces the <a href="/cmd/go/">go tool</a>, the standard way to fetch,
+build, and install Go packages and commands.
+</p>
+
+<p>
+The <code>go</code> tool requires you to organize your code in a specific
+way. Please read this document carefully.
+It explains the simplest way to get up and running with your Go installation.
+</p>
+
+<p>
+A similar explanation is available as a
+<a href="//www.youtube.com/watch?v=XCsL89YtqCs">screencast</a>.
+</p>
+
+
+<h2 id="Organization">Code organization</h2>
+
+<h3 id="Overview">Overview</h3>
+
+<ul>
+ <li>Go programmers typically keep all their Go code related to a single
+ project in a version control repository.</li>
+ <li>Typically, there is only one <i>module</i> in the root directory of a repository..</li>
+ <li>A workspace contains many version control <i>repositories</i>
+ (managed by Git, for example).</li>
+ <li>Each repository contains one or more <i>packages</i>.</li>
+ <li>Each package consists of one or more Go source files in a single directory.</li>
+ <li>The path to a package's directory determines its <i>import path</i>.</li>
+</ul>
+
+<p>
+Note that this differs from other programming environments in which every
+project has a separate workspace and workspaces are closely tied to version
+control repositories.
+</p>
+
+<h3 id="Workspaces">Workspaces</h3>
+
+<p>
+A workspace is a directory hierarchy with two directories at its root:
+</p>
+
+<ul>
+<li><code>src</code> contains Go source files, and
+<li><code>bin</code> contains executable commands.
+</ul>
+
+<p>
+The <code>go</code> tool builds and installs binaries to the <code>bin</code> directory.
+</p>
+
+<p>
+The <code>src</code> subdirectory typically contains multiple version control
+repositories (such as for Git or Mercurial) that track the development of one
+or more source packages.
+</p>
+
+<p>
+To give you an idea of how a workspace looks in practice, here's an example:
+</p>
+
+<pre>
+bin/
+ hello # command executable
+ outyet # command executable
+src/
+ <a href="https://github.com/golang/example/">github.com/golang/example/</a>
+ .git/ # Git repository metadata
+ hello/
+ hello.go # command source
+ outyet/
+ main.go # command source
+ main_test.go # test source
+ stringutil/
+ reverse.go # package source
+ reverse_test.go # test source
+ <a href="https://golang.org/x/image/">golang.org/x/image/</a>
+ .git/ # Git repository metadata
+ bmp/
+ reader.go # package source
+ writer.go # package source
+ ... (many more repositories and packages omitted) ...
+</pre>
+
+<p>
+The tree above shows a workspace containing two repositories
+(<code>example</code> and <code>image</code>).
+The <code>example</code> repository contains two commands (<code>hello</code>
+and <code>outyet</code>) and one library (<code>stringutil</code>).
+The <code>image</code> repository contains the <code>bmp</code> package
+and <a href="https://godoc.org/golang.org/x/image">several others</a>.
+</p>
+
+<p>
+A typical workspace contains many source repositories containing many
+packages and commands. Most Go programmers keep <i>all</i> their Go source code
+and dependencies in a single workspace.
+</p>
+
+<p>
+Note that symbolic links should <b>not</b> be used to link files or directories into your workspace.
+</p>
+
+<p>
+Commands and libraries are built from different kinds of source packages.
+We will discuss the distinction <a href="#PackageNames">later</a>.
+</p>
+
+
+<h3 id="GOPATH">The <code>GOPATH</code> environment variable</h3>
+
+<p>
+The <code>GOPATH</code> environment variable specifies the location of your
+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.
+</p>
+
+<p>
+If you would like to work in a different location, you will need to
+<a href="https://golang.org/wiki/SettingGOPATH">set <code>GOPATH</code></a>
+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>
+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>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>
+To learn more about the <code>GOPATH</code> environment variable, see
+<a href="/cmd/go/#hdr-GOPATH_environment_variable"><code>'go help gopath'</code></a>.
+</p>
+
+<h3 id="ImportPaths">Import paths</h3>
+
+<p>
+An <i>import path</i> is a string that uniquely identifies a package.
+A package's import path corresponds to its location inside a workspace
+or in a remote repository (explained below).
+</p>
+
+<p>
+The packages from the standard library are given short import paths such as
+<code>"fmt"</code> and <code>"net/http"</code>.
+For your own packages, you must choose a base path that is unlikely to
+collide with future additions to the standard library or other external
+libraries.
+</p>
+
+<p>
+If you keep your code in a source repository somewhere, then you should use the
+root of that source repository as your base path.
+For instance, if you have a <a href="https://github.com/">GitHub</a> account at
+<code>github.com/user</code>, that should be your base path.
+</p>
+
+<p>
+Note that you don't need to publish your code to a remote repository before you
+can build it. It's just a good habit to organize your code as if you will
+publish it someday. In practice you can choose any arbitrary path name,
+as long as it is unique to the standard library and greater Go ecosystem.
+</p>
+
+<p>
+We'll use <code>github.com/user</code> as our base path. Create a directory
+inside your workspace in which to keep source code:
+</p>
+
+<pre>
+$ <b>mkdir -p $GOPATH/src/github.com/user</b>
+</pre>
+
+
+<h3 id="Command">Your first program</h3>
+
+<p>
+To compile and run a simple program, first choose a package path (we'll use
+<code>github.com/user/hello</code>) and create a corresponding package directory
+inside your workspace:
+</p>
+
+<pre>
+$ <b>mkdir $GOPATH/src/github.com/user/hello</b>
+</pre>
+
+<p>
+Next, create a file named <code>hello.go</code> inside that directory,
+containing the following Go code.
+</p>
+
+<pre>
+package main
+
+import "fmt"
+
+func main() {
+ fmt.Println("Hello, world.")
+}
+</pre>
+
+<p>
+Now you can build and install that program with the <code>go</code> tool:
+</p>
+
+<pre>
+$ <b>go install github.com/user/hello</b>
+</pre>
+
+<p>
+Note that you can run this command from anywhere on your system. The
+<code>go</code> tool finds the source code by looking for the
+<code>github.com/user/hello</code> package inside the workspace specified by
+<code>GOPATH</code>.
+</p>
+
+<p>
+You can also omit the package path if you run <code>go install</code> from the
+package directory:
+</p>
+
+<pre>
+$ <b>cd $GOPATH/src/github.com/user/hello</b>
+$ <b>go install</b>
+</pre>
+
+<p>
+This command builds the <code>hello</code> command, producing an executable
+binary. It then installs that binary to the workspace's <code>bin</code>
+directory as <code>hello</code> (or, under Windows, <code>hello.exe</code>).
+In our example, that will be <code>$GOPATH/bin/hello</code>, which is
+<code>$HOME/go/bin/hello</code>.
+</p>
+
+<p>
+The <code>go</code> tool will only print output when an error occurs, so if
+these commands produce no output they have executed successfully.
+</p>
+
+<p>
+You can now run the program by typing its full path at the command line:
+</p>
+
+<pre>
+$ <b>$GOPATH/bin/hello</b>
+Hello, world.
+</pre>
+
+<p>
+Or, as you have added <code>$GOPATH/bin</code> to your <code>PATH</code>,
+just type the binary name:
+</p>
+
+<pre>
+$ <b>hello</b>
+Hello, world.
+</pre>
+
+<p>
+If you're using a source control system, now would be a good time to initialize
+a repository, add the files, and commit your first change. Again, this step is
+optional: you do not need to use source control to write Go code.
+</p>
+
+<pre>
+$ <b>cd $GOPATH/src/github.com/user/hello</b>
+$ <b>git init</b>
+Initialized empty Git repository in /home/user/go/src/github.com/user/hello/.git/
+$ <b>git add hello.go</b>
+$ <b>git commit -m "initial commit"</b>
+[master (root-commit) 0b4507d] initial commit
+ 1 file changed, 7 insertion(+)
+ create mode 100644 hello.go
+</pre>
+
+<p>
+Pushing the code to a remote repository is left as an exercise for the reader.
+</p>
+
+
+<h3 id="Library">Your first library</h3>
+
+<p>
+Let's write a library and use it from the <code>hello</code> program.
+</p>
+
+<p>
+Again, the first step is to choose a package path (we'll use
+<code>github.com/user/stringutil</code>) and create the package directory:
+</p>
+
+<pre>
+$ <b>mkdir $GOPATH/src/github.com/user/stringutil</b>
+</pre>
+
+<p>
+Next, create a file named <code>reverse.go</code> in that directory with the
+following contents.
+</p>
+
+<pre>
+// Package stringutil contains utility functions for working with strings.
+package stringutil
+
+// Reverse returns its argument string reversed rune-wise left to right.
+func Reverse(s string) string {
+ r := []rune(s)
+ for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
+ r[i], r[j] = r[j], r[i]
+ }
+ return string(r)
+}
+</pre>
+
+<p>
+Now, test that the package compiles with <code>go build</code>:
+</p>
+
+<pre>
+$ <b>go build github.com/user/stringutil</b>
+</pre>
+
+<p>
+Or, if you are working in the package's source directory, just:
+</p>
+
+<pre>
+$ <b>go build</b>
+</pre>
+
+<p>
+This won't produce an output file.
+Instead it saves the compiled package in the local build cache.
+</p>
+
+<p>
+After confirming that the <code>stringutil</code> package builds,
+modify your original <code>hello.go</code> (which is in
+<code>$GOPATH/src/github.com/user/hello</code>) to use it:
+</p>
+
+<pre>
+package main
+
+import (
+ "fmt"
+
+ <b>"github.com/user/stringutil"</b>
+)
+
+func main() {
+ fmt.Println(stringutil.Reverse("!oG ,olleH"))
+}
+</pre>
+
+<p>
+Install the <code>hello</code> program:
+</p>
+
+<pre>
+$ <b>go install github.com/user/hello</b>
+</pre>
+
+<p>
+Running the new version of the program, you should see a new, reversed message:
+</p>
+
+<pre>
+$ <b>hello</b>
+Hello, Go!
+</pre>
+
+<p>
+After the steps above, your workspace should look like this:
+</p>
+
+<pre>
+bin/
+ hello # command executable
+src/
+ github.com/user/
+ hello/
+ hello.go # command source
+ stringutil/
+ reverse.go # package source
+</pre>
+
+<h3 id="PackageNames">Package names</h3>
+
+<p>
+The first statement in a Go source file must be
+</p>
+
+<pre>
+package <i>name</i>
+</pre>
+
+<p>
+where <code><i>name</i></code> is the package's default name for imports.
+(All files in a package must use the same <code><i>name</i></code>.)
+</p>
+
+<p>
+Go's convention is that the package name is the last element of the
+import path: the package imported as "<code>crypto/rot13</code>"
+should be named <code>rot13</code>.
+</p>
+
+<p>
+Executable commands must always use <code>package main</code>.
+</p>
+
+<p>
+There is no requirement that package names be unique
+across all packages linked into a single binary,
+only that the import paths (their full file names) be unique.
+</p>
+
+<p>
+See <a href="/doc/effective_go.html#names">Effective Go</a> to learn more about
+Go's naming conventions.
+</p>
+
+
+<h2 id="Testing">Testing</h2>
+
+<p>
+Go has a lightweight test framework composed of the <code>go test</code>
+command and the <code>testing</code> package.
+</p>
+
+<p>
+You write a test by creating a file with a name ending in <code>_test.go</code>
+that contains functions named <code>TestXXX</code> with signature
+<code>func (t *testing.T)</code>.
+The test framework runs each such function;
+if the function calls a failure function such as <code>t.Error</code> or
+<code>t.Fail</code>, the test is considered to have failed.
+</p>
+
+<p>
+Add a test to the <code>stringutil</code> package by creating the file
+<code>$GOPATH/src/github.com/user/stringutil/reverse_test.go</code> containing
+the following Go code.
+</p>
+
+<pre>
+package stringutil
+
+import "testing"
+
+func TestReverse(t *testing.T) {
+ cases := []struct {
+ in, want string
+ }{
+ {"Hello, world", "dlrow ,olleH"},
+ {"Hello, 世界", "界世 ,olleH"},
+ {"", ""},
+ }
+ for _, c := range cases {
+ got := Reverse(c.in)
+ if got != c.want {
+ t.Errorf("Reverse(%q) == %q, want %q", c.in, got, c.want)
+ }
+ }
+}
+</pre>
+
+<p>
+Then run the test with <code>go test</code>:
+</p>
+
+<pre>
+$ <b>go test github.com/user/stringutil</b>
+ok github.com/user/stringutil 0.165s
+</pre>
+
+<p>
+As always, if you are running the <code>go</code> tool from the package
+directory, you can omit the package path:
+</p>
+
+<pre>
+$ <b>go test</b>
+ok github.com/user/stringutil 0.165s
+</pre>
+
+<p>
+Run <code><a href="/cmd/go/#hdr-Test_packages">go help test</a></code> and see the
+<a href="/pkg/testing/">testing package documentation</a> for more detail.
+</p>
+
+
+<h2 id="remote">Remote packages</h2>
+
+<p>
+An import path can describe how to obtain the package source code using a
+revision control system such as Git or Mercurial. The <code>go</code> tool uses
+this property to automatically fetch packages from remote repositories.
+For instance, the examples described in this document are also kept in a
+Git repository hosted at GitHub
+<code><a href="https://github.com/golang/example">github.com/golang/example</a></code>.
+If you include the repository URL in the package's import path,
+<code>go get</code> will fetch, build, and install it automatically:
+</p>
+
+<pre>
+$ <b>go get github.com/golang/example/hello</b>
+$ <b>$GOPATH/bin/hello</b>
+Hello, Go examples!
+</pre>
+
+<p>
+If the specified package is not present in a workspace, <code>go get</code>
+will place it inside the first workspace specified by <code>GOPATH</code>.
+(If the package does already exist, <code>go get</code> skips the remote
+fetch and behaves the same as <code>go install</code>.)
+</p>
+
+<p>
+After issuing the above <code>go get</code> command, the workspace directory
+tree should now look like this:
+</p>
+
+<pre>
+bin/
+ hello # command executable
+src/
+ github.com/golang/example/
+ .git/ # Git repository metadata
+ hello/
+ hello.go # command source
+ stringutil/
+ reverse.go # package source
+ reverse_test.go # test source
+ github.com/user/
+ hello/
+ hello.go # command source
+ stringutil/
+ reverse.go # package source
+ reverse_test.go # test source
+</pre>
+
+<p>
+The <code>hello</code> command hosted at GitHub depends on the
+<code>stringutil</code> package within the same repository. The imports in
+<code>hello.go</code> file use the same import path convention, so the
+<code>go get</code> command is able to locate and install the dependent
+package, too.
+</p>
+
+<pre>
+import "github.com/golang/example/stringutil"
+</pre>
+
+<p>
+This convention is the easiest way to make your Go packages available for
+others to use.
+The <a href="//golang.org/wiki/Projects">Go Wiki</a>
+and <a href="//godoc.org/">godoc.org</a>
+provide lists of external Go projects.
+</p>
+
+<p>
+For more information on using remote repositories with the <code>go</code> tool, see
+<code><a href="/cmd/go/#hdr-Remote_import_paths">go help importpath</a></code>.
+</p>
+
+
+<h2 id="next">What's next</h2>
+
+<p>
+Subscribe to the
+<a href="//groups.google.com/group/golang-announce">golang-announce</a>
+mailing list to be notified when a new stable version of Go is released.
+</p>
+
+<p>
+See <a href="/doc/effective_go.html">Effective Go</a> for tips on writing
+clear, idiomatic Go code.
+</p>
+
+<p>
+Take <a href="//tour.golang.org/">A Tour of Go</a> to learn the language
+proper.
+</p>
+
+<p>
+Visit the <a href="/doc/#articles">documentation page</a> for a set of in-depth
+articles about the Go language and its libraries and tools.
+</p>
+
+
+<h2 id="help">Getting help</h2>
+
+<p>
+For real-time help, ask the helpful gophers in <code>#go-nuts</code> on the
+<a href="https://freenode.net/">Freenode</a> IRC server.
+</p>
+
+<p>
+The official mailing list for discussion of the Go language is
+<a href="//groups.google.com/group/golang-nuts">Go Nuts</a>.
+</p>
+
+<p>
+Report bugs using the
+<a href="//golang.org/issue">Go issue tracker</a>.
+</p>
diff --git a/content/static/static.go b/content/static/static.go
index f2f648a..95858cc 100644
--- a/content/static/static.go
+++ b/content/static/static.go
@@ -45,7 +45,7 @@
"dirlist.html": "<!--\x0a\x09Copyright\x202009\x20The\x20Go\x20Authors.\x20All\x20rights\x20reserved.\x0a\x09Use\x20of\x20this\x20source\x20code\x20is\x20governed\x20by\x20a\x20BSD-style\x0a\x09license\x20that\x20can\x20be\x20found\x20in\x20the\x20LICENSE\x20file.\x0a-->\x0a\x0a<p>\x0a<table\x20class=\"layout\">\x0a<tr>\x0a\x09<th\x20align=\"left\">File</th>\x0a\x09<td\x20width=\"25\"> </td>\x0a\x09<th\x20align=\"right\">Bytes</th>\x0a\x09<td\x20width=\"25\"> </td>\x0a\x09<th\x20align=\"left\">Modified</th>\x0a</tr>\x0a<tr>\x0a\x09<td><a\x20href=\"..\">..</a></td>\x0a</tr>\x0a{{range\x20.}}\x0a<tr>\x0a\x09{{$name_html\x20:=\x20fileInfoName\x20.\x20|\x20html}}\x0a\x09<td\x20align=\"left\"><a\x20href=\"{{$name_html}}\">{{$name_html}}</a></td>\x0a\x09<td></td>\x0a\x09<td\x20align=\"right\">{{html\x20.Size}}</td>\x0a\x09<td></td>\x0a\x09<td\x20align=\"left\">{{fileInfoTime\x20.\x20|\x20html}}</td>\x0a</tr>\x0a{{end}}\x0a\x0a</table>\x0a</p>\x0a",
- "doc/code.html": "<!--{\x0a\x09\"Title\":\x20\"How\x20to\x20Write\x20Go\x20Code\"\x0a}-->\x0a\x0a<h2\x20id=\"Introduction\">Introduction</h2>\x0a\x0a<p>\x0aThis\x20document\x20demonstrates\x20the\x20development\x20of\x20a\x20simple\x20Go\x20package\x20and\x0aintroduces\x20the\x20<a\x20href=\"/cmd/go/\">go\x20tool</a>,\x20the\x20standard\x20way\x20to\x20fetch,\x0abuild,\x20and\x20install\x20Go\x20packages\x20and\x20commands.\x0a</p>\x0a\x0a<p>\x0aThe\x20<code>go</code>\x20tool\x20requires\x20you\x20to\x20organize\x20your\x20code\x20in\x20a\x20specific\x0away.\x20Please\x20read\x20this\x20document\x20carefully.\x0aIt\x20explains\x20the\x20simplest\x20way\x20to\x20get\x20up\x20and\x20running\x20with\x20your\x20Go\x20installation.\x0a</p>\x0a\x0a<p>\x0aA\x20similar\x20explanation\x20is\x20available\x20as\x20a\x0a<a\x20href=\"//www.youtube.com/watch?v=XCsL89YtqCs\">screencast</a>.\x0a</p>\x0a\x0a\x0a<h2\x20id=\"Organization\">Code\x20organization</h2>\x0a\x0a<h3\x20id=\"Overview\">Overview</h3>\x0a\x0a<ul>\x0a\x09<li>Go\x20programmers\x20typically\x20keep\x20all\x20their\x20Go\x20code\x20in\x20a\x20single\x20<i>workspace</i>.</li>\x0a\x09<li>A\x20workspace\x20contains\x20many\x20version\x20control\x20<i>repositories</i>\x0a\x09\x20\x20\x20\x20(managed\x20by\x20Git,\x20for\x20example).</li>\x0a\x09<li>Each\x20repository\x20contains\x20one\x20or\x20more\x20<i>packages</i>.</li>\x0a\x09<li>Each\x20package\x20consists\x20of\x20one\x20or\x20more\x20Go\x20source\x20files\x20in\x20a\x20single\x20directory.</li>\x0a\x09<li>The\x20path\x20to\x20a\x20package's\x20directory\x20determines\x20its\x20<i>import\x20path</i>.</li>\x0a</ul>\x0a\x0a<p>\x0aNote\x20that\x20this\x20differs\x20from\x20other\x20programming\x20environments\x20in\x20which\x20every\x0aproject\x20has\x20a\x20separate\x20workspace\x20and\x20workspaces\x20are\x20closely\x20tied\x20to\x20version\x0acontrol\x20repositories.\x0a</p>\x0a\x0a<h3\x20id=\"Workspaces\">Workspaces</h3>\x0a\x0a<p>\x0aA\x20workspace\x20is\x20a\x20directory\x20hierarchy\x20with\x20two\x20directories\x20at\x20its\x20root:\x0a</p>\x0a\x0a<ul>\x0a<li><code>src</code>\x20contains\x20Go\x20source\x20files,\x20and\x0a<li><code>bin</code>\x20contains\x20executable\x20commands.\x0a</ul>\x0a\x0a<p>\x0aThe\x20<code>go</code>\x20tool\x20builds\x20and\x20installs\x20binaries\x20to\x20the\x20<code>bin</code>\x20directory.\x0a</p>\x0a\x0a<p>\x0aThe\x20<code>src</code>\x20subdirectory\x20typically\x20contains\x20multiple\x20version\x20control\x0arepositories\x20(such\x20as\x20for\x20Git\x20or\x20Mercurial)\x20that\x20track\x20the\x20development\x20of\x20one\x0aor\x20more\x20source\x20packages.\x0a</p>\x0a\x0a<p>\x0aTo\x20give\x20you\x20an\x20idea\x20of\x20how\x20a\x20workspace\x20looks\x20in\x20practice,\x20here's\x20an\x20example:\x0a</p>\x0a\x0a<pre>\x0abin/\x0a\x20\x20\x20\x20hello\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20command\x20executable\x0a\x20\x20\x20\x20outyet\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20command\x20executable\x0asrc/\x0a\x20\x20\x20\x20<a\x20href=\"https://github.com/golang/example/\">github.com/golang/example/</a>\x0a\x20\x20\x20\x20\x20\x20\x20\x20.git/\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20Git\x20repository\x20metadata\x0a\x09hello/\x0a\x09\x20\x20\x20\x20hello.go\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20command\x20source\x0a\x09outyet/\x0a\x09\x20\x20\x20\x20main.go\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20command\x20source\x0a\x09\x20\x20\x20\x20main_test.go\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20test\x20source\x0a\x09stringutil/\x0a\x09\x20\x20\x20\x20reverse.go\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20package\x20source\x0a\x09\x20\x20\x20\x20reverse_test.go\x20\x20\x20\x20\x20\x20\x20\x20#\x20test\x20source\x0a\x20\x20\x20\x20<a\x20href=\"https://golang.org/x/image/\">golang.org/x/image/</a>\x0a\x20\x20\x20\x20\x20\x20\x20\x20.git/\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20Git\x20repository\x20metadata\x0a\x09bmp/\x0a\x09\x20\x20\x20\x20reader.go\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20package\x20source\x0a\x09\x20\x20\x20\x20writer.go\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20package\x20source\x0a\x20\x20\x20\x20...\x20(many\x20more\x20repositories\x20and\x20packages\x20omitted)\x20...\x0a</pre>\x0a\x0a<p>\x0aThe\x20tree\x20above\x20shows\x20a\x20workspace\x20containing\x20two\x20repositories\x0a(<code>example</code>\x20and\x20<code>image</code>).\x0aThe\x20<code>example</code>\x20repository\x20contains\x20two\x20commands\x20(<code>hello</code>\x0aand\x20<code>outyet</code>)\x20and\x20one\x20library\x20(<code>stringutil</code>).\x0aThe\x20<code>image</code>\x20repository\x20contains\x20the\x20<code>bmp</code>\x20package\x0aand\x20<a\x20href=\"https://godoc.org/golang.org/x/image\">several\x20others</a>.\x0a</p>\x0a\x0a<p>\x0aA\x20typical\x20workspace\x20contains\x20many\x20source\x20repositories\x20containing\x20many\x0apackages\x20and\x20commands.\x20Most\x20Go\x20programmers\x20keep\x20<i>all</i>\x20their\x20Go\x20source\x20code\x0aand\x20dependencies\x20in\x20a\x20single\x20workspace.\x0a</p>\x0a\x0a<p>\x0aNote\x20that\x20symbolic\x20links\x20should\x20<b>not</b>\x20be\x20used\x20to\x20link\x20files\x20or\x20directories\x20into\x20your\x20workspace.\x0a</p>\x0a\x0a<p>\x0aCommands\x20and\x20libraries\x20are\x20built\x20from\x20different\x20kinds\x20of\x20source\x20packages.\x0aWe\x20will\x20discuss\x20the\x20distinction\x20<a\x20href=\"#PackageNames\">later</a>.\x0a</p>\x0a\x0a\x0a<h3\x20id=\"GOPATH\">The\x20<code>GOPATH</code>\x20environment\x20variable</h3>\x0a\x0a<p>\x0aThe\x20<code>GOPATH</code>\x20environment\x20variable\x20specifies\x20the\x20location\x20of\x20your\x0aworkspace.\x20It\x20defaults\x20to\x20a\x20directory\x20named\x20<code>go</code>\x20inside\x20your\x20home\x20directory,\x0aso\x20<code>$HOME/go</code>\x20on\x20Unix,\x0a<code>$home/go</code>\x20on\x20Plan\x209,\x0aand\x20<code>%USERPROFILE%\\go</code>\x20(usually\x20<code>C:\\Users\\YourName\\go</code>)\x20on\x20Windows.\x0a</p>\x0a\x0a<p>\x0aIf\x20you\x20would\x20like\x20to\x20work\x20in\x20a\x20different\x20location,\x20you\x20will\x20need\x20to\x0a<a\x20href=\"https://golang.org/wiki/SettingGOPATH\">set\x20<code>GOPATH</code></a>\x0ato\x20the\x20path\x20to\x20that\x20directory.\x0a(Another\x20common\x20setup\x20is\x20to\x20set\x20<code>GOPATH=$HOME</code>.)\x0aNote\x20that\x20<code>GOPATH</code>\x20must\x20<b>not</b>\x20be\x20the\x0asame\x20path\x20as\x20your\x20Go\x20installation.\x0a</p>\x0a\x0a<p>\x0aThe\x20command\x20<code>go</code>\x20<code>env</code>\x20<code>GOPATH</code>\x0aprints\x20the\x20effective\x20current\x20<code>GOPATH</code>;\x0ait\x20prints\x20the\x20default\x20location\x20if\x20the\x20environment\x20variable\x20is\x20unset.\x0a</p>\x0a\x0a<p>\x0aFor\x20convenience,\x20add\x20the\x20workspace's\x20<code>bin</code>\x20subdirectory\x0ato\x20your\x20<code>PATH</code>:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>export\x20PATH=$PATH:$(go\x20env\x20GOPATH)/bin</b>\x0a</pre>\x0a\x0a<p>\x0aThe\x20scripts\x20in\x20the\x20rest\x20of\x20this\x20document\x20use\x20<code>$GOPATH</code>\x0ainstead\x20of\x20<code>$(go\x20env\x20GOPATH)</code>\x20for\x20brevity.\x0aTo\x20make\x20the\x20scripts\x20run\x20as\x20written\x0aif\x20you\x20have\x20not\x20set\x20GOPATH,\x0ayou\x20can\x20substitute\x20$HOME/go\x20in\x20those\x20commands\x0aor\x20else\x20run:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>export\x20GOPATH=$(go\x20env\x20GOPATH)</b>\x0a</pre>\x0a\x0a<p>\x0aTo\x20learn\x20more\x20about\x20the\x20<code>GOPATH</code>\x20environment\x20variable,\x20see\x0a<a\x20href=\"/cmd/go/#hdr-GOPATH_environment_variable\"><code>'go\x20help\x20gopath'</code></a>.\x0a</p>\x0a\x0a<h3\x20id=\"ImportPaths\">Import\x20paths</h3>\x0a\x0a<p>\x0aAn\x20<i>import\x20path</i>\x20is\x20a\x20string\x20that\x20uniquely\x20identifies\x20a\x20package.\x0aA\x20package's\x20import\x20path\x20corresponds\x20to\x20its\x20location\x20inside\x20a\x20workspace\x0aor\x20in\x20a\x20remote\x20repository\x20(explained\x20below).\x0a</p>\x0a\x0a<p>\x0aThe\x20packages\x20from\x20the\x20standard\x20library\x20are\x20given\x20short\x20import\x20paths\x20such\x20as\x0a<code>\"fmt\"</code>\x20and\x20<code>\"net/http\"</code>.\x0aFor\x20your\x20own\x20packages,\x20you\x20must\x20choose\x20a\x20base\x20path\x20that\x20is\x20unlikely\x20to\x0acollide\x20with\x20future\x20additions\x20to\x20the\x20standard\x20library\x20or\x20other\x20external\x0alibraries.\x0a</p>\x0a\x0a<p>\x0aIf\x20you\x20keep\x20your\x20code\x20in\x20a\x20source\x20repository\x20somewhere,\x20then\x20you\x20should\x20use\x20the\x0aroot\x20of\x20that\x20source\x20repository\x20as\x20your\x20base\x20path.\x0aFor\x20instance,\x20if\x20you\x20have\x20a\x20<a\x20href=\"https://github.com/\">GitHub</a>\x20account\x20at\x0a<code>github.com/user</code>,\x20that\x20should\x20be\x20your\x20base\x20path.\x0a</p>\x0a\x0a<p>\x0aNote\x20that\x20you\x20don't\x20need\x20to\x20publish\x20your\x20code\x20to\x20a\x20remote\x20repository\x20before\x20you\x0acan\x20build\x20it.\x20It's\x20just\x20a\x20good\x20habit\x20to\x20organize\x20your\x20code\x20as\x20if\x20you\x20will\x0apublish\x20it\x20someday.\x20In\x20practice\x20you\x20can\x20choose\x20any\x20arbitrary\x20path\x20name,\x0aas\x20long\x20as\x20it\x20is\x20unique\x20to\x20the\x20standard\x20library\x20and\x20greater\x20Go\x20ecosystem.\x0a</p>\x0a\x0a<p>\x0aWe'll\x20use\x20<code>github.com/user</code>\x20as\x20our\x20base\x20path.\x20Create\x20a\x20directory\x0ainside\x20your\x20workspace\x20in\x20which\x20to\x20keep\x20source\x20code:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>mkdir\x20-p\x20$GOPATH/src/github.com/user</b>\x0a</pre>\x0a\x0a\x0a<h3\x20id=\"Command\">Your\x20first\x20program</h3>\x0a\x0a<p>\x0aTo\x20compile\x20and\x20run\x20a\x20simple\x20program,\x20first\x20choose\x20a\x20package\x20path\x20(we'll\x20use\x0a<code>github.com/user/hello</code>)\x20and\x20create\x20a\x20corresponding\x20package\x20directory\x0ainside\x20your\x20workspace:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>mkdir\x20$GOPATH/src/github.com/user/hello</b>\x0a</pre>\x0a\x0a<p>\x0aNext,\x20create\x20a\x20file\x20named\x20<code>hello.go</code>\x20inside\x20that\x20directory,\x0acontaining\x20the\x20following\x20Go\x20code.\x0a</p>\x0a\x0a<pre>\x0apackage\x20main\x0a\x0aimport\x20\"fmt\"\x0a\x0afunc\x20main()\x20{\x0a\x09fmt.Println(\"Hello,\x20world.\")\x0a}\x0a</pre>\x0a\x0a<p>\x0aNow\x20you\x20can\x20build\x20and\x20install\x20that\x20program\x20with\x20the\x20<code>go</code>\x20tool:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>go\x20install\x20github.com/user/hello</b>\x0a</pre>\x0a\x0a<p>\x0aNote\x20that\x20you\x20can\x20run\x20this\x20command\x20from\x20anywhere\x20on\x20your\x20system.\x20The\x0a<code>go</code>\x20tool\x20finds\x20the\x20source\x20code\x20by\x20looking\x20for\x20the\x0a<code>github.com/user/hello</code>\x20package\x20inside\x20the\x20workspace\x20specified\x20by\x0a<code>GOPATH</code>.\x0a</p>\x0a\x0a<p>\x0aYou\x20can\x20also\x20omit\x20the\x20package\x20path\x20if\x20you\x20run\x20<code>go\x20install</code>\x20from\x20the\x0apackage\x20directory:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>cd\x20$GOPATH/src/github.com/user/hello</b>\x0a$\x20<b>go\x20install</b>\x0a</pre>\x0a\x0a<p>\x0aThis\x20command\x20builds\x20the\x20<code>hello</code>\x20command,\x20producing\x20an\x20executable\x0abinary.\x20It\x20then\x20installs\x20that\x20binary\x20to\x20the\x20workspace's\x20<code>bin</code>\x0adirectory\x20as\x20<code>hello</code>\x20(or,\x20under\x20Windows,\x20<code>hello.exe</code>).\x0aIn\x20our\x20example,\x20that\x20will\x20be\x20<code>$GOPATH/bin/hello</code>,\x20which\x20is\x0a<code>$HOME/go/bin/hello</code>.\x0a</p>\x0a\x0a<p>\x0aThe\x20<code>go</code>\x20tool\x20will\x20only\x20print\x20output\x20when\x20an\x20error\x20occurs,\x20so\x20if\x0athese\x20commands\x20produce\x20no\x20output\x20they\x20have\x20executed\x20successfully.\x0a</p>\x0a\x0a<p>\x0aYou\x20can\x20now\x20run\x20the\x20program\x20by\x20typing\x20its\x20full\x20path\x20at\x20the\x20command\x20line:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>$GOPATH/bin/hello</b>\x0aHello,\x20world.\x0a</pre>\x0a\x0a<p>\x0aOr,\x20as\x20you\x20have\x20added\x20<code>$GOPATH/bin</code>\x20to\x20your\x20<code>PATH</code>,\x0ajust\x20type\x20the\x20binary\x20name:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>hello</b>\x0aHello,\x20world.\x0a</pre>\x0a\x0a<p>\x0aIf\x20you're\x20using\x20a\x20source\x20control\x20system,\x20now\x20would\x20be\x20a\x20good\x20time\x20to\x20initialize\x0aa\x20repository,\x20add\x20the\x20files,\x20and\x20commit\x20your\x20first\x20change.\x20Again,\x20this\x20step\x20is\x0aoptional:\x20you\x20do\x20not\x20need\x20to\x20use\x20source\x20control\x20to\x20write\x20Go\x20code.\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>cd\x20$GOPATH/src/github.com/user/hello</b>\x0a$\x20<b>git\x20init</b>\x0aInitialized\x20empty\x20Git\x20repository\x20in\x20/home/user/go/src/github.com/user/hello/.git/\x0a$\x20<b>git\x20add\x20hello.go</b>\x0a$\x20<b>git\x20commit\x20-m\x20\"initial\x20commit\"</b>\x0a[master\x20(root-commit)\x200b4507d]\x20initial\x20commit\x0a\x201\x20file\x20changed,\x207\x20insertion(+)\x0a\x20create\x20mode\x20100644\x20hello.go\x0a</pre>\x0a\x0a<p>\x0aPushing\x20the\x20code\x20to\x20a\x20remote\x20repository\x20is\x20left\x20as\x20an\x20exercise\x20for\x20the\x20reader.\x0a</p>\x0a\x0a\x0a<h3\x20id=\"Library\">Your\x20first\x20library</h3>\x0a\x0a<p>\x0aLet's\x20write\x20a\x20library\x20and\x20use\x20it\x20from\x20the\x20<code>hello</code>\x20program.\x0a</p>\x0a\x0a<p>\x0aAgain,\x20the\x20first\x20step\x20is\x20to\x20choose\x20a\x20package\x20path\x20(we'll\x20use\x0a<code>github.com/user/stringutil</code>)\x20and\x20create\x20the\x20package\x20directory:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>mkdir\x20$GOPATH/src/github.com/user/stringutil</b>\x0a</pre>\x0a\x0a<p>\x0aNext,\x20create\x20a\x20file\x20named\x20<code>reverse.go</code>\x20in\x20that\x20directory\x20with\x20the\x0afollowing\x20contents.\x0a</p>\x0a\x0a<pre>\x0a//\x20Package\x20stringutil\x20contains\x20utility\x20functions\x20for\x20working\x20with\x20strings.\x0apackage\x20stringutil\x0a\x0a//\x20Reverse\x20returns\x20its\x20argument\x20string\x20reversed\x20rune-wise\x20left\x20to\x20right.\x0afunc\x20Reverse(s\x20string)\x20string\x20{\x0a\x09r\x20:=\x20[]rune(s)\x0a\x09for\x20i,\x20j\x20:=\x200,\x20len(r)-1;\x20i\x20<\x20len(r)/2;\x20i,\x20j\x20=\x20i+1,\x20j-1\x20{\x0a\x09\x09r[i],\x20r[j]\x20=\x20r[j],\x20r[i]\x0a\x09}\x0a\x09return\x20string(r)\x0a}\x0a</pre>\x0a\x0a<p>\x0aNow,\x20test\x20that\x20the\x20package\x20compiles\x20with\x20<code>go\x20build</code>:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>go\x20build\x20github.com/user/stringutil</b>\x0a</pre>\x0a\x0a<p>\x0aOr,\x20if\x20you\x20are\x20working\x20in\x20the\x20package's\x20source\x20directory,\x20just:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>go\x20build</b>\x0a</pre>\x0a\x0a<p>\x0aThis\x20won't\x20produce\x20an\x20output\x20file.\x0aInstead\x20it\x20saves\x20the\x20compiled\x20package\x20in\x20the\x20local\x20build\x20cache.\x0a</p>\x0a\x0a<p>\x0aAfter\x20confirming\x20that\x20the\x20<code>stringutil</code>\x20package\x20builds,\x0amodify\x20your\x20original\x20<code>hello.go</code>\x20(which\x20is\x20in\x0a<code>$GOPATH/src/github.com/user/hello</code>)\x20to\x20use\x20it:\x0a</p>\x0a\x0a<pre>\x0apackage\x20main\x0a\x0aimport\x20(\x0a\x09\"fmt\"\x0a\x0a\x09<b>\"github.com/user/stringutil\"</b>\x0a)\x0a\x0afunc\x20main()\x20{\x0a\x09fmt.Println(stringutil.Reverse(\"!oG\x20,olleH\"))\x0a}\x0a</pre>\x0a\x0a<p>\x0aInstall\x20the\x20<code>hello</code>\x20program:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>go\x20install\x20github.com/user/hello</b>\x0a</pre>\x0a\x0a<p>\x0aRunning\x20the\x20new\x20version\x20of\x20the\x20program,\x20you\x20should\x20see\x20a\x20new,\x20reversed\x20message:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>hello</b>\x0aHello,\x20Go!\x0a</pre>\x0a\x0a<p>\x0aAfter\x20the\x20steps\x20above,\x20your\x20workspace\x20should\x20look\x20like\x20this:\x0a</p>\x0a\x0a<pre>\x0abin/\x0a\x20\x20\x20\x20hello\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20command\x20executable\x0asrc/\x0a\x20\x20\x20\x20github.com/user/\x0a\x20\x20\x20\x20\x20\x20\x20\x20hello/\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20hello.go\x20\x20\x20\x20\x20\x20#\x20command\x20source\x0a\x20\x20\x20\x20\x20\x20\x20\x20stringutil/\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20reverse.go\x20\x20\x20\x20#\x20package\x20source\x0a</pre>\x0a\x0a<h3\x20id=\"PackageNames\">Package\x20names</h3>\x0a\x0a<p>\x0aThe\x20first\x20statement\x20in\x20a\x20Go\x20source\x20file\x20must\x20be\x0a</p>\x0a\x0a<pre>\x0apackage\x20<i>name</i>\x0a</pre>\x0a\x0a<p>\x0awhere\x20<code><i>name</i></code>\x20is\x20the\x20package's\x20default\x20name\x20for\x20imports.\x0a(All\x20files\x20in\x20a\x20package\x20must\x20use\x20the\x20same\x20<code><i>name</i></code>.)\x0a</p>\x0a\x0a<p>\x0aGo's\x20convention\x20is\x20that\x20the\x20package\x20name\x20is\x20the\x20last\x20element\x20of\x20the\x0aimport\x20path:\x20the\x20package\x20imported\x20as\x20\"<code>crypto/rot13</code>\"\x0ashould\x20be\x20named\x20<code>rot13</code>.\x0a</p>\x0a\x0a<p>\x0aExecutable\x20commands\x20must\x20always\x20use\x20<code>package\x20main</code>.\x0a</p>\x0a\x0a<p>\x0aThere\x20is\x20no\x20requirement\x20that\x20package\x20names\x20be\x20unique\x0aacross\x20all\x20packages\x20linked\x20into\x20a\x20single\x20binary,\x0aonly\x20that\x20the\x20import\x20paths\x20(their\x20full\x20file\x20names)\x20be\x20unique.\x0a</p>\x0a\x0a<p>\x0aSee\x20<a\x20href=\"/doc/effective_go.html#names\">Effective\x20Go</a>\x20to\x20learn\x20more\x20about\x0aGo's\x20naming\x20conventions.\x0a</p>\x0a\x0a\x0a<h2\x20id=\"Testing\">Testing</h2>\x0a\x0a<p>\x0aGo\x20has\x20a\x20lightweight\x20test\x20framework\x20composed\x20of\x20the\x20<code>go\x20test</code>\x0acommand\x20and\x20the\x20<code>testing</code>\x20package.\x0a</p>\x0a\x0a<p>\x0aYou\x20write\x20a\x20test\x20by\x20creating\x20a\x20file\x20with\x20a\x20name\x20ending\x20in\x20<code>_test.go</code>\x0athat\x20contains\x20functions\x20named\x20<code>TestXXX</code>\x20with\x20signature\x0a<code>func\x20(t\x20*testing.T)</code>.\x0aThe\x20test\x20framework\x20runs\x20each\x20such\x20function;\x0aif\x20the\x20function\x20calls\x20a\x20failure\x20function\x20such\x20as\x20<code>t.Error</code>\x20or\x0a<code>t.Fail</code>,\x20the\x20test\x20is\x20considered\x20to\x20have\x20failed.\x0a</p>\x0a\x0a<p>\x0aAdd\x20a\x20test\x20to\x20the\x20<code>stringutil</code>\x20package\x20by\x20creating\x20the\x20file\x0a<code>$GOPATH/src/github.com/user/stringutil/reverse_test.go</code>\x20containing\x0athe\x20following\x20Go\x20code.\x0a</p>\x0a\x0a<pre>\x0apackage\x20stringutil\x0a\x0aimport\x20\"testing\"\x0a\x0afunc\x20TestReverse(t\x20*testing.T)\x20{\x0a\x09cases\x20:=\x20[]struct\x20{\x0a\x09\x09in,\x20want\x20string\x0a\x09}{\x0a\x09\x09{\"Hello,\x20world\",\x20\"dlrow\x20,olleH\"},\x0a\x09\x09{\"Hello,\x20\xe4\xb8\x96\xe7\x95\x8c\",\x20\"\xe7\x95\x8c\xe4\xb8\x96\x20,olleH\"},\x0a\x09\x09{\"\",\x20\"\"},\x0a\x09}\x0a\x09for\x20_,\x20c\x20:=\x20range\x20cases\x20{\x0a\x09\x09got\x20:=\x20Reverse(c.in)\x0a\x09\x09if\x20got\x20!=\x20c.want\x20{\x0a\x09\x09\x09t.Errorf(\"Reverse(%q)\x20==\x20%q,\x20want\x20%q\",\x20c.in,\x20got,\x20c.want)\x0a\x09\x09}\x0a\x09}\x0a}\x0a</pre>\x0a\x0a<p>\x0aThen\x20run\x20the\x20test\x20with\x20<code>go\x20test</code>:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>go\x20test\x20github.com/user/stringutil</b>\x0aok\x20\x20\x09github.com/user/stringutil\x200.165s\x0a</pre>\x0a\x0a<p>\x0aAs\x20always,\x20if\x20you\x20are\x20running\x20the\x20<code>go</code>\x20tool\x20from\x20the\x20package\x0adirectory,\x20you\x20can\x20omit\x20the\x20package\x20path:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>go\x20test</b>\x0aok\x20\x20\x09github.com/user/stringutil\x200.165s\x0a</pre>\x0a\x0a<p>\x0aRun\x20<code><a\x20href=\"/cmd/go/#hdr-Test_packages\">go\x20help\x20test</a></code>\x20and\x20see\x20the\x0a<a\x20href=\"/pkg/testing/\">testing\x20package\x20documentation</a>\x20for\x20more\x20detail.\x0a</p>\x0a\x0a\x0a<h2\x20id=\"remote\">Remote\x20packages</h2>\x0a\x0a<p>\x0aAn\x20import\x20path\x20can\x20describe\x20how\x20to\x20obtain\x20the\x20package\x20source\x20code\x20using\x20a\x0arevision\x20control\x20system\x20such\x20as\x20Git\x20or\x20Mercurial.\x20The\x20<code>go</code>\x20tool\x20uses\x0athis\x20property\x20to\x20automatically\x20fetch\x20packages\x20from\x20remote\x20repositories.\x0aFor\x20instance,\x20the\x20examples\x20described\x20in\x20this\x20document\x20are\x20also\x20kept\x20in\x20a\x0aGit\x20repository\x20hosted\x20at\x20GitHub\x0a<code><a\x20href=\"https://github.com/golang/example\">github.com/golang/example</a></code>.\x0aIf\x20you\x20include\x20the\x20repository\x20URL\x20in\x20the\x20package's\x20import\x20path,\x0a<code>go\x20get</code>\x20will\x20fetch,\x20build,\x20and\x20install\x20it\x20automatically:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>go\x20get\x20github.com/golang/example/hello</b>\x0a$\x20<b>$GOPATH/bin/hello</b>\x0aHello,\x20Go\x20examples!\x0a</pre>\x0a\x0a<p>\x0aIf\x20the\x20specified\x20package\x20is\x20not\x20present\x20in\x20a\x20workspace,\x20<code>go\x20get</code>\x0awill\x20place\x20it\x20inside\x20the\x20first\x20workspace\x20specified\x20by\x20<code>GOPATH</code>.\x0a(If\x20the\x20package\x20does\x20already\x20exist,\x20<code>go\x20get</code>\x20skips\x20the\x20remote\x0afetch\x20and\x20behaves\x20the\x20same\x20as\x20<code>go\x20install</code>.)\x0a</p>\x0a\x0a<p>\x0aAfter\x20issuing\x20the\x20above\x20<code>go\x20get</code>\x20command,\x20the\x20workspace\x20directory\x0atree\x20should\x20now\x20look\x20like\x20this:\x0a</p>\x0a\x0a<pre>\x0abin/\x0a\x20\x20\x20\x20hello\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20command\x20executable\x0asrc/\x0a\x20\x20\x20\x20github.com/golang/example/\x0a\x09.git/\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20Git\x20repository\x20metadata\x0a\x20\x20\x20\x20\x20\x20\x20\x20hello/\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20hello.go\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20command\x20source\x0a\x20\x20\x20\x20\x20\x20\x20\x20stringutil/\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20reverse.go\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20package\x20source\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20reverse_test.go\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20test\x20source\x0a\x20\x20\x20\x20github.com/user/\x0a\x20\x20\x20\x20\x20\x20\x20\x20hello/\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20hello.go\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20command\x20source\x0a\x20\x20\x20\x20\x20\x20\x20\x20stringutil/\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20reverse.go\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20package\x20source\x0a\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20\x20reverse_test.go\x20\x20\x20\x20\x20\x20\x20\x20\x20#\x20test\x20source\x0a</pre>\x0a\x0a<p>\x0aThe\x20<code>hello</code>\x20command\x20hosted\x20at\x20GitHub\x20depends\x20on\x20the\x0a<code>stringutil</code>\x20package\x20within\x20the\x20same\x20repository.\x20The\x20imports\x20in\x0a<code>hello.go</code>\x20file\x20use\x20the\x20same\x20import\x20path\x20convention,\x20so\x20the\x0a<code>go\x20get</code>\x20command\x20is\x20able\x20to\x20locate\x20and\x20install\x20the\x20dependent\x0apackage,\x20too.\x0a</p>\x0a\x0a<pre>\x0aimport\x20\"github.com/golang/example/stringutil\"\x0a</pre>\x0a\x0a<p>\x0aThis\x20convention\x20is\x20the\x20easiest\x20way\x20to\x20make\x20your\x20Go\x20packages\x20available\x20for\x0aothers\x20to\x20use.\x0aThe\x20<a\x20href=\"//golang.org/wiki/Projects\">Go\x20Wiki</a>\x0aand\x20<a\x20href=\"//godoc.org/\">godoc.org</a>\x0aprovide\x20lists\x20of\x20external\x20Go\x20projects.\x0a</p>\x0a\x0a<p>\x0aFor\x20more\x20information\x20on\x20using\x20remote\x20repositories\x20with\x20the\x20<code>go</code>\x20tool,\x20see\x0a<code><a\x20href=\"/cmd/go/#hdr-Remote_import_paths\">go\x20help\x20importpath</a></code>.\x0a</p>\x0a\x0a\x0a<h2\x20id=\"next\">What's\x20next</h2>\x0a\x0a<p>\x0aSubscribe\x20to\x20the\x0a<a\x20href=\"//groups.google.com/group/golang-announce\">golang-announce</a>\x0amailing\x20list\x20to\x20be\x20notified\x20when\x20a\x20new\x20stable\x20version\x20of\x20Go\x20is\x20released.\x0a</p>\x0a\x0a<p>\x0aSee\x20<a\x20href=\"/doc/effective_go.html\">Effective\x20Go</a>\x20for\x20tips\x20on\x20writing\x0aclear,\x20idiomatic\x20Go\x20code.\x0a</p>\x0a\x0a<p>\x0aTake\x20<a\x20href=\"//tour.golang.org/\">A\x20Tour\x20of\x20Go</a>\x20to\x20learn\x20the\x20language\x0aproper.\x0a</p>\x0a\x0a<p>\x0aVisit\x20the\x20<a\x20href=\"/doc/#articles\">documentation\x20page</a>\x20for\x20a\x20set\x20of\x20in-depth\x0aarticles\x20about\x20the\x20Go\x20language\x20and\x20its\x20libraries\x20and\x20tools.\x0a</p>\x0a\x0a\x0a<h2\x20id=\"help\">Getting\x20help</h2>\x0a\x0a<p>\x0aFor\x20real-time\x20help,\x20ask\x20the\x20helpful\x20gophers\x20in\x20<code>#go-nuts</code>\x20on\x20the\x0a<a\x20href=\"https://freenode.net/\">Freenode</a>\x20IRC\x20server.\x0a</p>\x0a\x0a<p>\x0aThe\x20official\x20mailing\x20list\x20for\x20discussion\x20of\x20the\x20Go\x20language\x20is\x0a<a\x20href=\"//groups.google.com/group/golang-nuts\">Go\x20Nuts</a>.\x0a</p>\x0a\x0a<p>\x0aReport\x20bugs\x20using\x20the\x0a<a\x20href=\"//golang.org/issue\">Go\x20issue\x20tracker</a>.\x0a</p>\x0a",
+ "doc/code.html": "<!--{\x0a\x09\"Title\":\x20\"How\x20to\x20Write\x20Go\x20Code\",\x0a\x09\"Template\":\x20true\x0a}-->\x0a\x0a<h2\x20id=\"Introduction\">Introduction</h2>\x0a\x0a<p>\x0aThis\x20document\x20demonstrates\x20the\x20development\x20of\x20a\x20simple\x20Go\x20package\x20inside\x20a\x0amodule\x20and\x20introduces\x20the\x20<a\x20href=\"/cmd/go/\">go\x20tool</a>,\x20the\x20standard\x20way\x20to\x0afetch,\x20build,\x20and\x20install\x20Go\x20modules,\x20packages,\x20and\x20commands.\x0a</p>\x0a\x0a<p>\x0aNote:\x20This\x20document\x20assumes\x20that\x20you\x20are\x20using\x20Go\x201.13\x20or\x20later\x20and\x20the\x0a<code>GO111MODULE</code>\x20environment\x20variable\x20is\x20not\x20set.\x20If\x20you\x20are\x20looking\x20for\x0athe\x20older,\x20pre-modules\x20version\x20of\x20this\x20document,\x20it\x20is\x20archived\x0a<a\x20href=\"gopath_code.html\">here</a>.\x0a</p>\x0a\x0a<h2\x20id=\"Organization\">Code\x20organization</h2>\x0a\x0a<p>\x0aGo\x20programs\x20are\x20organized\x20into\x20packages.\x20A\x20<dfn>package</dfn>\x20is\x20a\x20collection\x0aof\x20source\x20files\x20in\x20the\x20same\x20directory\x20that\x20are\x20compiled\x20together.\x20Functions,\x0atypes,\x20variables,\x20and\x20constants\x20defined\x20in\x20one\x20source\x20file\x20are\x20visible\x20to\x20all\x0aother\x20source\x20files\x20within\x20the\x20same\x20package.\x0a</p>\x0a\x0a<p>\x0aA\x20repository\x20contains\x20one\x20or\x20more\x20modules.\x20A\x20<dfn>module</dfn>\x20is\x20a\x20collection\x0aof\x20related\x20Go\x20packages\x20that\x20are\x20released\x20together.\x20A\x20Go\x20repository\x20typically\x0acontains\x20only\x20one\x20module,\x20located\x20at\x20the\x20root\x20of\x20the\x20repository.\x20A\x20file\x20named\x0a<code>go.mod</code>\x20there\x20declares\x20the\x20<dfn>module\x20path</dfn>:\x20the\x20import\x20path\x0aprefix\x20for\x20all\x20packages\x20within\x20the\x20module.\x20The\x20module\x20contains\x20the\x20packages\x20in\x0athe\x20directory\x20containing\x20its\x20<code>go.mod</code>\x20file\x20as\x20well\x20as\x20subdirectories\x0aof\x20that\x20directory,\x20up\x20to\x20the\x20next\x20subdirectory\x20containing\x20another\x0a<code>go.mod</code>\x20file\x20(if\x20any).\x0a</p>\x0a\x0a<p>\x0aNote\x20that\x20you\x20don't\x20need\x20to\x20publish\x20your\x20code\x20to\x20a\x20remote\x20repository\x20before\x20you\x0acan\x20build\x20it.\x20A\x20module\x20can\x20be\x20defined\x20locally\x20without\x20belonging\x20to\x20a\x20repository.\x0aHowever,\x20it's\x20a\x20good\x20habit\x20to\x20organize\x20your\x20code\x20as\x20if\x20you\x20will\x20publish\x20it\x0asomeday.\x0a</p>\x0a\x0a<p>\x0aEach\x20module's\x20path\x20not\x20only\x20serves\x20as\x20an\x20import\x20path\x20prefix\x20for\x20its\x20packages,\x0abut\x20also\x20indicates\x20where\x20the\x20<code>go</code>\x20command\x20should\x20look\x20to\x20download\x20it.\x0aFor\x20example,\x20in\x20order\x20to\x20download\x20the\x20module\x20<code>golang.org/x/tools</code>,\x0athe\x20<code>go</code>\x20command\x20would\x20consult\x20the\x20repository\x20indicated\x20by\x0a<code>https://golang.org/x/tools</code>\x20(described\x20more\x20<a\x20href=\"https://golang.org/cmd/go/#hdr-Relative_import_paths\">here</a>).\x0a</p>\x0a\x0a<p>\x0aAn\x20<dfn>import\x20path</dfn>\x20is\x20a\x20string\x20used\x20to\x20import\x20a\x20package.\x20A\x20package's\x0aimport\x20path\x20is\x20its\x20module\x20path\x20joined\x20with\x20its\x20subdirectory\x20within\x20the\x20module.\x0aFor\x20example,\x20the\x20module\x20<code>github.com/google/go-cmp</code>\x20contains\x20a\x20package\x0ain\x20the\x20directory\x20<code>cmp/</code>.\x20That\x20package's\x20import\x20path\x20is\x0a<code>github.com/google/go-cmp/cmp</code>.\x20Packages\x20in\x20the\x20standard\x20library\x20do\x0anot\x20have\x20a\x20module\x20path\x20prefix.\x0a</p>\x0a\x0a<h2\x20id=\"Command\">Your\x20first\x20program</h2>\x0a\x0a<p>\x0aTo\x20compile\x20and\x20run\x20a\x20simple\x20program,\x20first\x20choose\x20a\x20module\x20path\x20(we'll\x20use\x0a<code>github.com/user/hello</code>)\x20and\x20create\x20a\x20<code>go.mod</code>\x20file\x20that\x0adeclares\x20it:\x0a</p>\x0a\x0a<pre>\x0a$\x20mkdir\x20hello\x20#\x20Alternatively,\x20clone\x20it\x20if\x20it\x20already\x20exists\x20in\x20version\x20control.\x0a$\x20cd\x20hello\x0a$\x20<b>go\x20mod\x20init\x20github.com/user/hello</b>\x0ago:\x20creating\x20new\x20go.mod:\x20module\x20github.com/user/hello\x0a$\x20cat\x20go.mod\x0amodule\x20github.com/user/hello\x0a\x0ago\x201.13\x0a$\x0a</pre>\x0a\x0a<p>\x0aThe\x20first\x20statement\x20in\x20a\x20Go\x20source\x20file\x20must\x20be\x0a<code>package\x20<dfn>name</dfn></code>.\x20Executable\x20commands\x20must\x20always\x20use\x0a<code>package\x20main</code>.\x0a</p>\x0a\x0a<p>\x0aNext,\x20create\x20a\x20file\x20named\x20<code>hello.go</code>\x20inside\x20that\x20directory\x20containing\x0athe\x20following\x20Go\x20code:\x0a</p>\x0a\x0a<pre>\x0apackage\x20main\x0a\x0aimport\x20\"fmt\"\x0a\x0afunc\x20main()\x20{\x0a\x09fmt.Println(\"Hello,\x20world.\")\x0a}\x0a</pre>\x0a\x0a<p>\x0aNow\x20you\x20can\x20build\x20and\x20install\x20that\x20program\x20with\x20the\x20<code>go</code>\x20tool:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>go\x20install\x20github.com/user/hello</b>\x0a$\x0a</pre>\x0a\x0a<p>\x0aThis\x20command\x20builds\x20the\x20<code>hello</code>\x20command,\x20producing\x20an\x20executable\x0abinary.\x20It\x20then\x20installs\x20that\x20binary\x20as\x20<code>$HOME/go/bin/hello</code>\x20(or,\x0aunder\x20Windows,\x20<code>%USERPROFILE%\\go\\bin\\hello.exe</code>).\x20You\x20can\x20change\x20the\x0ainstall\x20directory\x20by\x20setting\x20the\x20<code>GOBIN</code>\x0a<a\x20href=\"/cmd/go/#hdr-Environment_variables\">environment\x20variable</a>.\x0a</p>\x0a\x0a<pre>\x0a$\x20go\x20env\x20-w\x20GOBIN=/somewhere/else/bin\x0a$\x0a</pre>\x0a\x0a<p>\x0aCommands\x20like\x20<code>go\x20install</code>\x20apply\x20within\x20the\x20context\x20of\x20the\x20module\x0acontaining\x20the\x20current\x20working\x20directory.\x20If\x20the\x20working\x20directory\x20is\x20not\x20within\x0athe\x20<code>github.com/user/hello</code>\x20module,\x20<code>go\x20install</code>\x20may\x20fail.\x0a</p>\x0a\x0a<p>\x0aFor\x20convenience,\x20<code>go</code>\x20commands\x20accept\x20paths\x20relative\x0ato\x20the\x20working\x20directory,\x20and\x20default\x20to\x20the\x20package\x20in\x20the\x0acurrent\x20working\x20directory\x20if\x20no\x20other\x20path\x20is\x20given.\x0aSo\x20in\x20our\x20working\x20directory,\x20the\x20following\x20commands\x20are\x20all\x20equivalent:\x0a</p>\x0a\x0a<pre>\x0a$\x20go\x20install\x20github.com/user/hello\x0a</pre>\x0a\x0a<pre>\x0a$\x20go\x20install\x20.\x0a</pre>\x0a\x0a<pre>\x0a$\x20go\x20install\x0a</pre>\x0a\x0a<p>\x0aNext,\x20let's\x20run\x20the\x20program\x20to\x20ensure\x20it\x20works.\x20For\x20added\x20convenience,\x20we'll\x0aadd\x20the\x20install\x20directory\x20to\x20our\x20<code>PATH</code>\x20to\x20make\x20running\x20binaries\x0aeasy:\x0a</p>\x0a\x0a<pre>\x0a#\x20Windows\x20users\x20should\x20consult\x20https://github.com/golang/go/wiki/SettingGOPATH\x0a#\x20for\x20setting\x20%PATH%.\x0a$\x20<b>export\x20PATH=$PATH:$(go\x20env\x20GOBIN)</b>\x0a$\x20<b>hello</b>\x0aHello,\x20world.\x0a$\x0a</pre>\x0a\x0a<p>\x0aIf\x20you're\x20using\x20a\x20source\x20control\x20system,\x20now\x20would\x20be\x20a\x20good\x20time\x20to\x20initialize\x0aa\x20repository,\x20add\x20the\x20files,\x20and\x20commit\x20your\x20first\x20change.\x20Again,\x20this\x20step\x20is\x0aoptional:\x20you\x20do\x20not\x20need\x20to\x20use\x20source\x20control\x20to\x20write\x20Go\x20code.\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>git\x20init</b>\x0aInitialized\x20empty\x20Git\x20repository\x20in\x20/home/user/hello/.git/\x0a$\x20<b>git\x20add\x20go.mod\x20hello.go</b>\x0a$\x20<b>git\x20commit\x20-m\x20\"initial\x20commit\"</b>\x0a[master\x20(root-commit)\x200b4507d]\x20initial\x20commit\x0a\x201\x20file\x20changed,\x207\x20insertion(+)\x0a\x20create\x20mode\x20100644\x20go.mod\x20hello.go\x0a$\x0a</pre>\x0a\x0a<h3\x20id=\"ImportingLocal\">Importing\x20packages\x20from\x20your\x20module</h3>\x0a\x0a<p>\x0aLet's\x20write\x20a\x20<code>morestrings</code>\x20package\x20and\x20use\x20it\x20from\x20the\x20<code>hello</code>\x20program.\x0aFirst,\x20create\x20a\x20directory\x20for\x20the\x20package\x20named\x0a<code>$HOME/hello/morestrings</code>,\x20and\x20then\x20a\x20file\x20named\x0a<code>reverse.go</code>\x20in\x20that\x20directory\x20with\x20the\x20following\x20contents:\x0a</p>\x0a\x0a<pre>\x0a//\x20Package\x20morestrings\x20implements\x20additional\x20functions\x20to\x20manipulate\x20UTF-8\x0a//\x20encoded\x20strings,\x20beyond\x20what\x20is\x20provided\x20in\x20the\x20standard\x20\"strings\"\x20package.\x0apackage\x20morestrings\x0a\x0a//\x20ReverseRunes\x20returns\x20its\x20argument\x20string\x20reversed\x20rune-wise\x20left\x20to\x20right.\x0afunc\x20ReverseRunes(s\x20string)\x20string\x20{\x0a\x09r\x20:=\x20[]rune(s)\x0a\x09for\x20i,\x20j\x20:=\x200,\x20len(r)-1;\x20i\x20<\x20len(r)/2;\x20i,\x20j\x20=\x20i+1,\x20j-1\x20{\x0a\x09\x09r[i],\x20r[j]\x20=\x20r[j],\x20r[i]\x0a\x09}\x0a\x09return\x20string(r)\x0a}\x0a</pre>\x0a\x0a<p>\x0aBecause\x20our\x20<code>ReverseRunes</code>\x20function\x20begins\x20with\x20an\x20upper-case\x0aletter,\x20it\x20is\x20<a\x20href=\"/ref/spec#Exported_identifiers\"><dfn>exported</dfn></a>,\x0aand\x20can\x20be\x20used\x20in\x20other\x20packages\x20that\x20import\x20our\x20<code>morestrings</code>\x0apackage.\x0a</p>\x0a\x0a<p>\x0aLet's\x20test\x20that\x20the\x20package\x20compiles\x20with\x20<code>go\x20build</code>:\x0a</p>\x0a\x0a<pre>\x0a$\x20cd\x20$HOME/hello/morestrings\x0a$\x20<b>go\x20build</b>\x0a$\x0a</pre>\x0a\x0a<p>\x0aThis\x20won't\x20produce\x20an\x20output\x20file.\x20Instead\x20it\x20saves\x20the\x20compiled\x20package\x20in\x20the\x0alocal\x20build\x20cache.\x0a</p>\x0a\x0a<p>\x0aAfter\x20confirming\x20that\x20the\x20<code>morestrings</code>\x20package\x20builds,\x20let's\x20use\x20it\x0afrom\x20the\x20<code>hello</code>\x20program.\x20To\x20do\x20so,\x20modify\x20your\x20original\x0a<code>$HOME/hello/hello.go</code>\x20to\x20use\x20the\x20morestrings\x20package:\x0a</p>\x0a\x0a<pre>\x0apackage\x20main\x0a\x0aimport\x20(\x0a\x09\"fmt\"\x0a\x0a\x09<b>\"github.com/user/hello/morestrings\"</b>\x0a)\x0a\x0afunc\x20main()\x20{\x0a\x09fmt.Println(morestrings.ReverseRunes(\"!oG\x20,olleH\"))\x0a}\x0a</pre>\x0a\x0a<p>\x0aInstall\x20the\x20<code>hello</code>\x20program:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>go\x20install\x20github.com/user/hello</b>\x0a</pre>\x0a\x0a<p>\x0aRunning\x20the\x20new\x20version\x20of\x20the\x20program,\x20you\x20should\x20see\x20a\x20new,\x20reversed\x20message:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>hello</b>\x0aHello,\x20Go!\x0a</pre>\x0a\x0a<h3\x20id=\"ImportingRemote\">Importing\x20packages\x20from\x20remote\x20modules</h3>\x0a\x0a<p>\x0aAn\x20import\x20path\x20can\x20describe\x20how\x20to\x20obtain\x20the\x20package\x20source\x20code\x20using\x20a\x0arevision\x20control\x20system\x20such\x20as\x20Git\x20or\x20Mercurial.\x20The\x20<code>go</code>\x20tool\x20uses\x0athis\x20property\x20to\x20automatically\x20fetch\x20packages\x20from\x20remote\x20repositories.\x0aFor\x20instance,\x20to\x20use\x20<code>github.com/google/go-cmp/cmp</code>\x20in\x20your\x20program:\x0a</p>\x0a\x0a<pre>\x0apackage\x20main\x0a\x0aimport\x20(\x0a\x09\"fmt\"\x0a\x0a\x09\"github.com/user/hello/morestrings\"\x0a\x09\"github.com/google/go-cmp/cmp\"\x0a)\x0a\x0afunc\x20main()\x20{\x0a\x09fmt.Println(morestrings.ReverseRunes(\"!oG\x20,olleH\"))\x0a\x09fmt.Println(cmp.Diff(\"Hello\x20World\",\x20\"Hello\x20Go\"))\x0a}\x0a</pre>\x0a\x0a<p>\x0aWhen\x20you\x20run\x20commands\x20like\x20<code>go\x20install</code>,\x20<code>go\x20build</code>,\x20or\x0a<code>go\x20run</code>,\x20the\x20remote\x20module\x20will\x20automatically\x20be\x20added\x20to\x20your\x0a<code>go.mod</code>\x20file\x20(and\x20downloaded):\x0a\x0a<pre>\x0a$\x20go\x20install\x20github.com/user/hello\x0a$\x20hello\x0aHello,\x20Go!\x0a\xc2\xa0\xc2\xa0string(\x0a-\xc2\xa0\x09\"Hello\x20World\",\x0a+\xc2\xa0\x09\"Hello\x20Go\",\x0a\xc2\xa0\xc2\xa0)\x0a$\x20cat\x20go.mod\x0amodule\x20github.com/user/hello\x0a\x0ago\x201.13\x0a\x0a<b>require\x20github.com/google/go-cmp\x20v0.3.1</b>\x0a$\x0a</pre>\x0a\x0a<p>\x0aA\x20module's\x20path\x20doesn't\x20have\x20to\x20match\x20the\x20URL\x20for\x20its\x20repository,\x20but\x20this\x0aconvention\x20is\x20the\x20easiest\x20way\x20to\x20make\x20your\x20Go\x20packages\x20available\x20for\x20others\x20to\x0ause.\x20For\x20more\x20information\x20on\x20using\x20remote\x20modules\x20with\x20the\x20<code>go</code>\x20tool,\x20see\x0a<code><a\x20href=\"/cmd/go/#hdr-Remote_import_paths\">go\x20help\x20importpath</a></code>\x0aand\x20<a\x20href=\"https://blog.golang.org/using-go-modules\">Using\x20Go\x20Modules</a>.\x0a</p>\x0a\x0a<h2\x20id=\"Testing\">Testing</h2>\x0a\x0a<p>\x0aGo\x20has\x20a\x20lightweight\x20test\x20framework\x20composed\x20of\x20the\x20<code>go\x20test</code>\x0acommand\x20and\x20the\x20<code>testing</code>\x20package.\x0a</p>\x0a\x0a<p>\x0aYou\x20write\x20a\x20test\x20by\x20creating\x20a\x20file\x20with\x20a\x20name\x20ending\x20in\x20<code>_test.go</code>\x0athat\x20contains\x20functions\x20named\x20<code>TestXXX</code>\x20with\x20signature\x0a<code>func\x20(t\x20*testing.T)</code>.\x0aThe\x20test\x20framework\x20runs\x20each\x20such\x20function;\x0aif\x20the\x20function\x20calls\x20a\x20failure\x20function\x20such\x20as\x20<code>t.Error</code>\x20or\x0a<code>t.Fail</code>,\x20the\x20test\x20is\x20considered\x20to\x20have\x20failed.\x0a</p>\x0a\x0a<p>\x0aAdd\x20a\x20test\x20to\x20the\x20<code>morestrings</code>\x20package\x20by\x20creating\x20the\x20file\x0a<code>$HOME/hello/morestrings/reverse_test.go</code>\x20containing\x0athe\x20following\x20Go\x20code.\x0a</p>\x0a\x0a<pre>\x0apackage\x20morestrings\x0a\x0aimport\x20\"testing\"\x0a\x0afunc\x20TestReverseRunes(t\x20*testing.T)\x20{\x0a\x09cases\x20:=\x20[]struct\x20{\x0a\x09\x09in,\x20want\x20string\x0a\x09}{\x0a\x09\x09{\"Hello,\x20world\",\x20\"dlrow\x20,olleH\"},\x0a\x09\x09{\"Hello,\x20\xe4\xb8\x96\xe7\x95\x8c\",\x20\"\xe7\x95\x8c\xe4\xb8\x96\x20,olleH\"},\x0a\x09\x09{\"\",\x20\"\"},\x0a\x09}\x0a\x09for\x20_,\x20c\x20:=\x20range\x20cases\x20{\x0a\x09\x09got\x20:=\x20ReverseRunes(c.in)\x0a\x09\x09if\x20got\x20!=\x20c.want\x20{\x0a\x09\x09\x09t.Errorf(\"ReverseRunes(%q)\x20==\x20%q,\x20want\x20%q\",\x20c.in,\x20got,\x20c.want)\x0a\x09\x09}\x0a\x09}\x0a}\x0a</pre>\x0a\x0a<p>\x0aThen\x20run\x20the\x20test\x20with\x20<code>go\x20test</code>:\x0a</p>\x0a\x0a<pre>\x0a$\x20<b>go\x20test</b>\x0aPASS\x0aok\x20\x20\x09github.com/user/morestrings\x200.165s\x0a$\x0a</pre>\x0a\x0a<p>\x0aRun\x20<code><a\x20href=\"/cmd/go/#hdr-Test_packages\">go\x20help\x20test</a></code>\x20and\x20see\x20the\x0a<a\x20href=\"/pkg/testing/\">testing\x20package\x20documentation</a>\x20for\x20more\x20detail.\x0a</p>\x0a\x0a<h2\x20id=\"next\">What's\x20next</h2>\x0a\x0a<p>\x0aSubscribe\x20to\x20the\x0a<a\x20href=\"//groups.google.com/group/golang-announce\">golang-announce</a>\x0amailing\x20list\x20to\x20be\x20notified\x20when\x20a\x20new\x20stable\x20version\x20of\x20Go\x20is\x20released.\x0a</p>\x0a\x0a<p>\x0aSee\x20<a\x20href=\"/doc/effective_go.html\">Effective\x20Go</a>\x20for\x20tips\x20on\x20writing\x0aclear,\x20idiomatic\x20Go\x20code.\x0a</p>\x0a\x0a<p>\x0aTake\x20{{if\x20$.GoogleCN}}\x0aA\x20Tour\x20of\x20Go\x0a{{else}}\x0a<a\x20href=\"//tour.golang.org/\">A\x20Tour\x20of\x20Go</a>\x0a{{end}}\x20to\x20learn\x20the\x20language\x0aproper.\x0a</p>\x0a\x0a<p>\x0aVisit\x20the\x20<a\x20href=\"/doc/#articles\">documentation\x20page</a>\x20for\x20a\x20set\x20of\x20in-depth\x0aarticles\x20about\x20the\x20Go\x20language\x20and\x20its\x20libraries\x20and\x20tools.\x0a</p>\x0a\x0a<h2\x20id=\"help\">Getting\x20help</h2>\x0a\x0a<p>\x0aFor\x20real-time\x20help,\x20ask\x20the\x20helpful\x20gophers\x20in\x20the\x20community-run\x0a<a\x20href=\"https://gophers.slack.com/messages/general/\">gophers\x20Slack\x20server</a>\x0a(grab\x20an\x20invite\x20<a\x20href=\"https://invite.slack.golangbridge.org/\">here</a>).\x0a</p>\x0a\x0a<p>\x0aThe\x20official\x20mailing\x20list\x20for\x20discussion\x20of\x20the\x20Go\x20language\x20is\x0a<a\x20href=\"//groups.google.com/group/golang-nuts\">Go\x20Nuts</a>.\x0a</p>\x0a\x0a<p>\x0aReport\x20bugs\x20using\x20the\x0a<a\x20href=\"//golang.org/issue\">Go\x20issue\x20tracker</a>.\x0a</p>\x0a",
"doc/conduct.html": "<!--{\x0a\x09\"Title\":\x20\"Go\x20Community\x20Code\x20of\x20Conduct\",\x0a\x09\"Path\":\x20\x20\"/conduct\",\x0a\x09\"Template\":\x20true\x0a}-->\x0a\x0a<style>\x0aul\x20{\x0a\x09max-width:\x20800px;\x0a}\x0aul\x20ul\x20{\x0a\x09margin:\x200\x200\x205px;\x0a}\x0a</style>\x0a\x0a<h2\x20id=\"about\">About</h2>\x0a\x0a<p>\x0aOnline\x20communities\x20include\x20people\x20from\x20many\x20different\x20backgrounds.\x0aThe\x20Go\x20contributors\x20are\x20committed\x20to\x20providing\x20a\x20friendly,\x20safe\x20and\x20welcoming\x0aenvironment\x20for\x20all,\x20regardless\x20of\x20gender\x20identity\x20and\x20expression,\x20sexual\x20orientation,\x0adisabilities,\x20neurodiversity,\x20physical\x20appearance,\x20body\x20size,\x20ethnicity,\x20nationality,\x0arace,\x20age,\x20religion,\x20or\x20similar\x20personal\x20characteristics.\x0a</p>\x0a\x0a<p>\x0aThe\x20first\x20goal\x20of\x20the\x20Code\x20of\x20Conduct\x20is\x20to\x20specify\x20a\x20baseline\x20standard\x0aof\x20behavior\x20so\x20that\x20people\x20with\x20different\x20social\x20values\x20and\x20communication\x0astyles\x20can\x20talk\x20about\x20Go\x20effectively,\x20productively,\x20and\x20respectfully.\x0a</p>\x0a\x0a<p>\x0aThe\x20second\x20goal\x20is\x20to\x20provide\x20a\x20mechanism\x20for\x20resolving\x20conflicts\x20in\x20the\x0acommunity\x20when\x20they\x20arise.\x0a</p>\x0a\x0a<p>\x0aThe\x20third\x20goal\x20of\x20the\x20Code\x20of\x20Conduct\x20is\x20to\x20make\x20our\x20community\x20welcoming\x20to\x0apeople\x20from\x20different\x20backgrounds.\x0aDiversity\x20is\x20critical\x20to\x20the\x20project;\x20for\x20Go\x20to\x20be\x20successful,\x20it\x20needs\x0acontributors\x20and\x20users\x20from\x20all\x20backgrounds.\x0a(See\x20<a\x20href=\"https://blog.golang.org/open-source\">Go,\x20Open\x20Source,\x20Community</a>.)\x0a</p>\x0a\x0a<p>\x0aWe\x20believe\x20that\x20healthy\x20debate\x20and\x20disagreement\x20are\x20essential\x20to\x20a\x20healthy\x20project\x20and\x20community.\x0aHowever,\x20it\x20is\x20never\x20ok\x20to\x20be\x20disrespectful.\x0aWe\x20value\x20diverse\x20opinions,\x20but\x20we\x20value\x20respectful\x20behavior\x20more.\x0a</p>\x0a\x0a<h2\x20id=\"values\">Gopher\x20values</h2>\x0a\x0a<p>\x0aThese\x20are\x20the\x20values\x20to\x20which\x20people\x20in\x20the\x20Go\x20community\x20(\xe2\x80\x9cGophers\xe2\x80\x9d)\x20should\x20aspire.\x0a</p>\x0a\x0a<ul>\x0a<li>Be\x20friendly\x20and\x20welcoming\x0a<li>Be\x20patient\x0a\x20\x20\x20\x20<ul>\x0a\x20\x20\x20\x20<li>Remember\x20that\x20people\x20have\x20varying\x20communication\x20styles\x20and\x20that\x20not\x0a\x20\x20\x20\x20\x20\x20\x20\x20everyone\x20is\x20using\x20their\x20native\x20language.\x0a\x20\x20\x20\x20\x20\x20\x20\x20(Meaning\x20and\x20tone\x20can\x20be\x20lost\x20in\x20translation.)\x0a\x20\x20\x20\x20</ul>\x0a<li>Be\x20thoughtful\x0a\x20\x20\x20\x20<ul>\x0a\x20\x20\x20\x20<li>Productive\x20communication\x20requires\x20effort.\x0a\x20\x20\x20\x20\x20\x20\x20\x20Think\x20about\x20how\x20your\x20words\x20will\x20be\x20interpreted.\x0a\x20\x20\x20\x20<li>Remember\x20that\x20sometimes\x20it\x20is\x20best\x20to\x20refrain\x20entirely\x20from\x20commenting.\x0a\x20\x20\x20\x20</ul>\x0a<li>Be\x20respectful\x0a\x20\x20\x20\x20<ul>\x0a\x20\x20\x20\x20<li>In\x20particular,\x20respect\x20differences\x20of\x20opinion.\x0a\x20\x20\x20\x20</ul>\x0a<li>Be\x20charitable\x0a\x20\x20\x20\x20<ul>\x0a\x20\x20\x20\x20<li>Interpret\x20the\x20arguments\x20of\x20others\x20in\x20good\x20faith,\x20do\x20not\x20seek\x20to\x20disagree.\x0a\x20\x20\x20\x20<li>When\x20we\x20do\x20disagree,\x20try\x20to\x20understand\x20why.\x0a\x20\x20\x20\x20</ul>\x0a<li>Avoid\x20destructive\x20behavior:\x0a\x20\x20\x20\x20<ul>\x0a\x20\x20\x20\x20<li>Derailing:\x20stay\x20on\x20topic;\x20if\x20you\x20want\x20to\x20talk\x20about\x20something\x20else,\x0a\x20\x20\x20\x20\x20\x20\x20\x20start\x20a\x20new\x20conversation.\x0a\x20\x20\x20\x20<li>Unconstructive\x20criticism:\x20don't\x20merely\x20decry\x20the\x20current\x20state\x20of\x20affairs;\x0a\x20\x20\x20\x20\x20\x20\x20\x20offer\xe2\x80\x94or\x20at\x20least\x20solicit\xe2\x80\x94suggestions\x20as\x20to\x20how\x20things\x20may\x20be\x20improved.\x0a\x20\x20\x20\x20<li>Snarking\x20(pithy,\x20unproductive,\x20sniping\x20comments)\x0a\x20\x20\x20\x20<li>Discussing\x20potentially\x20offensive\x20or\x20sensitive\x20issues;\x0a\x20\x20\x20\x20\x20\x20\x20\x20this\x20all\x20too\x20often\x20leads\x20to\x20unnecessary\x20conflict.\x0a\x20\x20\x20\x20<li>Microaggressions:\x20brief\x20and\x20commonplace\x20verbal,\x20behavioral\x20and\x0a\x20\x20\x20\x20\x20\x20\x20\x20environmental\x20indignities\x20that\x20communicate\x20hostile,\x20derogatory\x20or\x20negative\x0a\x20\x20\x20\x20\x20\x20\x20\x20slights\x20and\x20insults\x20to\x20a\x20person\x20or\x20group.\x0a\x20\x20\x20\x20</ul>\x0a</ul>\x0a\x0a<p>\x0aPeople\x20are\x20complicated.\x0aYou\x20should\x20expect\x20to\x20be\x20misunderstood\x20and\x20to\x20misunderstand\x20others;\x0awhen\x20this\x20inevitably\x20occurs,\x20resist\x20the\x20urge\x20to\x20be\x20defensive\x20or\x20assign\x20blame.\x0aTry\x20not\x20to\x20take\x20offense\x20where\x20no\x20offense\x20was\x20intended.\x0aGive\x20people\x20the\x20benefit\x20of\x20the\x20doubt.\x0aEven\x20if\x20the\x20intent\x20was\x20to\x20provoke,\x20do\x20not\x20rise\x20to\x20it.\x0aIt\x20is\x20the\x20responsibility\x20of\x20<i>all\x20parties</i>\x20to\x20de-escalate\x20conflict\x20when\x20it\x20arises.\x0a</p>\x0a\x0a<h2\x20id=\"code\">Code\x20of\x20Conduct</h2>\x0a\x0a<h3\x20id=\"our-pledge\">Our\x20Pledge</h3>\x0a\x0a<p>In\x20the\x20interest\x20of\x20fostering\x20an\x20open\x20and\x20welcoming\x20environment,\x20we\x20as\x0acontributors\x20and\x20maintainers\x20pledge\x20to\x20making\x20participation\x20in\x20our\x20project\x20and\x0aour\x20community\x20a\x20harassment-free\x20experience\x20for\x20everyone,\x20regardless\x20of\x20age,\x20body\x0asize,\x20disability,\x20ethnicity,\x20gender\x20identity\x20and\x20expression,\x20level\x20of\x0aexperience,\x20education,\x20socio-economic\x20status,\x20nationality,\x20personal\x20appearance,\x0arace,\x20religion,\x20or\x20sexual\x20identity\x20and\x20orientation.</p>\x0a\x0a<h3\x20id=\"our-standards\">Our\x20Standards</h3>\x0a\x0a<p>Examples\x20of\x20behavior\x20that\x20contributes\x20to\x20creating\x20a\x20positive\x20environment\x0ainclude:</p>\x0a\x0a<ul>\x0a<li>Using\x20welcoming\x20and\x20inclusive\x20language</li>\x0a<li>Being\x20respectful\x20of\x20differing\x20viewpoints\x20and\x20experiences</li>\x0a<li>Gracefully\x20accepting\x20constructive\x20criticism</li>\x0a<li>Focusing\x20on\x20what\x20is\x20best\x20for\x20the\x20community</li>\x0a<li>Showing\x20empathy\x20towards\x20other\x20community\x20members</li>\x0a</ul>\x0a\x0a<p>Examples\x20of\x20unacceptable\x20behavior\x20by\x20participants\x20include:</p>\x0a\x0a<ul>\x0a<li>The\x20use\x20of\x20sexualized\x20language\x20or\x20imagery\x20and\x20unwelcome\x20sexual\x20attention\x20or\x0aadvances</li>\x0a<li>Trolling,\x20insulting/derogatory\x20comments,\x20and\x20personal\x20or\x20political\x20attacks</li>\x0a<li>Public\x20or\x20private\x20harassment</li>\x0a<li>Publishing\x20others’\x20private\x20information,\x20such\x20as\x20a\x20physical\x20or\x20electronic\x0aaddress,\x20without\x20explicit\x20permission</li>\x0a<li>Other\x20conduct\x20which\x20could\x20reasonably\x20be\x20considered\x20inappropriate\x20in\x20a\x0aprofessional\x20setting</li>\x0a</ul>\x0a\x0a<h3\x20id=\"our-responsibilities\">Our\x20Responsibilities</h3>\x0a\x0a<p>Project\x20maintainers\x20are\x20responsible\x20for\x20clarifying\x20the\x20standards\x20of\x20acceptable\x0abehavior\x20and\x20are\x20expected\x20to\x20take\x20appropriate\x20and\x20fair\x20corrective\x20action\x20in\x0aresponse\x20to\x20any\x20instances\x20of\x20unacceptable\x20behavior.</p>\x0a\x0a<p>Project\x20maintainers\x20have\x20the\x20right\x20and\x20responsibility\x20to\x20remove,\x20edit,\x20or\x20reject\x0acomments,\x20commits,\x20code,\x20wiki\x20edits,\x20issues,\x20and\x20other\x20contributions\x20that\x20are\x0anot\x20aligned\x20to\x20this\x20Code\x20of\x20Conduct,\x20or\x20to\x20ban\x20temporarily\x20or\x20permanently\x20any\x0acontributor\x20for\x20other\x20behaviors\x20that\x20they\x20deem\x20inappropriate,\x20threatening,\x0aoffensive,\x20or\x20harmful.</p>\x0a\x0a<h3\x20id=\"scope\">Scope</h3>\x0a\x0a<p>This\x20Code\x20of\x20Conduct\x20applies\x20both\x20within\x20project\x20spaces\x20and\x20in\x20public\x20spaces\x0awhen\x20an\x20individual\x20is\x20representing\x20the\x20project\x20or\x20its\x20community.\x20Examples\x20of\x0arepresenting\x20a\x20project\x20or\x20community\x20include\x20using\x20an\x20official\x20project\x20e-mail\x0aaddress,\x20posting\x20via\x20an\x20official\x20social\x20media\x20account,\x20or\x20acting\x20as\x20an\x20appointed\x0arepresentative\x20at\x20an\x20online\x20or\x20offline\x20event.\x20Representation\x20of\x20a\x20project\x20may\x20be\x0afurther\x20defined\x20and\x20clarified\x20by\x20project\x20maintainers.</p>\x0a\x0a<p>This\x20Code\x20of\x20Conduct\x20also\x20applies\x20outside\x20the\x20project\x20spaces\x20when\x20the\x20Project\x0aStewards\x20have\x20a\x20reasonable\x20belief\x20that\x20an\x20individual’s\x20behavior\x20may\x20have\x20a\x0anegative\x20impact\x20on\x20the\x20project\x20or\x20its\x20community.</p>\x0a\x0a<h3\x20id=\"conflict-resolution\"></a>Conflict\x20Resolution</h3>\x0a\x0a<p>We\x20do\x20not\x20believe\x20that\x20all\x20conflict\x20is\x20bad;\x20healthy\x20debate\x20and\x20disagreement\x0aoften\x20yield\x20positive\x20results.\x20However,\x20it\x20is\x20never\x20okay\x20to\x20be\x20disrespectful\x20or\x0ato\x20engage\x20in\x20behavior\x20that\x20violates\x20the\x20project\xe2\x80\x99s\x20code\x20of\x20conduct.</p>\x0a\x0a<p>If\x20you\x20see\x20someone\x20violating\x20the\x20code\x20of\x20conduct,\x20you\x20are\x20encouraged\x20to\x20address\x0athe\x20behavior\x20directly\x20with\x20those\x20involved.\x20Many\x20issues\x20can\x20be\x20resolved\x20quickly\x0aand\x20easily,\x20and\x20this\x20gives\x20people\x20more\x20control\x20over\x20the\x20outcome\x20of\x20their\x0adispute.\x20If\x20you\x20are\x20unable\x20to\x20resolve\x20the\x20matter\x20for\x20any\x20reason,\x20or\x20if\x20the\x0abehavior\x20is\x20threatening\x20or\x20harassing,\x20report\x20it.\x20We\x20are\x20dedicated\x20to\x20providing\x0aan\x20environment\x20where\x20participants\x20feel\x20welcome\x20and\x20safe.</p>\x0a\x0a<p\x20id=\"reporting\">Reports\x20should\x20be\x20directed\x20to\x20Carmen\x20Andoh\x20and\x20Van\x20Riper,\x20the\x0aGo\x20Project\x20Stewards,\x20at\x20<i>conduct@golang.org</i>.\x0aIt\x20is\x20the\x20Project\x20Stewards\xe2\x80\x99\x20duty\x20to\x0areceive\x20and\x20address\x20reported\x20violations\x20of\x20the\x20code\x20of\x20conduct.\x20They\x20will\x20then\x0awork\x20with\x20a\x20committee\x20consisting\x20of\x20representatives\x20from\x20the\x20Open\x20Source\x0aPrograms\x20Office\x20and\x20the\x20Google\x20Open\x20Source\x20Strategy\x20team.\x20If\x20for\x20any\x20reason\x20you\x0aare\x20uncomfortable\x20reaching\x20out\x20the\x20Project\x20Stewards,\x20please\x20email\x0athe\x20Google\x20Open\x20Source\x20Programs\x20Office\x20at\x20<i>opensource@google.com</i>.</p>\x0a\x0a<p>We\x20will\x20investigate\x20every\x20complaint,\x20but\x20you\x20may\x20not\x20receive\x20a\x20direct\x20response.\x0aWe\x20will\x20use\x20our\x20discretion\x20in\x20determining\x20when\x20and\x20how\x20to\x20follow\x20up\x20on\x20reported\x0aincidents,\x20which\x20may\x20range\x20from\x20not\x20taking\x20action\x20to\x20permanent\x20expulsion\x20from\x0athe\x20project\x20and\x20project-sponsored\x20spaces.\x20We\x20will\x20notify\x20the\x20accused\x20of\x20the\x0areport\x20and\x20provide\x20them\x20an\x20opportunity\x20to\x20discuss\x20it\x20before\x20any\x20action\x20is\x20taken.\x0aThe\x20identity\x20of\x20the\x20reporter\x20will\x20be\x20omitted\x20from\x20the\x20details\x20of\x20the\x20report\x0asupplied\x20to\x20the\x20accused.\x20In\x20potentially\x20harmful\x20situations,\x20such\x20as\x20ongoing\x0aharassment\x20or\x20threats\x20to\x20anyone’s\x20safety,\x20we\x20may\x20take\x20action\x20without\x20notice.</p>\x0a\x0a<h3\x20id=\"attribution\">Attribution</h3>\x0a\x0a<p>This\x20Code\x20of\x20Conduct\x20is\x20adapted\x20from\x20the\x20Contributor\x20Covenant,\x20version\x201.4,\x0aavailable\x20at\x0a<a\x20href=\"https://www.contributor-covenant.org/version/1/4/code-of-conduct.html\">https://www.contributor-covenant.org/version/1/4/code-of-conduct.html</a></p>\x0a\x0a<h2\x20id=\"summary\">Summary</h2>\x0a\x0a<ul>\x0a<li>Treat\x20everyone\x20with\x20respect\x20and\x20kindness.\x0a<li>Be\x20thoughtful\x20in\x20how\x20you\x20communicate.\x0a<li>Don\xe2\x80\x99t\x20be\x20destructive\x20or\x20inflammatory.\x0a<li>If\x20you\x20encounter\x20an\x20issue,\x20please\x20mail\x20<a\x20href=\"mailto:conduct@golang.org\">conduct@golang.org</a>.\x0a</ul>\x0a",
