Introduction

There are two distinct ways to experiment with Go. This document explains how to check out, build, and use the 6g Go compiler and tools. For information on how to use gccgo, a more traditional compiler using the gcc back end, see Setting up and using gccgo.

Environment variables

The Go compilation environment depends on three environment variables that you should set in your .bashrc or equivalent, plus one optional variable:

$GOROOT

The root of the Go tree. Typically this is $HOME/go but it can be any directory.

$GOOS and $GOARCH

The name of the target operating system and compilation architecture. Choices for $GOOS are darwin (OS X), linux, and nacl (Native Client, an incomplete port). Choices for $GOARCH are amd64 (64-bit x86, the most stable port), 386 (32-bit x86, an unoptimized but stable port), and arm (32-bit ARM, an incomplete port). The valid combinations are linux/amd64, linux/arm, linux/386, darwin/amd64, darwin/386, and nacl/386.

$GOBIN (optional)

The location where binaries will be installed. If you set $GOBIN, you need to ensure that it is in your $PATH so that newly built Go-specific command such as the compiler can be found during the build. The default, $HOME/bin, may already be in your $PATH.

Note that $GOARCH and $GOOS identify the target environment, not the environment you are running on. In effect, you are always cross-compiling.

After setting these variables in your .bashrc, double-check them by listing your environment.

$ env | grep '^GO'

Fetch the repository

If you do not have Mercurial installed (you do not have an hg command), this command:

$ sudo easy_install mercurial

works on most systems. If that fails, visit the Mercurial Download page.

Make sure the $GOROOT directory does not exist or is empty. Then check out the repository:

$ hg clone http://r45/ $GOROOT

Install Go

You need to have the parser generator Bison installed. It is installed as part of Xcode on OS X. If you need it on Linux,

$ sudo apt-get install bison

(or the equivalent on your Linux distribution).

To build the Go distribution, make sure $GOBIN (or $HOME/bin if $GOBIN is not set) is in your $PATH and then run

$ cd $GOROOT/src
$ ./all.bash

If all.bash goes well, it will finish by printing

--- cd ../test
N known bugs; 0 unexpected bugs

where N is a number that varies from release to release.

Writing programs

Given a file file.go, compile it using

$ 6g file.go

6g is the Go compiler for amd64; it will write the output in file.6. The ‘6’ identifies files for the amd64 architecture. The identifier letters for 386 and arm are ‘8’ and ‘5’. That is, if you were compiling for 386, you would use 8g and the output would be named file.8.

To link the file, use

$ 6l file.6

and to run it

$ ./6.out

A complete example:

$ cat >hello.go <<EOF
package main

import "fmt"

func main() {
	fmt.Printf("hello, world\n")
}
EOF
$ 6g hello.go
$ 6l hello.6
$ ./6.out
hello, world
$

There is no need to list hello.6's package dependencies (in this case, package fmt) on the 6l command line. The linker learns about them by reading hello.6.

To build more complicated programs, you will probably want to use a Makefile. There are examples in $GOROOT/src/cmd/godoc/Makefile and $GOROOT/src/pkg/*/Makefile. XXX other document XXX gives more detail about the process of building and testing Go programs.