diff options
Diffstat (limited to 'doc/install.html')
| -rw-r--r-- | doc/install.html | 474 |
1 files changed, 474 insertions, 0 deletions
diff --git a/doc/install.html b/doc/install.html new file mode 100644 index 000000000..a1bc89982 --- /dev/null +++ b/doc/install.html @@ -0,0 +1,474 @@ +<!-- 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>GNU <tt>make</tt> (version 3.81 or later), +and +<li><tt>awk</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 gawk gcc libc6-dev +make</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> + +<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 -u 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> |