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, be sure 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 any 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 make all or make build.)

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.