| <!--{ |
| "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 Linux, FreeBSD and NetBSD binaries. Less widely used than the other ports. |
| </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), Plan 9, |
| 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. |
| Please refer to the <a href="http://code.google.com/p/go-wiki/wiki/InstallFromSource#Install_C_tools">InstallFromSource</a> |
| page on the Go community Wiki for operating system specific instructions. |
| </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.) |
| </p> |
| |
| <p> |
| If you do not have a working Mercurial installation, |
| follow the instructions on the |
| <a href="http://mercurial.selenic.com/downloads/">Mercurial downloads</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="head">(Optional) Switch to the default branch</h2> |
| |
| <p>If you intend to modify the go source code, and |
| <a href="/doc/contribute.html">contribute your changes</a> |
| to the project, then move your repository |
| off the release branch, and onto the default (development) branch. |
| Otherwise, skip this step.</p> |
| |
| <pre> |
| $ hg update default |
| </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. *** |
| </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="gopath">Set up your work environment</h2> |
| |
| <p> |
| The document <a href="/doc/code.html">How to Write Go Code</a> explains how to |
| set up a work environment in which to build and test Go code. |
| </p> |
| |
| <h2 id="tools">Install additional tools</h2> |
| |
| <p> |
| The source code for several Go tools (including <a href="/cmd/godoc/">godoc</a>) |
| is kept in <a href="https://code.google.com/p/go.tools">the go.tools repository</a>. |
| To install all of them, run the <code>go</code> <code>get</code> command: |
| </p> |
| |
| <pre> |
| $ go get code.google.com/p/go.tools/cmd/... |
| </pre> |
| |
| <p> |
| Or if you just want to install a specific command (<code>godoc</code> in this case): |
| </p> |
| |
| <pre> |
| $ go get code.google.com/p/go.tools/cmd/godoc |
| </pre> |
| |
| <p> |
| To install these tools, the <code>go</code> <code>get</code> command requires |
| that <a href="#mercurial">Mercurial</a> be installed locally. |
| </p> |
| |
| <p> |
| You must also have a workspace (<code>GOPATH</code>) set up; |
| see <a href="/doc/code.html">How to Write Go Code</a> for the details. |
| </p> |
| |
| <p> |
| <b>Note</b>: The <code>go</code> command will install the <code>godoc</code> |
| binary to <code>$GOROOT/bin</code> (or <code>$GOBIN</code>) and the |
| <code>cover</code> and <code>vet</code> binaries to |
| <code>$GOROOT/pkg/tool/$GOOS_$GOARCH</code>. |
| You can access the latter commands with |
| "<code>go</code> <code>tool</code> <code>cover</code>" and |
| "<code>go</code> <code>tool</code> <code>vet</code>". |
| </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 a stable tag in its Mercurial repository: |
| <code>release</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> |
| |
| |
| <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> |
| |
| <ul> |
| <li><code>$GOROOT</code> |
| <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> |
| |
| <li><code>$GOROOT_FINAL</code> |
| <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> |
| |
| <li><code>$GOOS</code> and <code>$GOARCH</code> |
| <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><th align="left" width="100"><code>$GOOS</code></th> <th align="left" width="100"><code>$GOARCH</code></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>freebsd</code></td> <td><code>arm</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>netbsd</code></td> <td><code>arm</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>plan9</code></td> <td><code>amd64</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> |
| |
| <li><code>$GOHOSTOS</code> and <code>$GOHOSTARCH</code> |
| <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> |
| |
| <li><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> |
| |
| <li><code>$GO386</code> (for <code>386</code> only, default is auto-detected |
| if built natively, <code>387</code> if not) |
| <p> |
| This controls the code generated by 8g to use either the 387 floating-point unit |
| (set to <code>387</code>) or SSE2 instructions (set to <code>sse2</code>) for |
| floating point computations. |
| </p> |
| <ul> |
| <li><code>GO386=387</code>: use x87 for floating point operations; should support all x86 chips (Pentium MMX or later). |
| <li><code>GO386=sse2</code>: use SSE2 for floating point operations; has better performance than 387, but only available on Pentium 4/Opteron/Athlon 64 or later. |
| </ul> |
| |
| <li><code>$GOARM</code> (for <code>arm</code> only; default is auto-detected if building |
| on the target processor, 6 if not) |
| <p> |
| This sets the ARM floating point co-processor architecture version the run-time |
| should target. If you are compiling on the target system, its value will be auto-detected. |
| </p> |
| <ul> |
| <li><code>GOARM=5</code>: use software floating point; when CPU doesn't have VFP co-processor |
| <li><code>GOARM=6</code>: use VFPv1 only; default if cross compiling; usually ARM11 or better cores (VFPv2 or better is also supported) |
| <li><code>GOARM=7</code>: use VFPv3; usually Cortex-A cores |
| </ul> |
| <p> |
| If in doubt, leave this variable unset, and adjust it if required |
| when you first run the Go executable. |
| The <a href="http://code.google.com/p/go-wiki/wiki/GoArm">GoARM</a> page |
| on the <a href="http://code.google.com/p/go-wiki/w/list">Go community wiki</a> |
| contains further details regarding Go's ARM support. |
| </p> |
| |
| </ul> |
| |
| <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> |