summaryrefslogtreecommitdiff
path: root/doc/install.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/install.html')
-rw-r--r--doc/install.html392
1 files changed, 240 insertions, 152 deletions
diff --git a/doc/install.html b/doc/install.html
index 2c1ff2157..92b099fe8 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -1,6 +1,6 @@
-<!-- Installing Go -->
+<!-- Getting Started -->
-<h2>Introduction</h2>
+<h2 id="introduction">Introduction</h2>
<p>Go is an open source project, distributed under a
<a href="/LICENSE">BSD-style license</a>.
@@ -8,6 +8,8 @@ This document explains how to check out the sources,
build them on your own machine, and run them.
</p>
+<div class="detail">
+
<p>
There are two distinct ways to experiment with Go.
This document focuses on the <code>gc</code> Go
@@ -17,117 +19,6 @@ compiler using the GCC back end, see
<a href="gccgo_install.html">Setting up and using gccgo</a>.
</p>
-<h2>Environment variables</h2>
-
-<p>
-The Go compilation environment depends on three environment variables plus one optional variable:
-</p>
-
-<dl>
-<dt>
- <code>$GOROOT</code>
-</dt>
-<dd>The root of the Go tree. Typically this is <code>$HOME/go</code>
- but it can be any directory.
-</dd>
-
-<dt>
-<code>$GOOS</code> and <code>$GOARCH</code>
-</dt>
-<dd>
- The name of the target operating system and compilation architecture.
- Choices for <code>$GOOS</code> are <code>linux</code>,
- <code>freebsd</code>,
- <code>darwin</code> (Mac OS X 10.5 or 10.6),
- and <code>nacl</code> (Native Client, an incomplete port).
- 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, an incomplete port).
- The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> are:
- <p>
- <table cellpadding="0">
- <tr>
- <th width="50"><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>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>nacl</code></td> <td><code>386</code></td>
- </tr>
- </table>
- <p>
-</dd>
-
-<dt>
-<code>$GOBIN</code> (optional)
-</dt>
-<dd>
- The location where binaries will be installed.
- The default is <code>$HOME/bin</code>.
- After installing, you will want to arrange to add this
- directory to your <code>$PATH</code>, so you can use the tools.
-</dd>
-
-<dt>
-<code>$GOARM</code> (optional, arm, default=6)
-</dt>
-<dd>
- The ARM architecture version the runtime libraries should target.
- ARMv6 cores have more efficient synchronization primitives. Setting
- <code>$GOARM</code> to 5 will compile the runtime libraries using
- just SWP instructions that work on older architectures as well.
- Running v6 code on an older core will cause an illegal instruction trap.
-</dd>
-</dl>
-
-<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.
-</p>
-
-<p>
-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>
-Double-check them by listing your environment. (You will need to launch
-a new shell or terminal window for the changes to take effect.)
-</p>
-
-<pre>
-$ env | grep '^GO'
-</pre>
-
-<h2>Ports</h2>
-
<p>
The Go compilers support three instruction sets.
There are important differences in the quality of the compilers for the different
@@ -147,17 +38,19 @@ architectures.
<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. Not as well soaked but
- should be nearly as solid.
-
+ 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>
- It's got a couple of outstanding bugs but is improving.
- Tested against QEMU and an android phone.
- Only supports Linux binaries.
+ Incomplete.
+ It only supports Linux binaries, the optimizer is not enabled,
+ and floating point is performed entirely in software.
+ However, all tests pass.
+ Work on the optimizer and use of the VFP hardware
+ floating point unit is underway.
+ Tested against a Nexus One.
</dd>
</dl>
@@ -169,74 +62,106 @@ support for segmented stacks, and a strong goroutine implementation.
</p>
<p>
-See the separate <a href="gccgo_install.html"><code>gccgo</code> document</a>
-for details about that compiler and environment.
+The compilers can target the FreeBSD, Linux,
+and OS X (a.k.a. Darwin) operating systems.
+(A port to Microsoft Windows is in progress but incomplete. See the
+<a href="http://code.google.com/p/go/wiki/WindowsPort">Windows Port</a>
+page for details.)
+The full set of supported combinations is listed in the discussion of
+<a href="#environment">environment variables</a> below.
</p>
-<h2>Install C tools, if needed</h2>
+</div>
-<p>The Go tool chain is written in C. To build it, you need
-to have GCC, the standard C libraries, the parser generator Bison,
-<tt>make</tt>, <tt>awk</tt>, and the text editor <tt>ed</tt> installed. On OS X, they can be
-installed as part of
-<a href="http://developer.apple.com/TOOLS/Xcode/">Xcode</a>. On Linux, use
+<h2 id="ctools">Install C tools, if needed</h2>
+
+<p>The Go tool chain is written in C.
+To build it, you need these programs installed:
+<ul>
+<li>GCC,
+<li>the standard C libraries,
+<li>the parser generator Bison,
+<li><tt>make</tt>,
+<li><tt>awk</tt>, and
+<li>the text editor <tt>ed</tt>.
+</ul>
</p>
-<pre>
-$ sudo apt-get install bison gcc libc6-dev ed gawk make
-</pre>
+<p>On OS X, they can be
+installed as part of
+<a href="http://developer.apple.com/TOOLS/Xcode/">Xcode</a>.
+</p>
-<p>
-(or the equivalent on your Linux distribution).
+<p>On Ubuntu/Debian, use <code>sudo apt-get install bison ed gawk gcc libc6-dev make</code>.
</p>
-<h2>Fetch the repository</h2>
+<h2 id="mercurial">Install Mercurial, if needed</h2>
<p>
-If you do not have Mercurial installed (you do not have an <code>hg</code> command),
-this command:
+To perform the next step you must have Mercurial installed. (Check that you have an <code>hg</code> command.) This suffices to install Mercurial on most systems:
</p>
-
<pre>
-$ sudo easy_install mercurial
+sudo easy_install mercurial
</pre>
+(On Ubuntu/Debian, you might try <code>apt-get install python-setuptools
+python-dev build-essential</code> first. The Mercurial in your distribution's
+package repository will most likely be old and broken.)
+</p>
+<p>
+If that fails, try installing manually from the <a href="http://mercurial.selenic.com/wiki/Download">Mercurial Download</a> page.</p>
+</p>
-<p>works on most systems.
-(On Ubuntu/Debian, you might try <code>apt-get install python-setuptools python-dev build-essential gcc</code> first.)
-If that fails, visit the <a href="http://mercurial.selenic.com/wiki/Download">Mercurial Download</a> page.</p>
+<h2 id="fetch">Fetch the repository</h2>
-<p>Make sure the <code>$GOROOT</code> directory does not exist or is empty.
+<p>
+<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 -r release https://go.googlecode.com/hg/ $GOROOT
+$ hg clone -r release https://go.googlecode.com/hg/ go
</pre>
-<h2>Install Go</h2>
+<h2 id="install">Install Go</h2>
<p>
To build the Go distribution, run
</p>
<pre>
-$ cd $GOROOT/src
+$ cd go/src
$ ./all.bash
</pre>
<p>
-If all goes well, it will finish by printing
+If all goes well, it will finish by printing output like:
</p>
<pre>
--- cd ../test
N known bugs; 0 unexpected bugs
+
+---
+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. ***
+The compiler is 6g.
</pre>
<p>
-where <var>N</var> is a number that varies from release to release.
+where <var>N</var> is a number that varies from release to release
+and the details on the last few lines will reflect the operating system,
+architecture, and root directory used during the install.
</p>
-<h2>Writing programs</h2>
+<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="writing">Writing programs</h2>
<p>
Given a file <code>file.go</code>, compile it using
@@ -299,34 +224,57 @@ command line.
The linker learns about them by reading <code>hello.6</code>.
</p>
+<div class="detail">
<p>
To build more complicated programs, you will probably
want to use a
<code>Makefile</code>.
There are examples in places like
-<code>$GOROOT/src/cmd/godoc/Makefile</code>
-and <code>$GOROOT/src/pkg/*/Makefile</code>.
+<code>go/src/cmd/godoc/Makefile</code>
+and <code>go/src/pkg/*/Makefile</code>.
The
<a href="contribute.html">document</a>
about contributing to the Go project
gives more detail about
the process of building and testing Go programs.
</p>
+</div>
-<h2>Keeping up with releases</h2>
+<h2 id="next">What's next</h2>
+
+<p>
+Start by reading the <a href="go_tutorial.html">Go Tutorial</a>.
+</p>
+
+<p>
+Build a web application by following the <a href="codelab/wiki/">Wiki
+Codelab</a>.
+</p>
+
+<p>
+Read <a href="effective_go.html">Effective Go</a> to learn about writing
+idiomatic Go code.
+</p>
+
+<p>
+For the full story, consult Go's extensive
+<a href="docs.html">documentation</a>.
+</p>
+
+<h2 id="releases">Keeping up with releases</h2>
<p>New releases are announced on the <a href="http://groups.google.com/group/golang-nuts">Go Nuts</a> mailing list.
To update an existing tree to the latest release, you can run:
</p>
<pre>
-$ cd $GOROOT/src
+$ cd go/src
$ hg pull
$ hg update release
$ ./all.bash
</pre>
-<h2>Community resources</h2>
+<h2 id="community">Community resources</h2>
<p>
For real-time help, there may be users or developers on
@@ -348,4 +296,144 @@ there is another mailing list, <a href="http://groups.google.com/group/golang-ch
that receives a message summarizing each checkin to the Go repository.
</p>
+<h2 id="environment">Environment variables</h2>
+
+<p>
+The Go compilation environment can be customized by environment variables.
+None are required by the build, but you may wish to set them
+to override the defaults.
+</p>
+
+<dl>
+<dt>
+ <code>$GOROOT</code>
+</dt>
+<dd>
+ The root of the Go tree, often <code>$HOME/go</code>.
+ This defaults to the parent of the directory where <code>all.bash</code> is run.
+ If you choose not to set <code>$GOROOT</code>, you must
+ run <code>gomake</code> instead of <code>make</code> or <code>gmake</code>
+ when developing Go programs using the conventional makefiles.
+</dd>
+
+<dt>
+ <code>$GOROOT_FINAL</code>
+</dt>
+<dd>
+ The value assumed by installed binaries and scripts when
+ <code>$GOROOT</code> is not set.
+ It defaults to the value used for <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.
+</dd>
+
+<dt>
+<code>$GOOS</code> and <code>$GOARCH</code>
+</dt>
+<dd>
+ 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>linux</code>,
+ <code>freebsd</code>,
+ <code>darwin</code> (Mac OS X 10.5 or 10.6),
+ and <code>windows</code> (Windows, an incomplete port).
+ 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, an incomplete port).
+ The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> are:
+ <table cellpadding="0">
+ <tr>
+ <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>
+ </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>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> <td><i>incomplete</i></td>
+ </tr>
+ <tr>
+ <td></td><td><code>windows</code></td> <td><code>386</code></td> <td><i>incomplete</i></td>
+ </tr>
+ </table>
+</dd>
+
+<dt>
+<code>$GOHOSTOS</code> and <code>$GOHOSTARCH</code>
+</dt>
+<dd>
+ The name of the host operating system and compilation architecture.
+ These default to the local system's operating system and
+ architecture.
+
+ <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.
+</dd>
+
+<dt>
+<code>$GOBIN</code>
+</dt>
+<dd>
+ The location where 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.
+</dd>
+
+<dt>
+<code>$GOARM</code> (arm, default=6)
+</dt>
+<dd>
+ The ARM architecture version the runtime libraries should target.
+ ARMv6 cores have more efficient synchronization primitives. Setting
+ <code>$GOARM</code> to 5 will compile the runtime libraries using
+ just SWP instructions that work on older architectures as well.
+ Running v6 code on an older core will cause an illegal instruction trap.
+</dd>
+</dl>
+
+<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=386
+export GOOS=linux
+</pre>
generated by cgit v1.2.3 (git 2.39.1) at 2025-05-02 12:33:02 +0000