Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(1307)

Side by Side Diff: doc/install.html

Issue 2025041: code review 2025041: build: update, streamline documentation for new $GOBIN (Closed)
Patch Set: code review 2025041: build: update, streamline documentation for new $GOBIN Created 13 years, 7 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « README ('k') | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 <!-- Installing Go --> 1 <!-- Installing Go -->
2 2
3 <h2>Introduction</h2> 3 <h2 id="introduction">Introduction</h2>
4 4
5 <p>Go is an open source project, distributed under a 5 <p>Go is an open source project, distributed under a
6 <a href="/LICENSE">BSD-style license</a>. 6 <a href="/LICENSE">BSD-style license</a>.
7 This document explains how to check out the sources, 7 This document explains how to check out the sources,
8 build them on your own machine, and run them. 8 build them on your own machine, and run them.
9 </p> 9 </p>
10 10
11 <p> 11 <p>
12 There are two distinct ways to experiment with Go. 12 There are two distinct ways to experiment with Go.
13 This document focuses on the <code>gc</code> Go 13 This document focuses on the <code>gc</code> Go
14 compiler and tools (<code>6g</code>, <code>8g</code> etc.). 14 compiler and tools (<code>6g</code>, <code>8g</code> etc.).
15 For information on how to use <code>gccgo</code>, a more traditional 15 For information on how to use <code>gccgo</code>, a more traditional
16 compiler using the GCC back end, see 16 compiler using the GCC back end, see
17 <a href="gccgo_install.html">Setting up and using gccgo</a>. 17 <a href="gccgo_install.html">Setting up and using gccgo</a>.
18 </p> 18 </p>
19 19
20 <h2>Environment variables</h2>
21
22 <p>
23 The Go compilation environment can be customized by five environment variables.
24 None are required by the build, but you may wish to set them
25 to override the defaults.
26 </p>
27
28 <dl>
29 <dt>
30 <code>$GOROOT</code>
31 </dt>
32 <dd>
33 The root of the Go tree, often <code>$HOME/go</code>.
34 This defaults to the parent of the directory where <code>all.bash</code> is run.
35 Although this variable is optional, the examples and typescripts below
36 use it as shorthand for the location where you installed Go.
37 If you choose not to set <code>$GOROOT</code>, you must
38 run <code>gomake</code> instead of <code>make</code> or <code>gmake</cod e>
39 when developing Go programs using the conventional makefiles.
40 </dd>
41
42 <dt>
43 <code>$GOROOT_FINAL</code>
44 </dt>
45 <dd>
46 The value assumed by installed binaries and scripts when
47 <code>$GOROOT</code> is not set.
48 It defaults to the value used for <code>$GOROOT</code>.
49 If you want to build the Go tree in one location
50 but move it elsewhere after the build, set·
51 <code>$GOROOT_FINAL</code> to the eventual location.
52 </dd>
53
54 <dt>
55 <code>$GOOS</code> and <code>$GOARCH</code>
56 </dt>
57 <dd>
58 The name of the target operating system and compilation architecture.
59 These default to the local system's operating system and
60 architecture.
61
62 <p>
63 Choices for <code>$GOOS</code> are <code>linux</code>,
64 <code>freebsd</code>,
65 <code>darwin</code> (Mac OS X 10.5 or 10.6),
66 and <code>nacl</code> (Native Client, an incomplete port).
67 Choices for <code>$GOARCH</code> are <code>amd64</code> (64-bit x86, the most mature port),
68 <code>386</code> (32-bit x86), and
69 <code>arm</code> (32-bit ARM, an incomplete port).
70 The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> ar e:
71 <p>
72 <table cellpadding="0">
73 <tr>
74 <th width="50"><th align="left" width="100"><code>$GOOS</code></th> <th align="left" width="100"><code>$GOARCH</code></th>
75 </tr>
76 <tr>
77 <td></td><td><code>darwin</code></td> <td><code>386</code></td>
78 </tr>
79 <tr>
80 <td></td><td><code>darwin</code></td> <td><code>amd64</code></td>
81 </tr>
82 <tr>
83 <td></td><td><code>freebsd</code></td> <td><code>386</code></td>
84 </tr>
85 <tr>
86 <td></td><td><code>freebsd</code></td> <td><code>amd64</code></td>
87 </tr>
88 <tr>
89 <td></td><td><code>linux</code></td> <td><code>386</code></td>
90 </tr>
91 <tr>
92 <td></td><td><code>linux</code></td> <td><code>amd64</code></td>
93 </tr>
94 <tr>
95 <td></td><td><code>linux</code></td> <td><code>arm</code></td>
96 </tr>
97 <tr>
98 <td></td><td><code>nacl</code></td> <td><code>386</code></td>
99 </tr>
100 </table>
101 </dd>
102
103 <dt>
104 <code>$GOBIN</code>
105 </dt>
106 <dd>
107 The location where binaries will be installed.
108 The default is <code>$HOME/bin</code>.
109 After installing, you will want to arrange to add this
110 directory to your <code>$PATH</code>, so you can use the tools.
111 </dd>
112
113 <dt>
114 <code>$GOARM</code> (arm, default=6)
115 </dt>
116 <dd>
117 The ARM architecture version the runtime libraries should target.
118 ARMv6 cores have more efficient synchronization primitives. Setting
119 <code>$GOARM</code> to 5 will compile the runtime libraries using
120 just SWP instructions that work on older architectures as well.
121 Running v6 code on an older core will cause an illegal instruction trap.
122 </dd>
123 </dl>
124
125 <p>
126 Note that <code>$GOARCH</code> and <code>$GOOS</code> identify the
127 <em>target</em> environment, not the environment you are running on.
128 In effect, you are always cross-compiling.
129 By architecture, we mean the kind of binaries
130 that the target environment can run:
131 an x86-64 system running a 32-bit-only operating system
132 must set <code>GOARCH</code> to <code>386</code>,
133 not <code>amd64</code>.
134 </p>
135
136 <p>
137 If you choose to override the defaults,
138 set these variables in your shell profile (<code>$HOME/.bashrc</code>,
139 <code>$HOME/.profile</code>, or equivalent). The settings might look·
140 something like this:
141 </p>
142
143 <pre>
144 export GOROOT=$HOME/go
145 export GOARCH=amd64 # optional
146 export GOOS=linux # optional
147 </pre>
148
149 <p>
150 Double-check them by listing your environment. (You will need to launch
151 a new shell or terminal window for the changes to take effect.)
152 </p>
153
154 <pre>
155 $ env | grep '^GO'
156 </pre>
157
158 <h2>Ports</h2>
159
160 <p> 20 <p>
161 The Go compilers support three instruction sets. 21 The Go compilers support three instruction sets.
162 There are important differences in the quality of the compilers for the differen t 22 There are important differences in the quality of the compilers for the differen t
163 architectures. 23 architectures.
164 </p> 24 </p>
165 25
166 <dl> 26 <dl>
167 <dt> 27 <dt>
168 <code>amd64</code> (a.k.a. <code>x86-64</code>); <code>6g,6l,6c,6a</code > 28 <code>amd64</code> (a.k.a. <code>x86-64</code>); <code>6g,6l,6c,6a</code >
169 </dt> 29 </dt>
170 <dd> 30 <dd>
171 The most mature implementation. The compiler has an effective optimizer 31 The most mature implementation. The compiler has an effective optimizer
172 (registerizer) and generates good code (although <code>gccgo</code> 32 (registerizer) and generates good code (although <code>gccgo</code>
173 can do noticeably better sometimes). 33 can do noticeably better sometimes).
174 </dd> 34 </dd>
175 <dt> 35 <dt>
176 <code>386</code> (a.k.a. <code>x86</code> or <code>x86-32</code>); <code >8g,8l,8c,8a</code> 36 <code>386</code> (a.k.a. <code>x86</code> or <code>x86-32</code>); <code >8g,8l,8c,8a</code>
177 </dt> 37 </dt>
178 <dd> 38 <dd>
179 » Comparable to the <code>amd64</code> port. Not as well soaked but 39 » Comparable to the <code>amd64</code> port.
180 » should be nearly as solid.
181
182 </dd> 40 </dd>
183 <dt> 41 <dt>
184 <code>arm</code> (a.k.a. <code>ARM</code>); <code>5g,5l,5c,5a</code> 42 <code>arm</code> (a.k.a. <code>ARM</code>); <code>5g,5l,5c,5a</code>
185 </dt> 43 </dt>
186 <dd> 44 <dd>
187 » It's got a couple of outstanding bugs but is improving. 45 » Still a work in progress.
46 » It only supports Linux binaries, floating point is weak, and the
47 » optimizer is not enabled.
188 Tested against QEMU and an android phone. 48 Tested against QEMU and an android phone.
189 Only supports Linux binaries.
190 </dd> 49 </dd>
191 </dl> 50 </dl>
192 51
193 <p> 52 <p>
194 Except for things like low-level operating system interface code, the runtime 53 Except for things like low-level operating system interface code, the runtime
195 support is the same in all ports and includes a mark-and-sweep garbage collector 54 support is the same in all ports and includes a mark-and-sweep garbage collector
196 (a fancier one is in the works), efficient array and string slicing, 55 (a fancier one is in the works), efficient array and string slicing,
197 support for segmented stacks, and a strong goroutine implementation. 56 support for segmented stacks, and a strong goroutine implementation.
198 </p> 57 </p>
199 58
200 <p> 59 <p>
201 See the separate <a href="gccgo_install.html"><code>gccgo</code> document</a> 60 The compilers can target the FreeBSD, Linux, Native Client,
202 for details about that compiler and environment. 61 and OS X (a.k.a. Darwin) operating systems.
62 (A port to Microsoft Windows is in progress but incomplete.)
63 The full set of supported combinations is listed in the discussion of
64 <a href="#environment">environment variables</a> below.
203 </p> 65 </p>
204 66
205 <h2>Install C tools, if needed</h2> 67 <h2 id="ctools">Install C tools, if needed</h2>
206 68
207 <p>The Go tool chain is written in C. To build it, you need 69 <p>The Go tool chain is written in C. To build it, you need
208 to have GCC, the standard C libraries, the parser generator Bison, 70 to have GCC, the standard C libraries, the parser generator Bison,
209 <tt>make</tt>, <tt>awk</tt>, and the text editor <tt>ed</tt> installed. On OS X , they can be 71 <tt>make</tt>, <tt>awk</tt>, and the text editor <tt>ed</tt> installed.
210 installed as part of
211 <a href="http://developer.apple.com/TOOLS/Xcode/">Xcode</a>. On Linux, use
212 </p> 72 </p>
213 73
214 <pre> 74 <p>On OS X, they can be
215 $ sudo apt-get install bison gcc libc6-dev ed gawk make 75 installed as part of
216 </pre> 76 <a href="http://developer.apple.com/TOOLS/Xcode/">Xcode</a>.·
77 </p>
217 78
218 <p> 79 <p>On Linux, use <code>sudo apt-get install bison ed gawk gcc libc6-dev make</co de>
219 (or the equivalent on your Linux distribution). 80 (or the equivalent on your Linux distribution).
220 </p> 81 </p>
221 82
222 <h2>Fetch the repository</h2> 83 <h2 id="fetch">Fetch the repository</h2>
223 84
224 <p> 85 <p>
225 If you do not have Mercurial installed (you do not have an <code>hg</code> comma nd), 86 If you do not have Mercurial installed (you do not have an <code>hg</code> comma nd),
226 this command: 87 <code>sudo easy_install mercurial</code> works on most systems.
227 </p>
228
229 <pre>
230 $ sudo easy_install mercurial
231 </pre>
232
233 <p>works on most systems.
234 (On Ubuntu/Debian, you might try <code>apt-get install python-setuptools python- dev build-essential gcc</code> first.) 88 (On Ubuntu/Debian, you might try <code>apt-get install python-setuptools python- dev build-essential gcc</code> first.)
235 If that fails, visit the <a href="http://mercurial.selenic.com/wiki/Download">Me rcurial Download</a> page.</p> 89 If that fails, visit the <a href="http://mercurial.selenic.com/wiki/Download">Me rcurial Download</a> page.</p>
236 90
237 <p>Make sure the <code>$GOROOT</code> directory does not exist or is empty. 91 <p>Go will install to a directory named <code>go</code>.
92 Change to the directory that will be its parent
93 and make sure the <code>go</code> directory does not exist.
238 Then check out the repository:</p> 94 Then check out the repository:</p>
239 95
240 <pre> 96 <pre>
241 $ hg clone -r release https://go.googlecode.com/hg/ $GOROOT 97 $ hg clone -r release https://go.googlecode.com/hg/ go
242 </pre> 98 </pre>
243 99
244 <h2>Install Go</h2> 100 <h2 id="install">Install Go</h2>
245 101
246 <p> 102 <p>
247 To build the Go distribution, run 103 To build the Go distribution, run
248 </p> 104 </p>
249 105
250 <pre> 106 <pre>
251 $ cd $GOROOT/src 107 $ cd go/src
252 $ ./all.bash 108 $ ./all.bash
253 </pre> 109 </pre>
254 110
255 <p> 111 <p>
256 If all goes well, it will finish by printing output like: 112 If all goes well, it will finish by printing output like:
257 </p> 113 </p>
258 114
259 <pre> 115 <pre>
260 --- cd ../test 116 --- cd ../test
261 N known bugs; 0 unexpected bugs 117 N known bugs; 0 unexpected bugs
262 118
263 --- 119 ---
264 Installed Go for darwin/amd64 in /Users/you/go; the compiler is 6g. 120 Installed Go for linux/amd64 in /home/you/go.
121 Installed commands in /home/you/go/bin.
122 *** You need to add /home/you/go/bin to your $PATH. ***
123 The compiler is 6g.
265 </pre> 124 </pre>
266 125
267 <p> 126 <p>
268 where <var>N</var> is a number that varies from release to release 127 where <var>N</var> is a number that varies from release to release
269 and the details on the last line will reflect the operating system, 128 and the details on the last few lines will reflect the operating system,
270 architecture, and root directory used during the install. 129 architecture, and root directory used during the install.
271 </p> 130 </p>
272 131
273 <h2>Writing programs</h2> 132 <p>For more information about ways to control the build,
133 see the discussion of <a href="#environment">environment variables</a> below.</p >
134
135 <h2 id="writing">Writing programs</h2>
274 136
275 <p> 137 <p>
276 Given a file <code>file.go</code>, compile it using 138 Given a file <code>file.go</code>, compile it using
277 </p> 139 </p>
278 140
279 <pre> 141 <pre>
280 $ 6g file.go 142 $ 6g file.go
281 </pre> 143 </pre>
282 144
283 <p> 145 <p>
(...skipping 47 matching lines...) Expand 10 before | Expand all | Expand 10 after
331 (in this case, package <code>fmt</code>) on the <code>6l</code> 193 (in this case, package <code>fmt</code>) on the <code>6l</code>
332 command line. 194 command line.
333 The linker learns about them by reading <code>hello.6</code>. 195 The linker learns about them by reading <code>hello.6</code>.
334 </p> 196 </p>
335 197
336 <p> 198 <p>
337 To build more complicated programs, you will probably 199 To build more complicated programs, you will probably
338 want to use a 200 want to use a
339 <code>Makefile</code>. 201 <code>Makefile</code>.
340 There are examples in places like 202 There are examples in places like
341 <code>$GOROOT/src/cmd/godoc/Makefile</code> 203 <code>go/src/cmd/godoc/Makefile</code>
342 and <code>$GOROOT/src/pkg/*/Makefile</code>. 204 and <code>go/src/pkg/*/Makefile</code>.
343 The 205 The
344 <a href="contribute.html">document</a> 206 <a href="contribute.html">document</a>
345 about contributing to the Go project 207 about contributing to the Go project
346 gives more detail about 208 gives more detail about
347 the process of building and testing Go programs. 209 the process of building and testing Go programs.
348 </p> 210 </p>
349 211
350 <h2>Keeping up with releases</h2> 212 <h2 id="releases">Keeping up with releases</h2>
351 213
352 <p>New releases are announced on the <a href="http://groups.google.com/group/gol ang-nuts">Go Nuts</a> mailing list. 214 <p>New releases are announced on the <a href="http://groups.google.com/group/gol ang-nuts">Go Nuts</a> mailing list.
353 To update an existing tree to the latest release, you can run: 215 To update an existing tree to the latest release, you can run:
354 </p> 216 </p>
355 217
356 <pre> 218 <pre>
357 $ cd $GOROOT/src 219 $ cd go/src
358 $ hg pull 220 $ hg pull
359 $ hg update release 221 $ hg update release
360 $ ./all.bash 222 $ ./all.bash
361 </pre> 223 </pre>
362 224
363 <h2>Community resources</h2> 225 <h2 id="community">Community resources</h2>
364 226
365 <p> 227 <p>
366 For real-time help, there may be users or developers on 228 For real-time help, there may be users or developers on
367 <code>#go-nuts</code> on the <a href="http://freenode.net/">Freenode</a> IRC ser ver. 229 <code>#go-nuts</code> on the <a href="http://freenode.net/">Freenode</a> IRC ser ver.
368 </p> 230 </p>
369 231
370 <p> 232 <p>
371 The official mailing list for discussion of the Go language is 233 The official mailing list for discussion of the Go language is
372 <a href="http://groups.google.com/group/golang-nuts">Go Nuts</a>. 234 <a href="http://groups.google.com/group/golang-nuts">Go Nuts</a>.
373 </p> 235 </p>
374 236
375 <p> 237 <p>
376 Bugs can be reported using the <a href="http://code.google.com/p/go/issues/list" >Go issue tracker</a>. 238 Bugs can be reported using the <a href="http://code.google.com/p/go/issues/list" >Go issue tracker</a>.
377 </p> 239 </p>
378 240
379 <p> 241 <p>
380 For those who wish to keep up with development, 242 For those who wish to keep up with development,
381 there is another mailing list, <a href="http://groups.google.com/group/golang-ch eckins">golang-checkins</a>, 243 there is another mailing list, <a href="http://groups.google.com/group/golang-ch eckins">golang-checkins</a>,
382 that receives a message summarizing each checkin to the Go repository. 244 that receives a message summarizing each checkin to the Go repository.
383 </p> 245 </p>
384 246
247 <h2 id="environment">Environment variables</h2>
385 248
249 <p>
250 The Go compilation environment can be customized by five environment variables.
251 None are required by the build, but you may wish to set them
252 to override the defaults.
253 </p>
254
255 <dl>
256 <dt>
257 <code>$GOROOT</code>
258 </dt>
259 <dd>
260 The root of the Go tree, often <code>$HOME/go</code>.
261 This defaults to the parent of the directory where <code>all.bash</code> is run.
262 If you choose not to set <code>$GOROOT</code>, you must
263 run <code>gomake</code> instead of <code>make</code> or <code>gmake</cod e>
264 when developing Go programs using the conventional makefiles.
265 </dd>
266
267 <dt>
268 <code>$GOROOT_FINAL</code>
269 </dt>
270 <dd>
271 The value assumed by installed binaries and scripts when
272 <code>$GOROOT</code> is not set.
273 It defaults to the value used for <code>$GOROOT</code>.
274 If you want to build the Go tree in one location
275 but move it elsewhere after the build, set·
276 <code>$GOROOT_FINAL</code> to the eventual location.
277 </dd>
278
279 <dt>
280 <code>$GOOS</code> and <code>$GOARCH</code>
281 </dt>
282 <dd>
283 The name of the target operating system and compilation architecture.
284 These default to the local system's operating system and
285 architecture.
286
287 <p>
288 Choices for <code>$GOOS</code> are <code>linux</code>,
289 <code>freebsd</code>,
290 <code>darwin</code> (Mac OS X 10.5 or 10.6),
291 and <code>nacl</code> (Native Client, an incomplete port).
292 Choices for <code>$GOARCH</code> are <code>amd64</code> (64-bit x86, the most mature port),
293 <code>386</code> (32-bit x86), and
294 <code>arm</code> (32-bit ARM, an incomplete port).
295 The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> ar e:
296 <p>
297 <table cellpadding="0">
298 <tr>
299 <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>
300 </tr>
301 <tr>
302 <td></td><td><code>darwin</code></td> <td><code>386</code></td>
303 </tr>
304 <tr>
305 <td></td><td><code>darwin</code></td> <td><code>amd64</code></td>
306 </tr>
307 <tr>
308 <td></td><td><code>freebsd</code></td> <td><code>386</code></td>
309 </tr>
310 <tr>
311 <td></td><td><code>freebsd</code></td> <td><code>amd64</code></td>
312 </tr>
313 <tr>
314 <td></td><td><code>linux</code></td> <td><code>386</code></td>
315 </tr>
316 <tr>
317 <td></td><td><code>linux</code></td> <td><code>amd64</code></td>
318 </tr>
319 <tr>
320 <td></td><td><code>linux</code></td> <td><code>arm</code></td> <td><i>in complete</i></td>
321 </tr>
322 <tr>
323 <td></td><td><code>nacl</code></td> <td><code>386</code></td>
324 </tr>
325 <tr>
326 <td></td><td><code>windows</code></td> <td><code>386</code></td> <td><i> incomplete</i></td>
327 </tr>
328 </table>
329 </dd>
330
331 <dt>
332 <code>$GOBIN</code>
333 </dt>
334 <dd>
335 The location where binaries will be installed.
336 The default is <code>$GOROOT/bin</code>.
337 After installing, you will want to arrange to add this
338 directory to your <code>$PATH</code>, so you can use the tools.
339 </dd>
340
341 <dt>
342 <code>$GOARM</code> (arm, default=6)
343 </dt>
344 <dd>
345 The ARM architecture version the runtime libraries should target.
346 ARMv6 cores have more efficient synchronization primitives. Setting
347 <code>$GOARM</code> to 5 will compile the runtime libraries using
348 just SWP instructions that work on older architectures as well.
349 Running v6 code on an older core will cause an illegal instruction trap.
350 </dd>
351 </dl>
352
353 <p>
354 Note that <code>$GOARCH</code> and <code>$GOOS</code> identify the
355 <em>target</em> environment, not the environment you are running on.
356 In effect, you are always cross-compiling.
357 By architecture, we mean the kind of binaries
358 that the target environment can run:
359 an x86-64 system running a 32-bit-only operating system
360 must set <code>GOARCH</code> to <code>386</code>,
361 not <code>amd64</code>.
362 </p>
363
364 <p>
365 If you choose to override the defaults,
366 set these variables in your shell profile (<code>$HOME/.bashrc</code>,
367 <code>$HOME/.profile</code>, or equivalent). The settings might look·
368 something like this:
369 </p>
370
371 <pre>
372 export GOROOT=$HOME/go
373 export GOARCH=386
374 export GOOS=linux
375 </pre>
OLDNEW
« no previous file with comments | « README ('k') | no next file » | no next file with comments »

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b