Imported Upstream version 1upstream/1

1 files changed, 441 insertions, 0 deletions

diff --git a/doc/install-source.html b/doc/install-source.html
new file mode 100644
index 000000000..4673850f4
--- /dev/null
+++ b/doc/install-source.html
@@ -0,0 +1,441 @@
+<!--{
+	"Title": "Installing Go from source",
+	"Path": "/doc/install/source"
+}-->
+
+<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>
+
+<p>
+Most users don't need to do this, and will instead install
+from precompiled binary packages as described in
+<a href="/doc/install">Getting Started</a>,
+a much simpler process.
+If you want to help develop what goes into those precompiled
+packages, though, read on.
+</p>
+
+<div class="detail">
+
+<p>
+There are two official Go compiler tool chains.
+This document focuses on the <code>gc</code> Go
+compiler and tools (<code>6g</code>, <code>8g</code> etc.).
+For information on how to work on <code>gccgo</code>, a more traditional
+compiler using the GCC back end, see
+<a href="/doc/install/gccgo">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>
+	A 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>
+	Supports only Linux binaries. Less widely used than the other ports and therefore
+	not as thoroughly tested.
+</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, efficient array and string slicing, and support for efficient
+goroutines, such as stacks that grow and shrink on demand.
+</p>
+
+<p>
+The compilers can target the FreeBSD, Linux, NetBSD, OpenBSD, OS X (Darwin),
+and Windows operating systems.
+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 a C compiler installed.
+</p>
+
+<p>
+On OS X, a C compiler can be installed as part of
+<a href="http://developer.apple.com/Xcode/">Xcode</a>. 
+</p>
+
+<p>
+On Ubuntu/Debian, use <code>sudo apt-get install gcc libc6-dev</code>.
+If you want to build 32-bit binaries on a 64-bit system you'll also need the
+<code>libc6-dev-i386</code> package.
+</p>
+
+<p>
+On Windows, install <code>gcc</code> with
+<a href="http://www.mingw.org/">MinGW</a>.
+(Make sure you add its <code>bin</code> subdirectory to your <code>PATH</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
+Unix systems:
+</p>
+
+<pre>
+sudo easy_install mercurial==2.0
+</pre>
+
+<p>
+On Ubuntu/Debian, the Mercurial in your distribution's
+package repository is most likely old and broken.
+You might try this first:
+</p>
+
+<pre>apt-get install python-setuptools python-dev build-essential</pre>
+
+<p>
+If that fails, or if you use Windows, install manually from the
+<a href="http://mercurial.selenic.com/wiki/Download">Mercurial Download</a>
+page.
+</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: code.google.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>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 -u release https://code.google.com/p/go
+</pre>
+
+<h2 id="install">Install Go</h2>
+
+<p>
+To build the Go distribution, run
+</p>
+
+<pre>
+$ cd go/src
+$ ./all.bash
+</pre>
+
+<p>
+(To build under Windows use <code>all.bat</code>.)
+</p>
+
+<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="testing">Testing your installation</h2>
+
+<p>
+Check that Go is installed correctly by building a simple program.
+</p>
+
+<p>
+Create a file named <code>hello.go</code> and put the following program in it:
+</p>
+
+<pre>
+package main
+
+import "fmt"
+
+func main() {
+    fmt.Printf("hello, world\n")
+}
+</pre>
+
+<p>
+Then run it with the <code>go</code> tool:
+</p>
+
+<pre>
+$ go run hello.go
+hello, world
+</pre>
+
+<p>
+If you see the "hello, world" message then Go is installed correctly.
+</p>
+
+
+<h2 id="community">Community resources</h2>
+
+<p>
+The usual community resources such as
+<code>#go-nuts</code> on the <a href="http://freenode.net/">Freenode</a> IRC server
+and the
+<a href="http://groups.google.com/group/golang-nuts">Go Nuts</a>
+mailing list have active developers that can help you with problems
+with your installation or your development work.
+For those who wish to keep up to date,
+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>
+
+<p>
+Bugs can be reported using the <a href="http://code.google.com/p/go/issues/list">Go issue tracker</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>.
+</p>
+
+<p>
+The <code>release</code> tag refers to the current stable release of Go.
+Most Go users should use this version. 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>
+The <code>weekly</code> tag is updated about once a week, and should be used 
+only by those who are actively working on the Go core.
+To use the <code>weekly</code> tag run <code>hg update weekly</code> instead.
+</p>
+
+
+<h2 id="environment">Optional environment variables</h2>
+
+<p>
+The Go compilation environment can be customized by environment variables.
+<i>None is required by the build</i>, but you may wish to set some
+to override the defaults.
+</p>
+
+<blockquote>
+
+<p><code>$GOROOT</code></p>
+<p>
+The root of the Go tree, often <code>$HOME/go</code>.
+Its value is built into the tree when it is compiled, and
+defaults to the parent of the directory where <code>all.bash</code> was run.
+There is no need to set this unless you want to switch between multiple
+local copies of the repository.
+</p>
+
+<p><code>$GOROOT_FINAL</code></p>
+<p>
+The value assumed by installed binaries and scripts when
+<code>$GOROOT</code> is not set explicitly.
+It defaults to the value of <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.
+</p>
+
+<p><code>$GOOS</code> and <code>$GOARCH</code></p>
+<p>
+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>darwin</code> (Mac OS X 10.6 and above), <code>freebsd</code>,
+<code>linux</code>, <code>netbsd</code>, <code>openbsd</code>, 
+<code>plan9</code>, and <code>windows</code>.
+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).
+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>
+</tr>
+<tr>
+<td></td><td><code>netbsd</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>netbsd</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>openbsd</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>openbsd</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>plan9</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>windows</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>windows</code></td> <td><code>amd64</code></td>
+</tr>
+</table>
+
+<p><code>$GOHOSTOS</code> and <code>$GOHOSTARCH</code></p>
+<p>
+The name of the host operating system and compilation architecture.
+These default to the local system's operating system and
+architecture.
+</p>
+
+<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.
+</p>
+
+<p><code>$GOBIN</code>
+<p>
+The location where Go 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.
+If <code>$GOBIN</code> is set, the <a href="/cmd/go">go command</a>
+installs all commands there.
+</p>
+
+<p><code>$GOARM</code> (arm, default=6)</p>
+<p>
+The ARM architecture version the run-time libraries should target.
+Setting <code>$GOARM</code> to 5 causes the linker to emit calls
+to a software floating point implementation instead of using
+hardware floating point support.
+</p>
+
+</blockquote>
+
+<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=amd64
+export GOOS=linux
+</pre>
+
+<p>
+although, to reiterate, none of these variables needs to be set to build,
+install, and develop the Go tree.
+</p>