2 "Title": "Installing Go from source",
3 "Path": "/doc/install/source"
6 <h2 id="introduction">Introduction</h2>
9 Go is an open source project, distributed under a
10 <a href="/LICENSE">BSD-style license</a>.
11 This document explains how to check out the sources,
12 build them on your own machine, and run them.
16 Most users don't need to do this, and will instead install
17 from precompiled binary packages as described in
18 <a href="/doc/install">Getting Started</a>,
19 a much simpler process.
20 If you want to help develop what goes into those precompiled
21 packages, though, read on.
27 There are two official Go compiler tool chains.
28 This document focuses on the <code>gc</code> Go
29 compiler and tools (<code>6g</code>, <code>8g</code> etc.).
30 For information on how to work on <code>gccgo</code>, a more traditional
31 compiler using the GCC back end, see
32 <a href="/doc/install/gccgo">Setting up and using gccgo</a>.
36 The Go compilers support three instruction sets.
37 There are important differences in the quality of the compilers for the different
43 <code>amd64</code> (a.k.a. <code>x86-64</code>); <code>6g,6l,6c,6a</code>
46 A mature implementation. The compiler has an effective
47 optimizer (registerizer) and generates good code (although
48 <code>gccgo</code> can do noticeably better sometimes).
51 <code>386</code> (a.k.a. <code>x86</code> or <code>x86-32</code>); <code>8g,8l,8c,8a</code>
54 Comparable to the <code>amd64</code> port.
57 <code>arm</code> (a.k.a. <code>ARM</code>); <code>5g,5l,5c,5a</code>
60 Supports Linux, FreeBSD and NetBSD binaries. Less widely used than the other ports.
65 Except for things like low-level operating system interface code, the run-time
66 support is the same in all ports and includes a mark-and-sweep garbage
67 collector, efficient array and string slicing, and support for efficient
68 goroutines, such as stacks that grow and shrink on demand.
72 The compilers can target the DragonFly BSD, FreeBSD, Linux, NetBSD, OpenBSD,
73 OS X (Darwin), Plan 9, Solaris and Windows operating systems.
74 The full set of supported combinations is listed in the discussion of
75 <a href="#environment">environment variables</a> below.
80 <h2 id="ctools">Install C tools, if needed</h2>
83 The Go tool chain is written in C. To build it, you need a C compiler installed.
84 Please refer to the <a href="//golang.org/wiki/InstallFromSource#Install_C_tools">InstallFromSource</a>
85 page on the Go community Wiki for operating system specific instructions.
88 <h2 id="mercurial">Install Mercurial, if needed</h2>
91 To perform the next step you must have Mercurial installed. (Check that you
92 have an <code>hg</code> command.)
96 If you do not have a working Mercurial installation,
97 follow the instructions on the
98 <a href="http://mercurial.selenic.com/downloads">Mercurial downloads</a> page.
102 Mercurial versions 1.7.x and up require the configuration of
103 <a href="http://mercurial.selenic.com/wiki/CACertificates">Certification Authorities</a>
104 (CAs). Error messages of the form:
108 warning: code.google.com certificate with fingerprint b1:af: ... bc not verified (check hostfingerprints or web.cacerts config setting)
112 when using Mercurial indicate that the CAs are missing.
113 Check your Mercurial version (<code>hg --version</code>) and
114 <a href="http://mercurial.selenic.com/wiki/CACertificates#Configuration_of_HTTPS_certificate_authorities">configure the CAs</a>
119 <h2 id="fetch">Fetch the repository</h2>
121 <p>Go will install to a directory named <code>go</code>.
122 Change to the directory that will be its parent
123 and make sure the <code>go</code> directory does not exist.
124 Then check out the repository:</p>
127 $ hg clone -u release https://code.google.com/p/go
130 <h2 id="head">(Optional) Switch to the default branch</h2>
132 <p>If you intend to modify the go source code, and
133 <a href="/doc/contribute.html">contribute your changes</a>
134 to the project, then move your repository
135 off the release branch, and onto the default (development) branch.
136 Otherwise, skip this step.</p>
142 <h2 id="install">Install Go</h2>
145 To build the Go distribution, run
154 (To build under Windows use <code>all.bat</code>.)
158 If all goes well, it will finish by printing output like:
165 Installed Go for linux/amd64 in /home/you/go.
166 Installed commands in /home/you/go/bin.
167 *** You need to add /home/you/go/bin to your $PATH. ***
171 where the details on the last few lines reflect the operating system,
172 architecture, and root directory used during the install.
177 For more information about ways to control the build, see the discussion of
178 <a href="#environment">environment variables</a> below.
179 <code>all.bash</code> (or <code>all.bat</code>) runs important tests for Go,
180 which can take more time than simply building Go. If you do not want to run
181 the test suite use <code>make.bash</code> (or <code>make.bat</code>)
187 <h2 id="testing">Testing your installation</h2>
190 Check that Go is installed correctly by building a simple program.
194 Create a file named <code>hello.go</code> and put the following program in it:
203 fmt.Printf("hello, world\n")
208 Then run it with the <code>go</code> tool:
217 If you see the "hello, world" message then Go is installed correctly.
220 <h2 id="gopath">Set up your work environment</h2>
224 You just need to do a little more setup.
228 <a href="/doc/code.html" class="download" id="start">
229 <span class="big">How to Write Go Code</span>
230 <span class="desc">Learn how to set up and use the Go tools</span>
235 The <a href="/doc/code.html">How to Write Go Code</a> document
236 provides <b>essential setup instructions</b> for using the Go tools.
240 <h2 id="tools">Install additional tools</h2>
243 The source code for several Go tools (including <a href="/cmd/godoc/">godoc</a>)
244 is kept in <a href="https://code.google.com/p/go.tools">the go.tools repository</a>.
245 To install all of them, run the <code>go</code> <code>get</code> command:
249 $ go get code.google.com/p/go.tools/cmd/...
253 Or if you just want to install a specific command (<code>godoc</code> in this case):
257 $ go get code.google.com/p/go.tools/cmd/godoc
261 To install these tools, the <code>go</code> <code>get</code> command requires
262 that <a href="#mercurial">Mercurial</a> be installed locally.
266 You must also have a workspace (<code>GOPATH</code>) set up;
267 see <a href="/doc/code.html">How to Write Go Code</a> for the details.
271 <b>Note</b>: The <code>go</code> command will install the <code>godoc</code>
272 binary to <code>$GOROOT/bin</code> (or <code>$GOBIN</code>) and the
273 <code>cover</code> and <code>vet</code> binaries to
274 <code>$GOROOT/pkg/tool/$GOOS_$GOARCH</code>.
275 You can access the latter commands with
276 "<code>go</code> <code>tool</code> <code>cover</code>" and
277 "<code>go</code> <code>tool</code> <code>vet</code>".
280 <h2 id="community">Community resources</h2>
283 The usual community resources such as
284 <code>#go-nuts</code> on the <a href="http://freenode.net/">Freenode</a> IRC server
286 <a href="//groups.google.com/group/golang-nuts">Go Nuts</a>
287 mailing list have active developers that can help you with problems
288 with your installation or your development work.
289 For those who wish to keep up to date,
290 there is another mailing list, <a href="//groups.google.com/group/golang-checkins">golang-checkins</a>,
291 that receives a message summarizing each checkin to the Go repository.
295 Bugs can be reported using the <a href="//code.google.com/p/go/issues/list">Go issue tracker</a>.
299 <h2 id="releases">Keeping up with releases</h2>
302 The Go project maintains a stable tag in its Mercurial repository:
303 <code>release</code>.
307 The <code>release</code> tag refers to the current stable release of Go.
308 Most Go users should use this version. New releases are announced on the
309 <a href="//groups.google.com/group/golang-announce">golang-announce</a>
314 To update an existing tree to the latest release, you can run:
325 <h2 id="environment">Optional environment variables</h2>
328 The Go compilation environment can be customized by environment variables.
329 <i>None is required by the build</i>, but you may wish to set some
330 to override the defaults.
334 <li><code>$GOROOT</code>
336 The root of the Go tree, often <code>$HOME/go</code>.
337 Its value is built into the tree when it is compiled, and
338 defaults to the parent of the directory where <code>all.bash</code> was run.
339 There is no need to set this unless you want to switch between multiple
340 local copies of the repository.
343 <li><code>$GOROOT_FINAL</code>
345 The value assumed by installed binaries and scripts when
346 <code>$GOROOT</code> is not set explicitly.
347 It defaults to the value of <code>$GOROOT</code>.
348 If you want to build the Go tree in one location
349 but move it elsewhere after the build, set
350 <code>$GOROOT_FINAL</code> to the eventual location.
353 <li><code>$GOOS</code> and <code>$GOARCH</code>
355 The name of the target operating system and compilation architecture.
356 These default to the values of <code>$GOHOSTOS</code> and
357 <code>$GOHOSTARCH</code> respectively (described below).
360 Choices for <code>$GOOS</code> are
361 <code>darwin</code> (Mac OS X 10.6 and above), <code>dragonfly</code>, <code>freebsd</code>,
362 <code>linux</code>, <code>netbsd</code>, <code>openbsd</code>,
363 <code>plan9</code>, <code>solaris</code> and <code>windows</code>.
364 Choices for <code>$GOARCH</code> are
365 <code>amd64</code> (64-bit x86, the most mature port),
366 <code>386</code> (32-bit x86), and <code>arm</code> (32-bit ARM).
367 The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> are:
368 <table cellpadding="0">
370 <th width="50"></th><th align="left" width="100"><code>$GOOS</code></th> <th align="left" width="100"><code>$GOARCH</code></th>
373 <td></td><td><code>darwin</code></td> <td><code>386</code></td>
376 <td></td><td><code>darwin</code></td> <td><code>amd64</code></td>
379 <td></td><td><code>dragonfly</code></td> <td><code>386</code></td>
382 <td></td><td><code>dragonfly</code></td> <td><code>amd64</code></td>
385 <td></td><td><code>freebsd</code></td> <td><code>386</code></td>
388 <td></td><td><code>freebsd</code></td> <td><code>amd64</code></td>
391 <td></td><td><code>freebsd</code></td> <td><code>arm</code></td>
394 <td></td><td><code>linux</code></td> <td><code>386</code></td>
397 <td></td><td><code>linux</code></td> <td><code>amd64</code></td>
400 <td></td><td><code>linux</code></td> <td><code>arm</code></td>
403 <td></td><td><code>netbsd</code></td> <td><code>386</code></td>
406 <td></td><td><code>netbsd</code></td> <td><code>amd64</code></td>
409 <td></td><td><code>netbsd</code></td> <td><code>arm</code></td>
412 <td></td><td><code>openbsd</code></td> <td><code>386</code></td>
415 <td></td><td><code>openbsd</code></td> <td><code>amd64</code></td>
418 <td></td><td><code>plan9</code></td> <td><code>386</code></td>
421 <td></td><td><code>plan9</code></td> <td><code>amd64</code></td>
424 <td></td><td><code>solaris</code></td> <td><code>amd64</code></td>
427 <td></td><td><code>windows</code></td> <td><code>386</code></td>
430 <td></td><td><code>windows</code></td> <td><code>amd64</code></td>
434 <li><code>$GOHOSTOS</code> and <code>$GOHOSTARCH</code>
436 The name of the host operating system and compilation architecture.
437 These default to the local system's operating system and
442 Valid choices are the same as for <code>$GOOS</code> and
443 <code>$GOARCH</code>, listed above.
444 The specified values must be compatible with the local system.
445 For example, you should not set <code>$GOHOSTARCH</code> to
446 <code>arm</code> on an x86 system.
449 <li><code>$GOBIN</code>
451 The location where Go binaries will be installed.
452 The default is <code>$GOROOT/bin</code>.
453 After installing, you will want to arrange to add this
454 directory to your <code>$PATH</code>, so you can use the tools.
455 If <code>$GOBIN</code> is set, the <a href="/cmd/go">go command</a>
456 installs all commands there.
459 <li><code>$GO386</code> (for <code>386</code> only, default is auto-detected
460 if built on either <code>386</code> or <code>amd64</code>, <code>387</code> otherwise)
462 This controls the code generated by 8g to use either the 387 floating-point unit
463 (set to <code>387</code>) or SSE2 instructions (set to <code>sse2</code>) for
464 floating point computations.
467 <li><code>GO386=387</code>: use x87 for floating point operations; should support all x86 chips (Pentium MMX or later).
468 <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.
471 <li><code>$GOARM</code> (for <code>arm</code> only; default is auto-detected if building
472 on the target processor, 6 if not)
474 This sets the ARM floating point co-processor architecture version the run-time
475 should target. If you are compiling on the target system, its value will be auto-detected.
478 <li><code>GOARM=5</code>: use software floating point; when CPU doesn't have VFP co-processor
479 <li><code>GOARM=6</code>: use VFPv1 only; default if cross compiling; usually ARM11 or better cores (VFPv2 or better is also supported)
480 <li><code>GOARM=7</code>: use VFPv3; usually Cortex-A cores
483 If in doubt, leave this variable unset, and adjust it if required
484 when you first run the Go executable.
485 The <a href="//golang.org/wiki/GoArm">GoARM</a> page
486 on the <a href="//golang.org/wiki">Go community wiki</a>
487 contains further details regarding Go's ARM support.
493 Note that <code>$GOARCH</code> and <code>$GOOS</code> identify the
494 <em>target</em> environment, not the environment you are running on.
495 In effect, you are always cross-compiling.
496 By architecture, we mean the kind of binaries
497 that the target environment can run:
498 an x86-64 system running a 32-bit-only operating system
499 must set <code>GOARCH</code> to <code>386</code>,
500 not <code>amd64</code>.
504 If you choose to override the defaults,
505 set these variables in your shell profile (<code>$HOME/.bashrc</code>,
506 <code>$HOME/.profile</code>, or equivalent). The settings might look
511 export GOROOT=$HOME/go
517 although, to reiterate, none of these variables needs to be set to build,
518 install, and develop the Go tree.