From c19b7b23e55f5fdb33a6c280cf1af29eb54d456f Mon Sep 17 00:00:00 2001 From: Alberto Donizetti Date: Sat, 28 Sep 2019 20:29:11 +0200 Subject: doc: remove double mention of custom workspace In the GOPATH section of the 'How To Write Go Code' document, it is mentioned two times in the span of a few lines that one can set GOPATH to a custom workspace path. The two paragraphs say basically the same thing, and they both link to golang.org/wiki/SettingGOPATH, so I'm quite sure the duplication is not intentional. This change deletes the second occurrence. Change-Id: I16f8bb8657041a23ed272eacf9adbc5637e8e34a Reviewed-on: https://go-review.googlesource.com/c/go/+/197839 Reviewed-by: Dmitri Shuralyov --- doc/code.html | 5 ----- 1 file changed, 5 deletions(-) (limited to 'doc/code.html') diff --git a/doc/code.html b/doc/code.html index 1e380001e0..a2adc82ae0 100644 --- a/doc/code.html +++ b/doc/code.html @@ -166,11 +166,6 @@ To learn more about the GOPATH environment variable, see 'go help gopath'.

-

-To use a custom workspace location, -set the GOPATH environment variable. -

-

Import paths

-- cgit v1.3 From 60dc159cf71c7f4b7021a7bed8708fecf5547887 Mon Sep 17 00:00:00 2001 From: Jean de Klerk Date: Fri, 4 Oct 2019 13:10:04 -0600 Subject: doc: remove code.html This is being moved to x/website in https://golang.org/cl/199058. Updates golang/go#33637 Updates golang/go#29206 Change-Id: I5c58b784fcdd212d7a003cd0f4085059f33a47c7 Reviewed-on: https://go-review.googlesource.com/c/go/+/199057 Reviewed-by: Dmitri Shuralyov --- doc/code.html | 643 ---------------------------------------------------------- 1 file changed, 643 deletions(-) delete mode 100644 doc/code.html (limited to 'doc/code.html') diff --git a/doc/code.html b/doc/code.html deleted file mode 100644 index a2adc82ae0..0000000000 --- a/doc/code.html +++ /dev/null @@ -1,643 +0,0 @@ - - -

Introduction

- -

-This document demonstrates the development of a simple Go package and -introduces the go tool, the standard way to fetch, -build, and install Go packages and commands. -

- -

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

- -

-A similar explanation is available as a -screencast. -

- - -

Code organization

- -

Overview

- - - -

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

- -

Workspaces

- -

-A workspace is a directory hierarchy with two directories at its root: -

- - - -

-The go tool builds and installs binaries to the bin directory. -

- -

-The src subdirectory typically contains multiple version control -repositories (such as for Git or Mercurial) that track the development of one -or more source packages. -

- -

-To give you an idea of how a workspace looks in practice, here's an example: -

- -
-bin/
-    hello                          # command executable
-    outyet                         # command executable
-src/
-    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
-    golang.org/x/image/
-        .git/                      # Git repository metadata
-	bmp/
-	    reader.go              # package source
-	    writer.go              # package source
-    ... (many more repositories and packages omitted) ...
-
- -

-The tree above shows a workspace containing two repositories -(example and image). -The example repository contains two commands (hello -and outyet) and one library (stringutil). -The image repository contains the bmp package -and several others. -

- -

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

- -

-Note that symbolic links should not be used to link files or directories into your workspace. -

- -

-Commands and libraries are built from different kinds of source packages. -We will discuss the distinction later. -

- - -

The GOPATH environment variable

- -

-The GOPATH environment variable specifies the location of your -workspace. It defaults to a directory named go inside your home directory, -so $HOME/go on Unix, -$home/go on Plan 9, -and %USERPROFILE%\go (usually C:\Users\YourName\go) on Windows. -

- -

-If you would like to work in a different location, you will need to -set GOPATH -to the path to that directory. -(Another common setup is to set GOPATH=$HOME.) -Note that GOPATH must not be the -same path as your Go installation. -

- -

-The command go env GOPATH -prints the effective current GOPATH; -it prints the default location if the environment variable is unset. -

- -

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

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

-The scripts in the rest of this document use $GOPATH -instead of $(go env GOPATH) for brevity. -To make the scripts run as written -if you have not set GOPATH, -you can substitute $HOME/go in those commands -or else run: -

- -
-$ export GOPATH=$(go env GOPATH)
-
- -

-To learn more about the GOPATH environment variable, see -'go help gopath'. -

- -

Import paths

- -

-An import path 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). -

- -

-The packages from the standard library are given short import paths such as -"fmt" and "net/http". -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. -

- -

-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 GitHub account at -github.com/user, that should be your base path. -

- -

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

- -

-We'll use github.com/user as our base path. Create a directory -inside your workspace in which to keep source code: -

- -
-$ mkdir -p $GOPATH/src/github.com/user
-
- - -

Your first program

- -

