blob: 7daf360a0f4d57ffb53596a79b92034b6891c106 [file] [log] [blame]
Colin Cross7bb052a2015-02-03 12:59:37 -08001<!--{
2 "Title": "Installing Go from source",
3 "Path": "/doc/install/source"
4}-->
5
6<h2 id="introduction">Introduction</h2>
7
8<p>
9Go is an open source project, distributed under a
10<a href="/LICENSE">BSD-style license</a>.
11This document explains how to check out the sources,
12build them on your own machine, and run them.
13</p>
14
15<p>
16Most users don't need to do this, and will instead install
17from precompiled binary packages as described in
18<a href="/doc/install">Getting Started</a>,
19a much simpler process.
20If you want to help develop what goes into those precompiled
21packages, though, read on.
22</p>
23
24<div class="detail">
25
26<p>
27There are two official Go compiler tool chains.
28This document focuses on the <code>gc</code> Go
29compiler and tools (<code>6g</code>, <code>8g</code> etc.).
30For information on how to work on <code>gccgo</code>, a more traditional
31compiler using the GCC back end, see
32<a href="/doc/install/gccgo">Setting up and using gccgo</a>.
33</p>
34
35<p>
36The Go compilers support three instruction sets.
37There are important differences in the quality of the compilers for the different
38architectures.
39</p>
40
41<dl>
42<dt>
43 <code>amd64</code> (a.k.a. <code>x86-64</code>); <code>6g,6l,6c,6a</code>
44</dt>
45<dd>
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).
49</dd>
50<dt>
51 <code>386</code> (a.k.a. <code>x86</code> or <code>x86-32</code>); <code>8g,8l,8c,8a</code>
52</dt>
53<dd>
54 Comparable to the <code>amd64</code> port.
55</dd>
56<dt>
57 <code>arm</code> (a.k.a. <code>ARM</code>); <code>5g,5l,5c,5a</code>
58</dt>
59<dd>
60 Supports Linux, FreeBSD and NetBSD binaries. Less widely used than the other ports.
61</dd>
62</dl>
63
64<p>
65Except for things like low-level operating system interface code, the run-time
66support is the same in all ports and includes a mark-and-sweep garbage
67collector, efficient array and string slicing, and support for efficient
68goroutines, such as stacks that grow and shrink on demand.
69</p>
70
71<p>
72The compilers can target the DragonFly BSD, FreeBSD, Linux, NetBSD, OpenBSD,
73OS X (Darwin), Plan 9, Solaris and Windows operating systems.
74The full set of supported combinations is listed in the discussion of
75<a href="#environment">environment variables</a> below.
76</p>
77
78</div>
79
80<h2 id="ctools">Install C tools, if needed</h2>
81
82<p>
83The Go tool chain is written in C. To build it, you need a C compiler installed.
84Please refer to the <a href="//golang.org/wiki/InstallFromSource#install-c-tools">InstallFromSource</a>
85page on the Go community Wiki for operating system specific instructions.
86</p>
87
88<h2 id="git">Install Git, if needed</h2>
89
90<p>
91To perform the next step you must have Git installed. (Check that you
92have a <code>git</code> command before proceeding.)
93</p>
94
95<p>
96If you do not have a working Git installation,
97follow the instructions on the
98<a href="http://git-scm.com/downloads">Git downloads</a> page.
99</p>
100
101
102<h2 id="fetch">Fetch the repository</h2>
103
104<p>Go will install to a directory named <code>go</code>.
105Change to the directory that will be its parent
106and make sure the <code>go</code> directory does not exist.
107Then clone the repository and check out the latest release tag:</p>
108
109<pre>
110$ git clone https://go.googlesource.com/go
111$ cd go
112$ git checkout go1.4.1
113</pre>
114
115<h2 id="head">(Optional) Switch to the master branch</h2>
116
117<p>If you intend to modify the go source code, and
118<a href="/doc/contribute.html">contribute your changes</a>
119to the project, then move your repository
120off the release branch, and onto the master (development) branch.
121Otherwise, skip this step.</p>
122
123<pre>
124$ git checkout master
125</pre>
126
127<h2 id="install">Install Go</h2>
128
129<p>
130To build the Go distribution, run
131</p>
132
133<pre>
134$ cd go/src
135$ ./all.bash
136</pre>
137
138<p>
139(To build under Windows use <code>all.bat</code>.)
140</p>
141
142<p>
143If all goes well, it will finish by printing output like:
144</p>
145
146<pre>
147ALL TESTS PASSED
148
149---
150Installed Go for linux/amd64 in /home/you/go.
151Installed commands in /home/you/go/bin.
152*** You need to add /home/you/go/bin to your $PATH. ***
153</pre>
154
155<p>
156where the details on the last few lines reflect the operating system,
157architecture, and root directory used during the install.
158</p>
159
160<div class="detail">
161<p>
162For more information about ways to control the build, see the discussion of
163<a href="#environment">environment variables</a> below.
164<code>all.bash</code> (or <code>all.bat</code>) runs important tests for Go,
165which can take more time than simply building Go. If you do not want to run
166the test suite use <code>make.bash</code> (or <code>make.bat</code>)
167instead.
168</p>
169</div>
170
171
172<h2 id="testing">Testing your installation</h2>
173
174<p>
175Check that Go is installed correctly by building a simple program.
176</p>
177
178<p>
179Create a file named <code>hello.go</code> and put the following program in it:
180</p>
181
182<pre>
183package main
184
185import "fmt"
186
187func main() {
188 fmt.Printf("hello, world\n")
189}
190</pre>
191
192<p>
193Then run it with the <code>go</code> tool:
194</p>
195
196<pre>
197$ go run hello.go
198hello, world
199</pre>
200
201<p>
202If you see the "hello, world" message then Go is installed correctly.
203</p>
204
205<h2 id="gopath">Set up your work environment</h2>
206
207<p>
208You're almost done.
209You just need to do a little more setup.
210</p>
211
212<p>
213<a href="/doc/code.html" class="download" id="start">
214<span class="big">How to Write Go Code</span>
215<span class="desc">Learn how to set up and use the Go tools</span>
216</a>
217</p>
218
219<p>
220The <a href="/doc/code.html">How to Write Go Code</a> document
221provides <b>essential setup instructions</b> for using the Go tools.
222</p>
223
224
225<h2 id="tools">Install additional tools</h2>
226
227<p>
228The source code for several Go tools (including <a href="/cmd/godoc/">godoc</a>)
229is kept in <a href="https://golang.org/x/tools">the go.tools repository</a>.
230To install all of them, run the <code>go</code> <code>get</code> command:
231</p>
232
233<pre>
234$ go get golang.org/x/tools/cmd/...
235</pre>
236
237<p>
238Or if you just want to install a specific command (<code>godoc</code> in this case):
239</p>
240
241<pre>
242$ go get golang.org/x/tools/cmd/godoc
243</pre>
244
245<p>
246To install these tools, the <code>go</code> <code>get</code> command requires
247that <a href="#git">Git</a> be installed locally.
248</p>
249
250<p>
251You must also have a workspace (<code>GOPATH</code>) set up;
252see <a href="/doc/code.html">How to Write Go Code</a> for the details.
253</p>
254
255<p>
256<b>Note</b>: The <code>go</code> command will install the <code>godoc</code>
257binary to <code>$GOROOT/bin</code> (or <code>$GOBIN</code>) and the
258<code>cover</code> and <code>vet</code> binaries to
259<code>$GOROOT/pkg/tool/$GOOS_$GOARCH</code>.
260You can access the latter commands with
261"<code>go</code> <code>tool</code> <code>cover</code>" and
262"<code>go</code> <code>tool</code> <code>vet</code>".
263</p>
264
265<h2 id="community">Community resources</h2>
266
267<p>
268The usual community resources such as
269<code>#go-nuts</code> on the <a href="http://freenode.net/">Freenode</a> IRC server
270and the
271<a href="//groups.google.com/group/golang-nuts">Go Nuts</a>
272mailing list have active developers that can help you with problems
273with your installation or your development work.
274For those who wish to keep up to date,
275there is another mailing list, <a href="//groups.google.com/group/golang-checkins">golang-checkins</a>,
276that receives a message summarizing each checkin to the Go repository.
277</p>
278
279<p>
280Bugs can be reported using the <a href="//golang.org/issue/new">Go issue tracker</a>.
281</p>
282
283
284<h2 id="releases">Keeping up with releases</h2>
285
286<p>
287New releases are announced on the
288<a href="//groups.google.com/group/golang-announce">golang-announce</a>
289mailing list.
290Each announcement mentions the latest release tag, for instance,
291<code>go1.4</code>.
292</p>
293
294<p>
295To update an existing tree to the latest release, you can run:
296</p>
297
298<pre>
299$ cd go/src
300$ git fetch
301$ git checkout <i>&lt;tag&gt;</i>
302$ ./all.bash
303</pre>
304
305Where <code>&lt;tag&gt;</code> is the version string of the release.
306
307
308<h2 id="environment">Optional environment variables</h2>
309
310<p>
311The Go compilation environment can be customized by environment variables.
312<i>None is required by the build</i>, but you may wish to set some
313to override the defaults.
314</p>
315
316<ul>
317<li><code>$GOROOT</code>
318<p>
319The root of the Go tree, often <code>$HOME/go</code>.
320Its value is built into the tree when it is compiled, and
321defaults to the parent of the directory where <code>all.bash</code> was run.
322There is no need to set this unless you want to switch between multiple
323local copies of the repository.
324</p>
325
326<li><code>$GOROOT_FINAL</code>
327<p>
328The value assumed by installed binaries and scripts when
329<code>$GOROOT</code> is not set explicitly.
330It defaults to the value of <code>$GOROOT</code>.
331If you want to build the Go tree in one location
332but move it elsewhere after the build, set
333<code>$GOROOT_FINAL</code> to the eventual location.
334</p>
335
336<li><code>$GOOS</code> and <code>$GOARCH</code>
337<p>
338The name of the target operating system and compilation architecture.
339These default to the values of <code>$GOHOSTOS</code> and
340<code>$GOHOSTARCH</code> respectively (described below).
341
342<p>
343Choices for <code>$GOOS</code> are
344<code>darwin</code> (Mac OS X 10.6 and above), <code>dragonfly</code>, <code>freebsd</code>,
345<code>linux</code>, <code>netbsd</code>, <code>openbsd</code>,
346<code>plan9</code>, <code>solaris</code> and <code>windows</code>.
347Choices for <code>$GOARCH</code> are
348<code>amd64</code> (64-bit x86, the most mature port),
349<code>386</code> (32-bit x86), and <code>arm</code> (32-bit ARM).
350The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> are:
351<table cellpadding="0">
352<tr>
353<th width="50"></th><th align="left" width="100"><code>$GOOS</code></th> <th align="left" width="100"><code>$GOARCH</code></th>
354</tr>
355<tr>
356<td></td><td><code>darwin</code></td> <td><code>386</code></td>
357</tr>
358<tr>
359<td></td><td><code>darwin</code></td> <td><code>amd64</code></td>
360</tr>
361<tr>
362<td></td><td><code>dragonfly</code></td> <td><code>386</code></td>
363</tr>
364<tr>
365<td></td><td><code>dragonfly</code></td> <td><code>amd64</code></td>
366</tr>
367<tr>
368<td></td><td><code>freebsd</code></td> <td><code>386</code></td>
369</tr>
370<tr>
371<td></td><td><code>freebsd</code></td> <td><code>amd64</code></td>
372</tr>
373<tr>
374<td></td><td><code>freebsd</code></td> <td><code>arm</code></td>
375</tr>
376<tr>
377<td></td><td><code>linux</code></td> <td><code>386</code></td>
378</tr>
379<tr>
380<td></td><td><code>linux</code></td> <td><code>amd64</code></td>
381</tr>
382<tr>
383<td></td><td><code>linux</code></td> <td><code>arm</code></td>
384</tr>
385<tr>
386<td></td><td><code>netbsd</code></td> <td><code>386</code></td>
387</tr>
388<tr>
389<td></td><td><code>netbsd</code></td> <td><code>amd64</code></td>
390</tr>
391<tr>
392<td></td><td><code>netbsd</code></td> <td><code>arm</code></td>
393</tr>
394<tr>
395<td></td><td><code>openbsd</code></td> <td><code>386</code></td>
396</tr>
397<tr>
398<td></td><td><code>openbsd</code></td> <td><code>amd64</code></td>
399</tr>
400<tr>
401<td></td><td><code>plan9</code></td> <td><code>386</code></td>
402</tr>
403<tr>
404<td></td><td><code>plan9</code></td> <td><code>amd64</code></td>
405</tr>
406<tr>
407<td></td><td><code>solaris</code></td> <td><code>amd64</code></td>
408</tr>
409<tr>
410<td></td><td><code>windows</code></td> <td><code>386</code></td>
411</tr>
412<tr>
413<td></td><td><code>windows</code></td> <td><code>amd64</code></td>
414</tr>
415</table>
416
417<li><code>$GOHOSTOS</code> and <code>$GOHOSTARCH</code>
418<p>
419The name of the host operating system and compilation architecture.
420These default to the local system's operating system and
421architecture.
422</p>
423
424<p>
425Valid choices are the same as for <code>$GOOS</code> and
426<code>$GOARCH</code>, listed above.
427The specified values must be compatible with the local system.
428For example, you should not set <code>$GOHOSTARCH</code> to
429<code>arm</code> on an x86 system.
430</p>
431
432<li><code>$GOBIN</code>
433<p>
434The location where Go binaries will be installed.
435The default is <code>$GOROOT/bin</code>.
436After installing, you will want to arrange to add this
437directory to your <code>$PATH</code>, so you can use the tools.
438If <code>$GOBIN</code> is set, the <a href="/cmd/go">go command</a>
439installs all commands there.
440</p>
441
442<li><code>$GO386</code> (for <code>386</code> only, default is auto-detected
443if built on either <code>386</code> or <code>amd64</code>, <code>387</code> otherwise)
444<p>
445This controls the code generated by 8g to use either the 387 floating-point unit
446(set to <code>387</code>) or SSE2 instructions (set to <code>sse2</code>) for
447floating point computations.
448</p>
449<ul>
450 <li><code>GO386=387</code>: use x87 for floating point operations; should support all x86 chips (Pentium MMX or later).
451 <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.
452</ul>
453
454<li><code>$GOARM</code> (for <code>arm</code> only; default is auto-detected if building
455on the target processor, 6 if not)
456<p>
457This sets the ARM floating point co-processor architecture version the run-time
458should target. If you are compiling on the target system, its value will be auto-detected.
459</p>
460<ul>
461 <li><code>GOARM=5</code>: use software floating point; when CPU doesn't have VFP co-processor
462 <li><code>GOARM=6</code>: use VFPv1 only; default if cross compiling; usually ARM11 or better cores (VFPv2 or better is also supported)
463 <li><code>GOARM=7</code>: use VFPv3; usually Cortex-A cores
464</ul>
465<p>
466If in doubt, leave this variable unset, and adjust it if required
467when you first run the Go executable.
468The <a href="//golang.org/wiki/GoArm">GoARM</a> page
469on the <a href="//golang.org/wiki">Go community wiki</a>
470contains further details regarding Go's ARM support.
471</p>
472
473</ul>
474
475<p>
476Note that <code>$GOARCH</code> and <code>$GOOS</code> identify the
477<em>target</em> environment, not the environment you are running on.
478In effect, you are always cross-compiling.
479By architecture, we mean the kind of binaries
480that the target environment can run:
481an x86-64 system running a 32-bit-only operating system
482must set <code>GOARCH</code> to <code>386</code>,
483not <code>amd64</code>.
484</p>
485
486<p>
487If you choose to override the defaults,
488set these variables in your shell profile (<code>$HOME/.bashrc</code>,
489<code>$HOME/.profile</code>, or equivalent). The settings might look
490something like this:
491</p>
492
493<pre>
494export GOROOT=$HOME/go
495export GOARCH=amd64
496export GOOS=linux
497</pre>
498
499<p>
500although, to reiterate, none of these variables needs to be set to build,
501install, and develop the Go tree.
502</p>