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.
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.
The source code for the package with import path
x/y is, by convention, kept in the
directory $GOROOT/src/pkg/x/y.
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.inc 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.inc 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.
If you have not set $GOROOT in your environment,
you must run gomake to use this form of makefile.
Gomake also takes care to invoke GNU Make
even on systems where it is installed as gmake
rather than make.
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.
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.
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.
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.
To build a Go program with gomake, create a Makefile alongside your program's
source files. It should be similar to the example above, but include
Make.cmd instead of Make.pkg:
include $(GOROOT)/src/Make.inc TARG=helloworld GOFILES=\ helloworld.go\ include $(GOROOT)/src/Make.cmd
Running gomake will compile helloworld.go
and produce an executable named helloworld in the current
directory.
Running gomake install will build helloworld if
necessary and copy it to the $GOBIN directory
($GOROOT/bin/ is the default).
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 -test.bench=..
Once your new code is tested and working, it's time to get it reviewed and submitted.
This example package, numbers, consists of the function
Double, which takes an int and returns that value
multiplied by 2. It consists of three files.
First, the package implementation, numbers.go:
package numbers
func Double(i int) int {
return i * 2
}
Next, the tests, numbers_test.go:
package numbers
import (
"testing"
)
type doubleTest struct {
in, out int
}
var doubleTests = []doubleTest{
doubleTest{1, 2},
doubleTest{2, 4},
doubleTest{-5, -10},
}
func TestDouble(t *testing.T) {
for _, dt := range doubleTests {
v := Double(dt.in)
if v != dt.out {
t.Errorf("Double(%d) = %d, want %d.", dt.in, v, dt.out)
}
}
}
Finally, the Makefile:
include $(GOROOT)/src/Make.inc TARG=numbers GOFILES=\ numbers.go\ include $(GOROOT)/src/Make.pkg
Running gomake install will build and install the package to
the $GOROOT/pkg/ directory (it can then be used by any
program on the system).
Running gomake test (or just running the command
gotest) will rebuild the package, including the
numbers_test.go file, and then run the TestDouble
function. The output "PASS" indicates that all tests passed
successfully. Breaking the implementation by changing the multiplier from
2 to 3 will allow you to see how failing tests are
reported.
See the gotest documentation and the testing package for more detail.
First, a disclaimer: very few Go packages should need to know about the hardware and operating system they run on. In the vast majority of cases the language and standard library handle most portability issues. This section is a guide for experienced systems programmers who have a good reason to write platform-specific code, such as assembly-language support for fast trigonometric functions or code that implements a common interface above different operating systems.
To compile such code, use the $GOOS and $GOARCH
environment variables in your
source file names and Makefile.
For example, this Makefile describes a package that builds on
different operating systems by parameterizing the file name with
$GOOS.
include $(GOROOT)/src/Make.inc TARG=mypackage GOFILES=\ my.go\ my_$(GOOS).go\ include $(GOROOT)/src/Make.pkg
The OS-specific code goes in my_linux.go,
my_darwin.go, and so on.
If you follow these conventional parameterizations, tools such as goinstall will work seamlessly with your package:
my_$(GOOS).go my_$(GOARCH).go my_$(GOOS)_$(GOARCH).go
The same holds for .s (assembly) and .cgo files.