From 395a8eb5f4e4e10220a8a728a2124cf1521f70d3 Mon Sep 17 00:00:00 2001 From: Andrew Gerrand Date: Mon, 10 Nov 2014 09:15:57 +1100 Subject: all: use golang.org/x/... import paths LGTM=rsc, r R=r, rsc CC=golang-codereview, golang-codereviews https://codereview.appspot.com/168050043 --- doc/articles/go_command.html | 13 +-- doc/cmd.html | 6 +- doc/code.html | 183 +++++++++++++++++++++++-------------------- doc/contribute.html | 2 +- doc/go1compat.html | 6 +- doc/go_faq.html | 4 +- doc/install-source.html | 6 +- 7 files changed, 115 insertions(+), 105 deletions(-) (limited to 'doc') diff --git a/doc/articles/go_command.html b/doc/articles/go_command.html index 246b8c956..2978628cd 100644 --- a/doc/articles/go_command.html +++ b/doc/articles/go_command.html @@ -78,17 +78,18 @@ well-established conventions.

source code. For Bitbucket, GitHub, Google Code, and Launchpad, the root directory of the repository is identified by the repository's main URL, without the http:// prefix. Subdirectories are named by -adding to that path. For example, the supplemental networking -libraries for Go are obtained by running

+adding to that path. +For example, the Go example programs are obtained by running

-hg clone http://code.google.com/p/go.net
+git clone https://github.com/golang/example

and thus the import path for the root directory of that repository is -"code.google.com/p/go.net". The websocket package is stored in a -subdirectory, so its import path is -"code.google.com/p/go.net/websocket".

+"github.com/golang/example". +The stringutil +package is stored in a subdirectory, so its import path is +"github.com/golang/example/stringutil".

These paths are on the long side, but in exchange we get an automatically managed name space for import paths and the ability for diff --git a/doc/cmd.html b/doc/cmd.html index 132ea275f..5d20d3887 100644 --- a/doc/cmd.html +++ b/doc/cmd.html @@ -62,7 +62,7 @@ details. -cover +cover      Cover is a program for creating and analyzing the coverage profiles generated by "go test -coverprofile". @@ -83,13 +83,13 @@ gofmt command with more general options. -godoc +godoc      Godoc extracts and generates documentation for Go packages. -vet +vet      Vet examines Go source code and reports suspicious constructs, such as Printf calls whose arguments do not align with the format string. diff --git a/doc/code.html b/doc/code.html index f019306fa..ce9f8636f 100644 --- a/doc/code.html +++ b/doc/code.html @@ -60,37 +60,35 @@ To give you an idea of how a workspace looks in practice, here's an example: 

 bin/
-    streak                         # command executable
-    todo                           # command executable
+    hello                          # command executable
+    outyet                         # command executable
 pkg/
     linux_amd64/
-        code.google.com/p/goauth2/
-            oauth.a                # package object
-        github.com/nf/todo/
-            task.a                 # package object
+        github.com/golang/example/
+            stringutil.a           # package object
 src/
-    code.google.com/p/goauth2/
-        .hg/                       # mercurial repository metadata
-        oauth/
-            oauth.go               # package source
-            oauth_test.go          # test source
-    github.com/nf/
-        streak/
-            .git/                  # git repository metadata
-            oauth.go               # command source
-            streak.go              # command source
-        todo/
-            .git/                  # git repository metadata
-            task/
-                task.go            # package source
-            todo.go                # command source
+    github.com/golang/example/
+        .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

-This workspace contains three repositories (goauth2, -streak, and todo) comprising two commands -(streak and todo) and two libraries -(oauth and task). +This workspace contains one repository (example) +comprising two commands (hello and outyet) +and one library (stringutil). +

+ +

+A typical workspace would contain many source repositories containing many +packages and commands. Most Go programmers keep all their Go source code +and dependencies in a single workspace.

@@ -277,29 +275,29 @@ Let's write a library and use it from the hello program.

