## Introduction

There are two distinct ways to experiment with Go. This document explains how to check out, build, and use the `gc` Go compiler and tools (`6g`, `8g` etc.). 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 `linux`, `darwin` (Mac OS X 10.5 or 10.6), 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'

## Ports

Go compilers support two operating systems (Linux, Mac OS X) and three instruction sets. The versions for Linux and Mac are equally capable except that the ARM port does not run on OS X (yet).

There are important differences in the quality of the compilers for the different architectures.

`amd64` (a.k.a. `x86-64`); `6g,6l,6c,6a`
  The strongest implementation. The compiler has an effective optimizer (registerizer) and generates good code (although `gccgo` can do noticeably better sometimes).
`386` (a.k.a. `x86` or `x86-32`); `8g,8l,8c,8a`
  Comparable to the `amd64` port, but there is no optimizer. Work is underway.
`arm` (a.k.a. `ARM`); `5g,5l,5c,5a`
  Developed under the QEMU emulation environment, this is the newest implementation. It's got a couple of outstanding bugs but is improving.

Except for things like low-level operating system interface code, the runtime support is the same in all ports and includes a mark-and-sweep garbage collector (a fancier one is in the works), efficient array and string slicing, support for segmented stacks, and a strong goroutine implementation.

See the separate `gccgo` document for details about that compiler and environment.

## 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 places like `$GOROOT/src/cmd/godoc/Makefile` and `$GOROOT/src/pkg/*/Makefile`. The document about contributing to the Go project gives more detail about the process of building and testing Go programs.