github.com/miolini/go@v0.0.0-20160405192216-fca68c8cb408/doc/install-source.html (about)

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