Again, the first step is to choose a package path (we'll use -github.com/user/newmath) and create the package directory: +github.com/user/stringutil) and create the package directory: 

-$ mkdir $GOPATH/src/github.com/user/newmath
+$ mkdir $GOPATH/src/github.com/user/stringutil

-Next, create a file named sqrt.go in that directory with the +Next, create a file named reverse.go in that directory with the following contents. 

-// Package newmath is a trivial example package.
-package newmath
-
-// Sqrt returns an approximation to the square root of x.
-func Sqrt(x float64) float64 {
-	z := 1.0
-	for i := 0; i < 1000; i++ {
-		z -= (z*z - x) / (2 * z)
+// 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 z
+	return string(r)
 }
@@ -308,7 +306,7 @@ Now, test that the package compiles with go build: 

-$ go build github.com/user/newmath
+$ go build github.com/user/stringutil

@@ -326,7 +324,7 @@ directory of the workspace.

-After confirming that the newmath package builds, +After confirming that the stringutil package builds, modify your original hello.go (which is in $GOPATH/src/github.com/user/hello) to use it:

@@ -337,18 +335,18 @@ package main import ( "fmt" - "github.com/user/newmath" + "github.com/user/stringutil" ) func main() { - fmt.Printf("Hello, world. Sqrt(2) = %v\n", newmath.Sqrt(2)) + fmt.Printf(stringutil.Reverse("!oG ,olleH")) }

Whenever the go tool installs a package or binary, it also -installs whatever dependencies it has. So when you install the hello -program +installs whatever dependencies it has. +So when you install the hello program 

@@ -356,16 +354,16 @@ $ go install github.com/user/hello

-the newmath package will be installed as well, automatically. +the stringutil package will be installed as well, automatically.

-Running the new version of the program, you should see some numerical output: +Running the new version of the program, you should see a new, reversed message: 

 $ hello
-Hello, world.  Sqrt(2) = 1.414213562373095
+Hello, Go!

@@ -374,22 +372,22 @@ After the steps above, your workspace should look like this: 

 bin/
-    hello              # command executable
+    hello                 # command executable
 pkg/
-    linux_amd64/       # this will reflect your OS and architecture
+    linux_amd64/          # this will reflect your OS and architecture
         github.com/user/
-            newmath.a  # package object
+            stringutil.a  # package object
 src/
     github.com/user/
         hello/
-            hello.go   # command source
-        newmath/
-            sqrt.go    # package source
+            hello.go      # command source
+        stringutil/
+            reverse.go    # package source

-Note that go install placed the newmath.a object in a -directory inside pkg/linux_amd64 that mirrors its source +Note that go install placed the stringutil.a object +in a directory inside pkg/linux_amd64 that mirrors its source directory. This is so that future invocations of the go tool can find the package object and avoid recompiling the package unnecessarily. @@ -457,20 +455,29 @@ if the function calls a failure function such as t.Error or

-Add a test to the newmath package by creating the file -$GOPATH/src/github.com/user/newmath/sqrt_test.go containing the -following Go code. +Add a test to the stringutil package by creating the file +$GOPATH/src/github.com/user/stringutil/reverse_test.go containing +the following Go code. 

-package newmath
+package stringutil
 
 import "testing"
 
-func TestSqrt(t *testing.T) {
-	const in, out = 4, 2
-	if x := Sqrt(in); x != out {
-		t.Errorf("Sqrt(%v) = %v, want %v", in, x, out)
+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)
+		}
 	}
 }
@@ -480,8 +487,8 @@ Then run the test with go test: 

-$ go test github.com/user/newmath
-ok  	github.com/user/newmath 0.165s
+$ go test github.com/user/stringutil
+ok  	github.com/user/stringutil 0.165s

@@ -491,7 +498,7 @@ directory, you can omit the package path: 

 $ go test
-ok  	github.com/user/newmath 0.165s
+ok  	github.com/user/stringutil 0.165s

@@ -507,16 +514,16 @@ An import path can describe how to obtain the package source code using a revision control system such as Git or Mercurial. The go tool uses this property to automatically fetch packages from remote repositories. For instance, the examples described in this document are also kept in a -Mercurial repository hosted at Google Code, -code.google.com/p/go.example. +Git repository hosted at GitHub +github.com/golang/example. If you include the repository URL in the package's import path, go get will fetch, build, and install it automatically: 

-$ go get code.google.com/p/go.example/hello
+$ go get github.com/golang/example/hello
 $ $GOPATH/bin/hello
