| <!-- 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 not enabled, |
| and floating point is performed entirely in software. |
| However, all tests pass. |
| Work on the optimizer and use of the VFP hardware |
| floating point unit is underway. |
| Tested against a Nexus One. |
| </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> |
| 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> |
| |
| <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> |
| --- cd ../test |
| N known bugs; 0 unexpected bugs |
| |
| --- |
| 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 <var>N</var> is a number that varies from release to release |
| and the details on the last few lines will 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>New releases are announced on the <a href="http://groups.google.com/group/golang-nuts">Go Nuts</a> mailing list. |
| 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> |
| |
| <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 runtime libraries should target. |
| ARMv6 cores have more efficient synchronization primitives. Setting |
| <code>$GOARM</code> to 5 will compile the runtime 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> |