| <!--{ |
| "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 toolchains. |
| This document focuses on the <code>gc</code> Go |
| compiler and tools. |
| 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 eight instruction sets. |
| There are important differences in the quality of the compilers for the different |
| architectures. |
| </p> |
| |
| <dl> |
| <dt> |
| <code>amd64</code> (also known as <code>x86-64</code>) |
| </dt> |
| <dd> |
| A mature implementation. |
| </dd> |
| <dt> |
| <code>386</code> (<code>x86</code> or <code>x86-32</code>) |
| </dt> |
| <dd> |
| Comparable to the <code>amd64</code> port. |
| </dd> |
| <dt> |
| <code>arm</code> (<code>ARM</code>) |
| </dt> |
| <dd> |
| Supports Linux, FreeBSD, NetBSD, OpenBSD and Darwin binaries. Less widely used than the other ports. |
| </dd> |
| <dt> |
| <code>arm64</code> (<code>AArch64</code>) |
| </dt> |
| <dd> |
| Supports Linux and Darwin binaries. New in 1.5 and not as well exercised as other ports. |
| </dd> |
| <dt> |
| <code>ppc64, ppc64le</code> (64-bit PowerPC big- and little-endian) |
| </dt> |
| <dd> |
| Supports Linux binaries. New in 1.5 and not as well exercised as other ports. |
| </dd> |
| <dt> |
| <code>mips, mipsle</code> (32-bit MIPS big- and little-endian) |
| </dt> |
| <dd> |
| Supports Linux binaries. New in 1.8 and not as well exercised as other ports. |
| </dd> |
| <dt> |
| <code>mips64, mips64le</code> (64-bit MIPS big- and little-endian) |
| </dt> |
| <dd> |
| Supports Linux binaries. New in 1.6 and not as well exercised as other ports. |
| </dd> |
| <dt> |
| <code>s390x</code> (IBM System z) |
| </dt> |
| <dd> |
| Supports Linux binaries. New in 1.7 and not as well exercised as 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 DragonFly BSD, FreeBSD, Linux, NetBSD, OpenBSD, |
| macOS (Darwin), Plan 9, Solaris and Windows operating systems. |
| The full set of supported combinations is listed in the discussion of |
| <a href="#environment">environment variables</a> below. |
| </p> |
| |
| <p> |
| See the main installation page for the <a href="/doc/install#requirements">overall system requirements</a>. |
| The following additional constraints apply to systems that can be built only from source: |
| </p> |
| |
| <ul> |
| <li>For Linux on PowerPC 64-bit, the minimum supported kernel version is 2.6.37, meaning that |
| Go does not support CentOS 6 on these systems. |
| </li> |
| </ul> |
| |
| </div> |
| |
| <h2 id="go14">Install Go compiler binaries</h2> |
| |
| <p> |
| The Go toolchain is written in Go. To build it, you need a Go compiler installed. |
| The scripts that do the initial build of the tools look for an existing Go tool |
| chain in <code>$GOROOT_BOOTSTRAP</code>. |
| If unset, the default value of <code>GOROOT_BOOTSTRAP</code> |
| is <code>$HOME/go1.4</code>. |
| </p> |
| |
| <p> |
| There are many options for the bootstrap toolchain. |
| After obtaining one, set <code>GOROOT_BOOTSTRAP</code> to the |
| directory containing the unpacked tree. |
| For example, <code>$GOROOT_BOOTSTRAP/bin/go</code> should be |
| the <code>go</code> command binary for the bootstrap toolchain. |
| </p> |
| |
| <p> |
| To use a binary release as a bootstrap toolchain, see |
| <a href="/dl/">the downloads page</a> or use any other |
| packaged Go distribution. |
| </p> |
| |
| <p> |
| To build a bootstrap toolchain from source, use |
| either the git branch <code>release-branch.go1.4</code> or |
| <a href="https://dl.google.com/go/go1.4-bootstrap-20171003.tar.gz">go1.4-bootstrap-20171003.tar.gz</a>, |
| which contains the Go 1.4 source code plus accumulated fixes |
| to keep the tools running on newer operating systems. |
| (Go 1.4 was the last distribution in which the toolchain was written in C.) |
| After unpacking the Go 1.4 source, <code>cd</code> to |
| the <code>src</code> subdirectory, set <code>CGO_ENABLED=0</code> in |
| the environment, and run <code>make.bash</code> (or, |
| on Windows, <code>make.bat</code>). |
| </p> |
| |
| <p> |
| To cross-compile a bootstrap toolchain from source, which is |
| necessary on systems Go 1.4 did not target (for |
| example, <code>linux/ppc64le</code>), install Go on a different system |
| and run <a href="/src/bootstrap.bash">bootstrap.bash</a>. |
| </p> |
| |
| <p> |
| When run as (for example) |
| </p> |
| |
| <pre> |
| $ GOOS=linux GOARCH=ppc64 ./bootstrap.bash |
| </pre> |
| |
| <p> |
| <code>bootstrap.bash</code> cross-compiles a toolchain for that <code>GOOS/GOARCH</code> |
| combination, leaving the resulting tree in <code>../../go-${GOOS}-${GOARCH}-bootstrap</code>. |
| That tree can be copied to a machine of the given target type |
| and used as <code>GOROOT_BOOTSTRAP</code> to bootstrap a local build. |
| </p> |
| |
| <p> |
| To use gccgo as the bootstrap toolchain, you need to arrange |
| for <code>$GOROOT_BOOTSTRAP/bin/go</code> to be the go tool that comes |
| as part of gccgo 5. For example on Ubuntu Vivid: |
| </p> |
| |
| <pre> |
| $ sudo apt-get install gccgo-5 |
| $ sudo update-alternatives --set go /usr/bin/go-5 |
| $ GOROOT_BOOTSTRAP=/usr ./make.bash |
| </pre> |
| |
| <h2 id="git">Install Git, if needed</h2> |
| |
| <p> |
| To perform the next step you must have Git installed. (Check that you |
| have a <code>git</code> command before proceeding.) |
| </p> |
| |
| <p> |
| If you do not have a working Git installation, |
| follow the instructions on the |
| <a href="https://git-scm.com/downloads">Git downloads</a> page. |
| </p> |
| |
| <h2 id="ccompiler">(Optional) Install a C compiler</h2> |
| |
| <p> |
| To build a Go installation |
| with <code><a href="/cmd/cgo">cgo</a></code> support, which permits Go |
| programs to import C libraries, a C compiler such as <code>gcc</code> |
| or <code>clang</code> must be installed first. Do this using whatever |
| installation method is standard on the system. |
| </p> |
| |
| <p> |
| To build without <code>cgo</code>, set the environment variable |
| <code>CGO_ENABLED=0</code> before running <code>all.bash</code> or |
| <code>make.bash</code>. |
| </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 clone the repository and check out the latest release tag |
| (<code class="versionTag">go1.9</code>, for example):</p> |
| |
| <pre> |
| $ git clone https://go.googlesource.com/go |
| $ cd go |
| $ git checkout <span class="versionTag"><i><tag></i></span> |
| </pre> |
| |
| <p class="whereTag"> |
| Where <code><tag></code> is the version string of the release. |
| </p> |
| |
| <h2 id="head">(Optional) Switch to the master 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 master (development) branch. |
| Otherwise, skip this step.</p> |
| |
| <pre> |
| $ git checkout master |
| </pre> |
| |
| <h2 id="install">Install Go</h2> |
| |
| <p> |
| To build the Go distribution, run |
| </p> |
| |
| <pre> |
| $ cd 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. |
| <code>all.bash</code> (or <code>all.bat</code>) runs important tests for Go, |
| which can take more time than simply building Go. If you do not want to run |
| the test suite use <code>make.bash</code> (or <code>make.bat</code>) |
| instead. |
| </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> |
| You're almost done. |
| You just need to do a little more setup. |
| </p> |
| |
| <p> |
| <a href="/doc/code.html" class="download" id="start"> |
| <span class="big">How to Write Go Code</span> |
| <span class="desc">Learn how to set up and use the Go tools</span> |
| </a> |
| </p> |
| |
| <p> |
| The <a href="/doc/code.html">How to Write Go Code</a> document |
| provides <b>essential setup instructions</b> for using the Go tools. |
| </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://golang.org/x/tools">the go.tools repository</a>. |
| To install all of them, run the <code>go</code> <code>get</code> command: |
| </p> |
| |
| <pre> |
| $ go get golang.org/x/tools/cmd/... |
| </pre> |
| |
| <p> |
| Or if you just want to install a specific command (<code>godoc</code> in this case): |
| </p> |
| |
| <pre> |
| $ go get golang.org/x/tools/cmd/godoc |
| </pre> |
| |
| <p> |
| To install these tools, the <code>go</code> <code>get</code> command requires |
| that <a href="#git">Git</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="https://freenode.net/">Freenode</a> IRC server |
| and the |
| <a href="//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="//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="//golang.org/issue/new">Go issue tracker</a>. |
| </p> |
| |
| |
| <h2 id="releases">Keeping up with releases</h2> |
| |
| <p> |
| New releases are announced on the |
| <a href="//groups.google.com/group/golang-announce">golang-announce</a> |
| mailing list. |
| Each announcement mentions the latest release tag, for instance, |
| <code class="versionTag">go1.9</code>. |
| </p> |
| |
| <p> |
| To update an existing tree to the latest release, you can run: |
| </p> |
| |
| <pre> |
| $ cd go/src |
| $ git fetch |
| $ git checkout <span class="versionTag"><i><tag></i></psan> |
| $ ./all.bash |
| </pre> |
| |
| <p class="whereTag"> |
| Where <code><tag></code> is the version string of the release. |
| </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> |
| |
| <ul> |
| <li><code>$GOROOT</code> |
| <p> |
| The root of the Go tree, often <code>$HOME/go1.X</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> |
| |
| <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> |
| |
| <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). |
| </li> |
| |
| <p> |
| Choices for <code>$GOOS</code> are |
| <code>darwin</code> (macOS 10.10 and above and iOS), <code>dragonfly</code>, <code>freebsd</code>, |
| <code>linux</code>, <code>netbsd</code>, <code>openbsd</code>, |
| <code>plan9</code>, <code>solaris</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), <code>arm</code> (32-bit ARM), <code>arm64</code> (64-bit ARM), |
| <code>ppc64le</code> (PowerPC 64-bit, little-endian), <code>ppc64</code> (PowerPC 64-bit, big-endian), |
| <code>mips64le</code> (MIPS 64-bit, little-endian), <code>mips64</code> (MIPS 64-bit, big-endian), |
| <code>mipsle</code> (MIPS 32-bit, little-endian), <code>mips</code> (MIPS 32-bit, big-endian), and |
| <code>s390x</code> (IBM System z 64-bit, big-endian). |
| 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>android</code></td> <td><code>arm</code></td> |
| </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>darwin</code></td> <td><code>arm</code></td> |
| </tr> |
| <tr> |
| <td></td><td><code>darwin</code></td> <td><code>arm64</code></td> |
| </tr> |
| <tr> |
| <td></td><td><code>dragonfly</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>linux</code></td> <td><code>arm64</code></td> |
| </tr> |
| <tr> |
| <td></td><td><code>linux</code></td> <td><code>ppc64</code></td> |
| </tr> |
| <tr> |
| <td></td><td><code>linux</code></td> <td><code>ppc64le</code></td> |
| </tr> |
| <tr> |
| <td></td><td><code>linux</code></td> <td><code>mips</code></td> |
| </tr> |
| <tr> |
| <td></td><td><code>linux</code></td> <td><code>mipsle</code></td> |
| </tr> |
| <tr> |
| <td></td><td><code>linux</code></td> <td><code>mips64</code></td> |
| </tr> |
| <tr> |
| <td></td><td><code>linux</code></td> <td><code>mips64le</code></td> |
| </tr> |
| <tr> |
| <td></td><td><code>linux</code></td> <td><code>s390x</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>openbsd</code></td> <td><code>arm</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>solaris</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> |
| <br> |
| |
| <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> |
| </li> |
| |
| <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> |
| |
| <li><code>$GO386</code> (for <code>386</code> only, default is auto-detected |
| if built on either <code>386</code> or <code>amd64</code>, <code>387</code> otherwise) |
| <p> |
| This controls the code generated by gc 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> |
| <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.</li> |
| </ul> |
| </li> |
| |
| <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> |
| <li><code>GOARM=6</code>: use VFPv1 only; default if cross compiling; usually ARM11 or better cores (VFPv2 or better is also supported)</li> |
| <li><code>GOARM=7</code>: use VFPv3; usually Cortex-A cores</li> |
| </ul> |
| <p> |
| If in doubt, leave this variable unset, and adjust it if required |
| when you first run the Go executable. |
| The <a href="//golang.org/wiki/GoArm">GoARM</a> page |
| on the <a href="//golang.org/wiki">Go community wiki</a> |
| contains further details regarding Go's ARM support. |
| </p> |
| </li> |
| |
| <li><code>$GOMIPS</code> (for <code>mips</code> and <code>mipsle</code> only) <br> <code>$GOMIPS64</code> (for <code>mips64</code> and <code>mips64le</code> only) |
| <p> |
| These variables set whether to use floating point instructions. Set to "<code>hardfloat</code>" to use floating point instructions; this is the default. Set to "<code>softfloat</code>" to use soft floating point. |
| </p> |
| </li> |
| |
| </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 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> |