-To compile and run a simple program, first choose a package path (we'll use -github.com/user/hello) and create a corresponding package directory -inside your workspace: -

- -
-$ mkdir $GOPATH/src/github.com/user/hello
-
- -

-Next, create a file named hello.go inside that directory, -containing the following Go code. -

- -
-package main
-
-import "fmt"
-
-func main() {
-	fmt.Println("Hello, world.")
-}
-
- -

-Now you can build and install that program with the go tool: -

- -
-$ go install github.com/user/hello
-
- -

-Note that you can run this command from anywhere on your system. The -go tool finds the source code by looking for the -github.com/user/hello package inside the workspace specified by -GOPATH. -

- -

-You can also omit the package path if you run go install from the -package directory: -

- -
-$ cd $GOPATH/src/github.com/user/hello
-$ go install
-
- -

-This command builds the hello command, producing an executable -binary. It then installs that binary to the workspace's bin -directory as hello (or, under Windows, hello.exe). -In our example, that will be $GOPATH/bin/hello, which is -$HOME/go/bin/hello. -

- -

-The go tool will only print output when an error occurs, so if -these commands produce no output they have executed successfully. -

- -

-You can now run the program by typing its full path at the command line: -

- -
-$ $GOPATH/bin/hello
-Hello, world.
-
- -

-Or, as you have added $GOPATH/bin to your PATH, -just type the binary name: -

- -
-$ hello
-Hello, world.
-
- -

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

- -
-$ cd $GOPATH/src/github.com/user/hello
-$ git init
-Initialized empty Git repository in /home/user/go/src/github.com/user/hello/.git/
-$ git add hello.go
-$ git commit -m "initial commit"
-[master (root-commit) 0b4507d] initial commit
- 1 file changed, 7 insertion(+)
- create mode 100644 hello.go
-
- -

-Pushing the code to a remote repository is left as an exercise for the reader. -

- - -

Your first library

- -

-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/stringutil) and create the package directory: -

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

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

- -
-// 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)
-}
-
- -

-Now, test that the package compiles with go build: -

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

-Or, if you are working in the package's source directory, just: -

- -
-$ go build
-
- -

-This won't produce an output file. -Instead it saves the compiled package in the local build cache. -

- -

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

- -
-package main
-
-import (
-	"fmt"
-
-	"github.com/user/stringutil"
-)
-
-func main() {
-	fmt.Println(stringutil.Reverse("!oG ,olleH"))
-}
-
- -

-Install the hello program: -

- -
-$ go install github.com/user/hello
-
- -

-Running the new version of the program, you should see a new, reversed message: -

- -
-$ hello
-Hello, Go!
-
- -

-After the steps above, your workspace should look like this: -

- -
-bin/
-    hello                 # command executable
-src/
-    github.com/user/
-        hello/
-            hello.go      # command source
-        stringutil/
-            reverse.go    # package source
-
- -

Package names

- -

-The first statement in a Go source file must be -

- -
-package name
-
- -

-where name is the package's default name for imports. -(All files in a package must use the same name.) -

- -

-Go's convention is that the package name is the last element of the -import path: the package imported as "crypto/rot13" -should be named rot13. -

- -

-Executable commands must always use package main. -

- -

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

- -

-See Effective Go to learn more about -Go's naming conventions. -

- - -

Testing

- -

-Go has a lightweight test framework composed of the go test -command and the testing package. -

- -

-You write a test by creating a file with a name ending in _test.go -that contains functions named TestXXX with signature -func (t *testing.T). -The test framework runs each such function; -if the function calls a failure function such as t.Error or -t.Fail, the test is considered to have failed. -

- -

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

-Then run the test with go test: -

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

-As always, if you are running the go tool from the package -directory, you can omit the package path: -

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

-Run go help test and see the -testing package documentation for more detail. -

- - -

Remote packages

- -

-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 -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 github.com/golang/example/hello
-$ $GOPATH/bin/hello
-Hello, Go examples!
-
- -

-If the specified package is not present in a workspace, go get -will place it inside the first workspace specified by GOPATH. -(If the package does already exist, go get skips the remote -fetch and behaves the same as go install.) -

- -

-After issuing the above go get command, the workspace directory -tree should now look like this: -

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

-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 "github.com/golang/example/stringutil"
-
- -

-This convention is the easiest way to make your Go packages available for -others to use. -The Go Wiki -and godoc.org -provide lists of external Go projects. -

- -

-For more information on using remote repositories with the go tool, see -go help importpath. -

- - -

What's next

- -

-Subscribe to the -golang-announce -mailing list to be notified when a new stable version of Go is released. -

- -

-See Effective Go for tips on writing -clear, idiomatic Go code. -

- -

-Take A Tour of Go to learn the language -proper. -

- -

-Visit the documentation page for a set of in-depth -articles about the Go language and its libraries and tools. -

- - -

Getting help

- -

-For real-time help, ask the helpful gophers in #go-nuts on the -Freenode IRC server. -

- -

-The official mailing list for discussion of the Go language is -Go Nuts. -

- -

-Report bugs using the -Go issue tracker. -

-- cgit v1.3