doc/install.html

<!-- Installing Go -->

<h2>Introduction</h2>

<p>
There are two distinct ways to experiment with Go.
This document explains how to check out, build, and use the <code>gc</code> Go
compiler and tools (<code>6g</code>, <code>8g</code> etc.).
For information on how to use <code>gccgo</code>, a more traditional
compiler using the GCC back end, see
<a href="go_gccgo_setup.html">Setting up and using gccgo</a>.
</p>

<h2>Environment variables</h2>

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

<dl>
<dt>
	<code>$GOROOT</code>
</dt>
<dd>The root of the Go tree.  Typically this is <code>$HOME/go</code>
	but it can be any directory.
</dd>

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

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

<p>
Note that <code>$GOARCH</code> and <code>$GOOS</code> identify the
<em>target</em> environment, not the environment you are running on.
In effect, you are always cross-compiling.
</p>

<p>
After setting these variables in your <code>.bashrc</code>, double-check them by
listing your environment.
</p>

<pre>
$ env | grep '^GO'
</pre>

<h2>Ports</h2>

<p>
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).
</p>
<p>
There are important differences in the quality of the compilers for the different
architectures.
</p>

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

<p>
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.
</p>

<p>
See the separate <a href="go_gccgo_setup.html"><code>gccgo</code> document</a>
for details about that compiler and environment.
</p>

<h2>Fetch the repository</h2>

<p>
If you do not have Mercurial installed (you do not have an <code>hg</code> command),
this command:
</p>

<pre>
$ sudo easy_install mercurial
</pre>

<p>works on most systems.
If that fails, visit the <a href="http://mercurial.selenic.com/wiki/Download">Mercurial Download</a> page.</p>

<p>Make sure the <code>$GOROOT</code> directory does not exist or is empty.
Then check out the repository:</p>

<!-- TODO(go-dev): Replace with http://go.googlecode.com/ for launch. -->
<pre>
$ hg clone http://r45/ $GOROOT
</pre>

<h2>Install Go</h2>

<p>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,
</p>

<pre>
$ sudo apt-get install bison
</pre>

<p>
(or the equivalent on your Linux distribution).
</p>

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

<pre>
$ cd $GOROOT/src
$ ./all.bash
</pre>

<p>
If <code>all.bash</code> goes well, it will finish by printing
</p>

<pre>
--- cd ../test
N known bugs; 0 unexpected bugs
</pre>

<p>
where <var>N</var> is a number that varies from release to release.
</p>

<h2>Writing programs</h2>

<p>
Given a file <code>file.go</code>, compile it using
</p>

<pre>
$ 6g file.go
</pre>

<p>
<code>6g</code> is the Go compiler for <code>amd64</code>; it will write the output
in <code>file.6</code>. The &lsquo;<code>6</code>&rsquo; identifies
files for the <code>amd64</code> architecture.
The identifier letters for <code>386</code> and <code>arm</code>
are &lsquo;<code>8</code>&rsquo; and &lsquo;<code>5</code>&rsquo;.
That is, if you were compiling for <code>386</code>, you would use
<code>8g</code> and the output would be named <code>file.8</code>.
</p>

<p>
To link the file, use
</p>

<pre>
$ 6l file.6
</pre>

<p>
and to run it
</p>

<pre>
$ ./6.out
</pre>

<p>A complete example:
</p>

<pre>
$ cat &gt;hello.go &lt;&lt;EOF
package main

import "fmt"

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

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

<p>
To build more complicated programs, you will probably
want to use a 
<code>Makefile</code>.
There are examples in places like
<code>$GOROOT/src/cmd/godoc/Makefile</code>
and <code>$GOROOT/src/pkg/*/Makefile</code>.
The
<a href="contribute.html">document</a>
about contributing to the Go project
gives more detail about
the process of building and testing Go programs.
</p>