From 10650b718e9020238b9db8ebdb34f674189709c5 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Wed, 9 Dec 2009 14:05:12 -0800 Subject: doc: split contribute.html into code.html and contribute.html R=r http://codereview.appspot.com/170042 --- doc/code.html | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 doc/code.html (limited to 'doc/code.html') diff --git a/doc/code.html b/doc/code.html new file mode 100644 index 000000000..178fca131 --- /dev/null +++ b/doc/code.html @@ -0,0 +1,204 @@ + + +

Introduction

+ +

+This document explains how to write a new package +and how to test code. +It assumes you have installed Go using the +installation instructions. +

+ +

+Before embarking on a change to an existing +package or the creation of a new package, +it's a good idea to send mail to the mailing list +to let people know what you are thinking of doing. +Doing so helps avoid duplication of effort and +enables discussions about design before much code +has been written. +

+ +

Community resources

+ +

+For real-time help, there may be users or developers on +#go-nuts on the Freenode IRC server. +

+ +

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

+ +

+Bugs can be reported using the Go issue tracker. +

+ +

+For those who wish to keep up with development, +there is another mailing list, golang-checkins, +that receives a message summarizing each checkin to the Go repository. +

+ + +

Creating a new package

+ +

+The source code for the package with import path +x/y is, by convention, kept in the +directory $GOROOT/src/pkg/x/y. +

+ +

Makefile

+ +

+It would be nice to have Go-specific tools that +inspect the source files to determine what to build and in +what order, but for now, Go uses GNU make. +Thus, the first file to create in a new package directory is +usually the Makefile. +The basic form used in the Go source tree +is illustrated by src/pkg/container/vector/Makefile: +

+ +
+include ../../../Make.$(GOARCH)
+
+TARG=container/vector
+GOFILES=\
+	intvector.go\
+	stringvector.go\
+	vector.go\
+
+include ../../../Make.pkg
+
+ +

+Outside the Go source tree (for personal packages), the standard form is +

+ +
+include $(GOROOT)/src/Make.$(GOARCH)
+
+TARG=mypackage
+GOFILES=\
+	my1.go\
+	my2.go\
+
+include $(GOROOT)/src/Make.pkg
+
+ +

+The first and last lines include standard definitions and rules. +Packages maintained in the standard Go tree use a relative path (instead of +$(GOROOT)/src) so that make will work correctly +even if $(GOROOT) contains spaces. +This makes it easy for programmers to try Go. +

+ +

+TARG is the target install path for the package, +the string that clients will use to import it. +Inside the Go tree, this string should be the same as the directory +in which the Makefile appears, with the +$GOROOT/src/pkg/ prefix removed. +Outside the Go tree, you can use any TARG you +want that doesn't conflict with the standard Go package names. +A common convention is to use an identifying top-level name +to group your packages: myname/tree, myname/filter, etc. +Note that even if you keep your package source outside the +Go tree, running make install installs your +package binaries in the standard location—$GOROOT/pkg—to +make it easy to find them. +

+ +

+GOFILES is a list of source files to compile to +create the package. The trailing \ characters +allow the list to be split onto multiple lines +for easy sorting. +

+ +

+If you create a new package directory in the Go tree, add it to the list in +$GOROOT/src/pkg/Makefile so that it +is included in the standard build. Then run: +

+cd $GOROOT/src/pkg
+./deps.bash
+
+

+to update the dependency file Make.deps. +(This happens automatically each time you run all.bash +or make.bash.) +

+ +

+If you change the imports of an existing package, +you do not need to edit $GOROOT/src/pkg/Makefile +but you will still need to run deps.bash as above. +

+ + +

Go source files

+ +

+The first statement in each of the source files listed in the Makefile +should 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. +At the moment, the Go tools impose a restriction that package names are unique +across all packages linked into a single binary, but that restriction +will be lifted soon. +

+ +

+Go compiles all the source files in a package at once, so one file +can refer to constants, variables, types, and functions in another +file without special arrangement or declarations. +

+ +

+Writing clean, idiomatic Go code is beyond the scope of this document. +Effective Go is an introduction to +that topic. +

+ +

Testing

+ +

+Go has a lightweight test framework known as gotest. +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. +The gotest command documentation +and the testing package documentation give more detail. +

+ +

+The *_test.go files should not be listed in the Makefile. +

+ +

+To run the test, run either make test or gotest +(they are equivalent). +To run only the tests in a single test file, for instance one_test.go, +run gotest one_test.go. +

+ +

+If your change affects performance, add a Benchmark function +(see the gotest command documentation) +and run it using gotest -benchmarks=.. +

+ +

+Once your new code is tested and working, +it's time to get it reviewed and submitted. +

+ -- cgit v1.2.3