doc/install.html - go - Git at Google

 <!-- Getting Started -->

 <h2 id="introduction">Introduction</h2>

 <p>Go is an open source project, distributed under a
 <a href="/LICENSE">BSD-style license</a>.
 This document explains how to check out the sources,
 build them on your own machine, and run them.
 </p>

 <div class="detail">

 <p>
 There are two distinct ways to experiment with Go.
 This document focuses on 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="gccgo_install.html">Setting up and using gccgo</a>.
 </p>

 <p>
 The Go compilers support three instruction sets.
 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 most mature 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.
 </dd>
 <dt>
 	<code>arm</code> (a.k.a. <code>ARM</code>); <code>5g,5l,5c,5a</code>
 </dt>
 <dd>
 	Incomplete.
 	It only supports Linux binaries, the optimizer is incomplete,
 	and floating point uses the VFP unit.
 	However, all tests pass.
 	Work on the optimizer is continuing.
 	Tested against a Nexus One.
 </dd>
 </dl>

 <p>
 Except for things like low-level operating system interface code, the run-time
 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>
 The compilers can target the FreeBSD, Linux,
 and OS X (a.k.a. Darwin) operating systems.
 (A port to Microsoft Windows is in progress but incomplete.  See the
 <a href="http://code.google.com/p/go/wiki/WindowsPort">Windows Port</a>
 page for details.)
 The full set of supported combinations is listed in the discussion of
 <a href="#environment">environment variables</a> below.
 </p>

 </div>

 <h2 id="ctools">Install C tools, if needed</h2>

 <p>The Go tool chain is written in C.
 To build it, you need these programs installed:
 <ul>
 <li>GCC,
 <li>the standard C libraries,
 <li>the parser generator Bison,
 <li><tt>make</tt>,
 <li><tt>awk</tt>, and
 <li>the text editor <tt>ed</tt>.
 </ul>
 </p>

 <p>On OS X, they can be
 installed as part of
 <a href="http://developer.apple.com/TOOLS/Xcode/">Xcode</a>.
 </p>

 <p>On Ubuntu/Debian, use <code>sudo apt-get install bison ed gawk gcc libc6-dev make</code>.
 </p>

 <h2 id="mercurial">Install Mercurial, if needed</h2>

 <p>
 To perform the next step you must have Mercurial installed. (Check that you  have an <code>hg</code> command.) This suffices to install Mercurial on most systems:
 </p>
 <pre>
 sudo easy_install mercurial
 </pre>
 (On Ubuntu/Debian, you might try <code>apt-get install python-setuptools
 python-dev build-essential</code> first. The Mercurial in your distribution's
 package repository will most likely be old and broken.)
 </p>
 <p>
 If that fails, try installing manually from the <a href="http://mercurial.selenic.com/wiki/Download">Mercurial Download</a> page.</p>
 </p>

 <p>
 Mercurial versions 1.7.x and up require the configuration of
 <a href="http://mercurial.selenic.com/wiki/CACertificates">Certification Authorities</a>
 (CAs). Error messages of the form:
 </p>
 <pre>
 warning: go.googlecode.com certificate with fingerprint b1:af: ... bc not verified (check hostfingerprints or web.cacerts config setting)
 </pre>
 <p>
 when using Mercurial indicate that the CAs are missing.
 Check your Mercurial version (<code>hg --version</code>) and
 <a href="http://mercurial.selenic.com/wiki/CACertificates#Configuration_of_HTTPS_certificate_authorities">configure the CAs</a>
 if necessary.
 </p>

 <h2 id="fetch">Fetch the repository</h2>

 <p>
 <p>Go will install to a directory named <code>go</code>.
 Change to the directory that will be its parent
 and make sure the <code>go</code> directory does not exist.
 Then check out the repository:</p>

 <pre>
 $ hg clone -r release https://go.googlecode.com/hg/ go
 </pre>

 <h2 id="install">Install Go</h2>

 <p>
 To build the Go distribution, run
 </p>

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

 <p>
 If all goes well, it will finish by printing output like:
 </p>

 <pre>
 ALL TESTS PASSED

 ---
 Installed Go for linux/amd64 in /home/you/go.
 Installed commands in /home/you/go/bin.
 *** You need to add /home/you/go/bin to your $PATH. ***
 The compiler is 6g.
 </pre>

 <p>
 where the details on the last few lines reflect the operating system,
 architecture, and root directory used during the install.
 </p>

 <div class="detail">

 <p>For more information about ways to control the build,
 see the discussion of <a href="#environment">environment variables</a> below.</p>
 </div>

 <h2 id="writing">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>

 <div class="detail">
 <p>
 To build more complicated programs, you will probably
 want to use a
 <code>Makefile</code>.
 There are examples in places like
 <code>go/src/cmd/godoc/Makefile</code>
 and <code>go/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>
 </div>

 <h2 id="next">What's next</h2>

 <p>
 Start by reading the <a href="go_tutorial.html">Go Tutorial</a>.
 </p>

 <p>
 Build a web application by following the <a href="codelab/wiki/">Wiki
 Codelab</a>.
 </p>

 <p>
 Read <a href="effective_go.html">Effective Go</a> to learn about writing
 idiomatic Go code.
 </p>

 <p>
 For the full story, consult Go's extensive
 <a href="docs.html">documentation</a>.
 </p>

 <h2 id="releases">Keeping up with releases</h2>

 <p>
 The Go project maintains two stable tags in its Mercurial repository:
 <code>release</code> and <code>weekly</code>.
 The <code>weekly</code> tag is updated about once a week, and should be used by
 those who want to track the project's development.
 The <code>release</code> tag is given, less often, to those weekly releases
 that have proven themselves to be robust.
 </p>

 <p>
 Most Go users will want to keep their Go installation at the latest
 <code>release</code> tag.
 New releases are announced on the
 <a href="http://groups.google.com/group/golang-announce">golang-announce</a>
 mailing list.
 </p>

 <p>
 To update an existing tree to the latest release, you can run:
 </p>

 <pre>
 $ cd go/src
 $ hg pull
 $ hg update release
 $ ./all.bash
 </pre>

 <p>
 To use the <code>weekly</code> tag run <code>hg update weekly</code> instead.
 </p>

 <h2 id="community">Community resources</h2>

 <p>
 For real-time help, there may be users or developers on
 <code>#go-nuts</code> on the <a href="http://freenode.net/">Freenode</a> IRC server.
 </p>

 <p>
 The official mailing list for discussion of the Go language is
 <a href="http://groups.google.com/group/golang-nuts">Go Nuts</a>.
 </p>

 <p>
 Bugs can be reported using the <a href="http://code.google.com/p/go/issues/list">Go issue tracker</a>.
 </p>

 <p>
 For those who wish to keep up with development,
 there is another mailing list, <a href="http://groups.google.com/group/golang-checkins">golang-checkins</a>,
 that receives a message summarizing each checkin to the Go repository.
 </p>

 <h2 id="environment">Environment variables</h2>

 <p>
 The Go compilation environment can be customized by environment variables.
 None are required by the build, but you may wish to set them
 to override the defaults.
 </p>

 <dl>
 <dt>
 	<code>$GOROOT</code>
 </dt>
 <dd>
 	The root of the Go tree, often <code>$HOME/go</code>.
 	This defaults to the parent of the directory where <code>all.bash</code> is run.
 	If you choose not to set <code>$GOROOT</code>, you must
 	run <code>gomake</code> instead of <code>make</code> or <code>gmake</code>
 	when developing Go programs using the conventional makefiles.
 </dd>

 <dt>
 	<code>$GOROOT_FINAL</code>
 </dt>
 <dd>
 	The value assumed by installed binaries and scripts when
 	<code>$GOROOT</code> is not set.
 	It defaults to the value used for <code>$GOROOT</code>.
 	If you want to build the Go tree in one location
 	but move it elsewhere after the build, set
 	<code>$GOROOT_FINAL</code> to the eventual location.
 </dd>

 <dt>
 <code>$GOOS</code> and <code>$GOARCH</code>
 </dt>
 <dd>
 	The name of the target operating system and compilation architecture.
 	These default to the values of <code>$GOHOSTOS</code> and
 	<code>$GOHOSTARCH</code> respectively (described below).

 	<p>
 	Choices for <code>$GOOS</code> are <code>linux</code>,
 	<code>freebsd</code>,
 	<code>darwin</code> (Mac OS X 10.5 or 10.6),
 	and <code>windows</code> (Windows, an incomplete port).
 	Choices for <code>$GOARCH</code> are <code>amd64</code> (64-bit x86, the most mature port),
 	<code>386</code> (32-bit x86), and
 	<code>arm</code> (32-bit ARM, an incomplete port).
 	The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> are:
 	<table cellpadding="0">
 	<tr>
 	<th width="50"><th align="left" width="100"><code>$GOOS</code></th> <th align="left" width="100"><code>$GOARCH</code></th> <th align="left"></th>
 	</tr>
 	<tr>
 	<td></td><td><code>darwin</code></td> <td><code>386</code></td>
 	</tr>
 	<tr>
 	<td></td><td><code>darwin</code></td> <td><code>amd64</code></td>
 	</tr>
 	<tr>
 	<td></td><td><code>freebsd</code></td> <td><code>386</code></td>
 	</tr>
 	<tr>
 	<td></td><td><code>freebsd</code></td> <td><code>amd64</code></td>
 	</tr>
 	<tr>
 	<td></td><td><code>linux</code></td> <td><code>386</code></td>
 	</tr>
 	<tr>
 	<td></td><td><code>linux</code></td> <td><code>amd64</code></td>
 	</tr>
 	<tr>
 	<td></td><td><code>linux</code></td> <td><code>arm</code></td> <td><i>incomplete</i></td>
 	</tr>
 	<tr>
 	<td></td><td><code>windows</code></td> <td><code>386</code></td> <td><i>incomplete</i></td>
 	</tr>
 	</table>
 </dd>

 <dt>
 <code>$GOHOSTOS</code> and <code>$GOHOSTARCH</code>
 </dt>
 <dd>
 	The name of the host operating system and compilation architecture.
 	These default to the local system's operating system and
 	architecture.

 	<p>
 	Valid choices are the same as for <code>$GOOS</code> and
 	<code>$GOARCH</code>, listed above.
 	The specified values must be compatible with the local system.
 	For example, you should not set <code>$GOHOSTARCH</code> to
 	<code>arm</code> on an x86 system.
 </dd>

 <dt>
 <code>$GOBIN</code>
 </dt>
 <dd>
 	The location where binaries will be installed.
 	The default is <code>$GOROOT/bin</code>.
 	After installing, you will want to arrange to add this
 	directory to your <code>$PATH</code>, so you can use the tools.
 </dd>

 <dt>
 <code>$GOARM</code> (arm, default=6)
 </dt>
 <dd>
 	The ARM architecture version the run-time libraries should target.
 	ARMv6 cores have more efficient synchronization primitives. Setting
 	<code>$GOARM</code> to 5 will compile the run-time libraries using
 	just SWP instructions that work on older architectures as well.
 	Running v6 code on an older core will cause an illegal instruction trap.
 </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.
 By architecture, we mean the kind of binaries
 that the target environment can run:
 an x86-64 system running a 32-bit-only operating system
 must set <code>GOARCH</code> to <code>386</code>,
 not <code>amd64</code>.
 </p>

 <p>
 If you choose to override the defaults,
 set these variables in your shell profile (<code>$HOME/.bashrc</code>,
 <code>$HOME/.profile</code>, or equivalent). The settings might look
 something like this:
 </p>

 <pre>
 export GOROOT=$HOME/go
 export GOARCH=386
 export GOOS=linux
 </pre>
	<!-- Getting Started -->

	<h2 id="introduction">Introduction</h2>

	<p>Go is an open source project, distributed under a
	<a href="/LICENSE">BSD-style license</a>.
	This document explains how to check out the sources,
	build them on your own machine, and run them.
	</p>

	<div class="detail">

	<p>
	There are two distinct ways to experiment with Go.
	This document focuses on 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="gccgo_install.html">Setting up and using gccgo</a>.
	</p>

	<p>
	The Go compilers support three instruction sets.
	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 most mature 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.
	</dd>
	<dt>
	<code>arm</code> (a.k.a. <code>ARM</code>); <code>5g,5l,5c,5a</code>
	</dt>
	<dd>
	Incomplete.
	It only supports Linux binaries, the optimizer is incomplete,
	and floating point uses the VFP unit.
	However, all tests pass.
	Work on the optimizer is continuing.
	Tested against a Nexus One.
	</dd>
	</dl>

	<p>
	Except for things like low-level operating system interface code, the run-time
	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>
	The compilers can target the FreeBSD, Linux,
	and OS X (a.k.a. Darwin) operating systems.
	(A port to Microsoft Windows is in progress but incomplete. See the
	<a href="http://code.google.com/p/go/wiki/WindowsPort">Windows Port</a>
	page for details.)
	The full set of supported combinations is listed in the discussion of
	<a href="#environment">environment variables</a> below.
	</p>

	</div>

	<h2 id="ctools">Install C tools, if needed</h2>

	<p>The Go tool chain is written in C.
	To build it, you need these programs installed:
	<ul>
	<li>GCC,
	<li>the standard C libraries,
	<li>the parser generator Bison,
	<li><tt>make</tt>,
	<li><tt>awk</tt>, and
	<li>the text editor <tt>ed</tt>.
	</ul>
	</p>

	<p>On OS X, they can be
	installed as part of
	<a href="http://developer.apple.com/TOOLS/Xcode/">Xcode</a>.
	</p>

	<p>On Ubuntu/Debian, use <code>sudo apt-get install bison ed gawk gcc libc6-dev make</code>.
	</p>

	<h2 id="mercurial">Install Mercurial, if needed</h2>

	<p>
	To perform the next step you must have Mercurial installed. (Check that you have an <code>hg</code> command.) This suffices to install Mercurial on most systems:
	</p>
	<pre>
	sudo easy_install mercurial
	</pre>
	(On Ubuntu/Debian, you might try <code>apt-get install python-setuptools
	python-dev build-essential</code> first. The Mercurial in your distribution's
	package repository will most likely be old and broken.)
	</p>
	<p>
	If that fails, try installing manually from the <a href="http://mercurial.selenic.com/wiki/Download">Mercurial Download</a> page.</p>
	</p>

	<p>
	Mercurial versions 1.7.x and up require the configuration of
	<a href="http://mercurial.selenic.com/wiki/CACertificates">Certification Authorities</a>
	(CAs). Error messages of the form:
	</p>
	<pre>
	warning: go.googlecode.com certificate with fingerprint b1:af: ... bc not verified (check hostfingerprints or web.cacerts config setting)
	</pre>
	<p>
	when using Mercurial indicate that the CAs are missing.
	Check your Mercurial version (<code>hg --version</code>) and
	<a href="http://mercurial.selenic.com/wiki/CACertificates#Configuration_of_HTTPS_certificate_authorities">configure the CAs</a>
	if necessary.
	</p>

	<h2 id="fetch">Fetch the repository</h2>

	<p>
	<p>Go will install to a directory named <code>go</code>.
	Change to the directory that will be its parent
	and make sure the <code>go</code> directory does not exist.
	Then check out the repository:</p>

	<pre>
	$ hg clone -r release https://go.googlecode.com/hg/ go
	</pre>

	<h2 id="install">Install Go</h2>

	<p>
	To build the Go distribution, run
	</p>

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

	<p>
	If all goes well, it will finish by printing output like:
	</p>

	<pre>
	ALL TESTS PASSED

	---
	Installed Go for linux/amd64 in /home/you/go.
	Installed commands in /home/you/go/bin.
	* You need to add /home/you/go/bin to your $PATH. *
	The compiler is 6g.
	</pre>

	<p>
	where the details on the last few lines reflect the operating system,
	architecture, and root directory used during the install.
	</p>

	<div class="detail">

	<p>For more information about ways to control the build,
	see the discussion of <a href="#environment">environment variables</a> below.</p>
	</div>

	<h2 id="writing">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 ‘<code>6</code>’ identifies
	files for the <code>amd64</code> architecture.
	The identifier letters for <code>386</code> and <code>arm</code>
	are ‘<code>8</code>’ and ‘<code>5</code>’.
	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 >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
	$
	</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>

	<div class="detail">
	<p>
	To build more complicated programs, you will probably
	want to use a
	<code>Makefile</code>.
	There are examples in places like
	<code>go/src/cmd/godoc/Makefile</code>
	and <code>go/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>
	</div>

	<h2 id="next">What's next</h2>

	<p>
	Start by reading the <a href="go_tutorial.html">Go Tutorial</a>.
	</p>

	<p>
	Build a web application by following the <a href="codelab/wiki/">Wiki
	Codelab</a>.
	</p>

	<p>
	Read <a href="effective_go.html">Effective Go</a> to learn about writing
	idiomatic Go code.
	</p>

	<p>
	For the full story, consult Go's extensive
	<a href="docs.html">documentation</a>.
	</p>

	<h2 id="releases">Keeping up with releases</h2>

	<p>
	The Go project maintains two stable tags in its Mercurial repository:
	<code>release</code> and <code>weekly</code>.
	The <code>weekly</code> tag is updated about once a week, and should be used by
	those who want to track the project's development.
	The <code>release</code> tag is given, less often, to those weekly releases
	that have proven themselves to be robust.
	</p>

	<p>
	Most Go users will want to keep their Go installation at the latest
	<code>release</code> tag.
	New releases are announced on the
	<a href="http://groups.google.com/group/golang-announce">golang-announce</a>
	mailing list.
	</p>

	<p>
	To update an existing tree to the latest release, you can run:
	</p>

	<pre>
	$ cd go/src
	$ hg pull
	$ hg update release
	$ ./all.bash
	</pre>

	<p>
	To use the <code>weekly</code> tag run <code>hg update weekly</code> instead.
	</p>

	<h2 id="community">Community resources</h2>

	<p>
	For real-time help, there may be users or developers on
	<code>#go-nuts</code> on the <a href="http://freenode.net/">Freenode</a> IRC server.
	</p>

	<p>
	The official mailing list for discussion of the Go language is
	<a href="http://groups.google.com/group/golang-nuts">Go Nuts</a>.
	</p>

	<p>
	Bugs can be reported using the <a href="http://code.google.com/p/go/issues/list">Go issue tracker</a>.
	</p>

	<p>
	For those who wish to keep up with development,
	there is another mailing list, <a href="http://groups.google.com/group/golang-checkins">golang-checkins</a>,
	that receives a message summarizing each checkin to the Go repository.
	</p>

	<h2 id="environment">Environment variables</h2>

	<p>
	The Go compilation environment can be customized by environment variables.
	None are required by the build, but you may wish to set them
	to override the defaults.
	</p>

	<dl>
	<dt>
	<code>$GOROOT</code>
	</dt>
	<dd>
	The root of the Go tree, often <code>$HOME/go</code>.
	This defaults to the parent of the directory where <code>all.bash</code> is run.
	If you choose not to set <code>$GOROOT</code>, you must
	run <code>gomake</code> instead of <code>make</code> or <code>gmake</code>
	when developing Go programs using the conventional makefiles.
	</dd>

	<dt>
	<code>$GOROOT_FINAL</code>
	</dt>
	<dd>
	The value assumed by installed binaries and scripts when
	<code>$GOROOT</code> is not set.
	It defaults to the value used for <code>$GOROOT</code>.
	If you want to build the Go tree in one location
	but move it elsewhere after the build, set
	<code>$GOROOT_FINAL</code> to the eventual location.
	</dd>

	<dt>
	<code>$GOOS</code> and <code>$GOARCH</code>
	</dt>
	<dd>
	The name of the target operating system and compilation architecture.
	These default to the values of <code>$GOHOSTOS</code> and
	<code>$GOHOSTARCH</code> respectively (described below).

	<p>
	Choices for <code>$GOOS</code> are <code>linux</code>,
	<code>freebsd</code>,
	<code>darwin</code> (Mac OS X 10.5 or 10.6),
	and <code>windows</code> (Windows, an incomplete port).
	Choices for <code>$GOARCH</code> are <code>amd64</code> (64-bit x86, the most mature port),
	<code>386</code> (32-bit x86), and
	<code>arm</code> (32-bit ARM, an incomplete port).
	The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> are:
	<table cellpadding="0">
	<tr>
	<th width="50"><th align="left" width="100"><code>$GOOS</code></th> <th align="left" width="100"><code>$GOARCH</code></th> <th align="left"></th>
	</tr>
	<tr>
	<td></td><td><code>darwin</code></td> <td><code>386</code></td>
	</tr>
	<tr>
	<td></td><td><code>darwin</code></td> <td><code>amd64</code></td>
	</tr>
	<tr>
	<td></td><td><code>freebsd</code></td> <td><code>386</code></td>
	</tr>
	<tr>
	<td></td><td><code>freebsd</code></td> <td><code>amd64</code></td>
	</tr>
	<tr>
	<td></td><td><code>linux</code></td> <td><code>386</code></td>
	</tr>
	<tr>
	<td></td><td><code>linux</code></td> <td><code>amd64</code></td>
	</tr>
	<tr>
	<td></td><td><code>linux</code></td> <td><code>arm</code></td> <td><i>incomplete</i></td>
	</tr>
	<tr>
	<td></td><td><code>windows</code></td> <td><code>386</code></td> <td><i>incomplete</i></td>
	</tr>
	</table>
	</dd>

	<dt>
	<code>$GOHOSTOS</code> and <code>$GOHOSTARCH</code>
	</dt>
	<dd>
	The name of the host operating system and compilation architecture.
	These default to the local system's operating system and
	architecture.

	<p>
	Valid choices are the same as for <code>$GOOS</code> and
	<code>$GOARCH</code>, listed above.
	The specified values must be compatible with the local system.
	For example, you should not set <code>$GOHOSTARCH</code> to
	<code>arm</code> on an x86 system.
	</dd>

	<dt>
	<code>$GOBIN</code>
	</dt>
	<dd>
	The location where binaries will be installed.
	The default is <code>$GOROOT/bin</code>.
	After installing, you will want to arrange to add this
	directory to your <code>$PATH</code>, so you can use the tools.
	</dd>

	<dt>
	<code>$GOARM</code> (arm, default=6)
	</dt>
	<dd>
	The ARM architecture version the run-time libraries should target.
	ARMv6 cores have more efficient synchronization primitives. Setting
	<code>$GOARM</code> to 5 will compile the run-time libraries using
	just SWP instructions that work on older architectures as well.
	Running v6 code on an older core will cause an illegal instruction trap.
	</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.
	By architecture, we mean the kind of binaries
	that the target environment can run:
	an x86-64 system running a 32-bit-only operating system
	must set <code>GOARCH</code> to <code>386</code>,
	not <code>amd64</code>.
	</p>

	<p>
	If you choose to override the defaults,
	set these variables in your shell profile (<code>$HOME/.bashrc</code>,
	<code>$HOME/.profile</code>, or equivalent). The settings might look
	something like this:
	</p>

	<pre>
	export GOROOT=$HOME/go
	export GOARCH=386
	export GOOS=linux
	</pre>