-Hello, world.  Sqrt(2) = 1.414213562373095
+Hello, Go examples!

@@ -533,37 +540,39 @@ tree should now look like this: 

 bin/
-    hello                 # command executable
+    hello                           # command executable
 pkg/
     linux_amd64/
-        code.google.com/p/go.example/
-            newmath.a     # package object
+        github.com/golang/example/
+            stringutil.a            # package object
         github.com/user/
-            newmath.a     # package object
+            stringutil.a            # package object
 src/
-    code.google.com/p/go.example/
+    github.com/golang/example/
+	.git/                       # Git repository metadata
         hello/
-            hello.go      # command source
-        newmath/
-            sqrt.go       # package source
-            sqrt_test.go  # test source
+            hello.go                # command source
+        stringutil/
+            reverse.go              # package source
+            reverse_test.go         # test source
     github.com/user/
         hello/
-            hello.go      # command source
-        newmath/
-            sqrt.go       # package source
-            sqrt_test.go  # test source
+            hello.go                # command source
+        stringutil/
+            reverse.go              # package source
+            reverse_test.go         # test source

-The hello command hosted at Google Code depends on the -newmath package within the same repository. The imports in -hello.go file use the same import path convention, so the go -get command is able to locate and install the dependent package, too. +The hello command hosted at GitHub depends on the +stringutil package within the same repository. The imports in +hello.go file use the same import path convention, so the +go get command is able to locate and install the dependent +package, too. 

-import "code.google.com/p/go.example/newmath"
+import "github.com/golang/example/stringutil"

diff --git a/doc/contribute.html b/doc/contribute.html index 90c3f10a1..92fd88b48 100644 --- a/doc/contribute.html +++ b/doc/contribute.html @@ -121,7 +121,7 @@ are inside the go directory when issuing commands.

To contribute to subrepositories, edit the .hg/hgrc for each subrepository in the same way. For example, add the codereview extension to -code.google.com/p/go.tools/.hg/hgrc. +golang.org/x/tools/.hg/hgrc.

Understanding the extension

diff --git a/doc/go1compat.html b/doc/go1compat.html index 94c48d2ce..d800dec0c 100644 --- a/doc/go1compat.html +++ b/doc/go1compat.html @@ -153,7 +153,7 @@ developed software based on Go 1.

Code in sub-repositories of the main go tree, such as -code.google.com/p/go.net, +golang.org/x/net, may be developed under looser compatibility requirements. However, the sub-repositories will be tagged as appropriate to identify versions that are compatible @@ -170,9 +170,9 @@ is therefore outside the purview of the guarantees made here. As of Go version 1.4, the syscall package is frozen. Any evolution of the system call interface must be supported elsewhere, such as in the -go.sys subrepository. +go.sys subrepository. For details and background, see -this document. +this document.

Tools

diff --git a/doc/go_faq.html b/doc/go_faq.html index 9aac05838..759799779 100644 --- a/doc/go_faq.html +++ b/doc/go_faq.html @@ -1616,7 +1616,7 @@ Go is a fine language in which to implement a self-hosting compiler: a native lexer and parser are already available in the go package and a separate type checking -package +package has also been written.

@@ -1715,7 +1715,7 @@ func main() {

Nowadays, most Go programmers use a tool, -goimports, +goimports, which automatically rewrites a Go source file to have the correct imports, eliminating the unused imports issue in practice. This program is easily connected to most editors to run automatically when a Go source file is written. diff --git a/doc/install-source.html b/doc/install-source.html index 82859b50f..f53deb404 100644 --- a/doc/install-source.html +++ b/doc/install-source.html @@ -241,12 +241,12 @@ provides essential setup instructions for using the Go tools.

The source code for several Go tools (including godoc) -is kept in the go.tools repository. +is kept in the go.tools repository. To install all of them, run the go get command: 

-$ go get code.google.com/p/go.tools/cmd/...
+$ go get golang.org/x/tools/cmd/...

@@ -254,7 +254,7 @@ Or if you just want to install a specific command (godoc in this ca 

-$ go get code.google.com/p/go.tools/cmd/godoc
+$ go get golang.org/x/tools/cmd/godoc

-- cgit v1.2.1