2010-09-15 22:01:02 -06:00
<!-- Getting Started -->
2009-10-23 16:24:08 -06:00
2010-08-24 18:00:50 -06:00
< h2 id = "introduction" > Introduction< / h2 >
2009-10-23 16:24:08 -06:00
2009-11-08 23:12:51 -07:00
< p > Go is an open source project, distributed under a
< a href = "/LICENSE" > BSD-style license< / a > .
This document explains how to check out the sources,
build them on your own machine, and run them.
< / p >
2010-09-15 22:01:02 -06:00
< div class = "detail" >
2009-10-23 16:24:08 -06:00
< p >
There are two distinct ways to experiment with Go.
2009-11-08 23:12:51 -07:00
This document focuses on the < code > gc< / code > Go
2009-11-05 16:07:42 -07:00
compiler and tools (< code > 6g< / code > , < code > 8g< / code > etc.).
2009-10-23 16:24:08 -06:00
For information on how to use < code > gccgo< / code > , a more traditional
2009-11-05 16:07:42 -07:00
compiler using the GCC back end, see
2009-11-06 15:36:34 -07:00
< a href = "gccgo_install.html" > Setting up and using gccgo< / a > .
2009-10-23 16:24:08 -06:00
< / p >
2009-11-05 16:07:42 -07:00
< p >
2010-03-16 19:45:16 -06:00
The Go compilers support three instruction sets.
2009-11-05 16:07:42 -07:00
There are important differences in the quality of the compilers for the different
architectures.
< / p >
< dl >
< dt >
< code > amd64< / code > (a.k.a. < code > x86-64< / code > ); < code > 6g,6l,6c,6a< / code >
< / dt >
< dd >
2009-11-06 18:31:23 -07:00
The most mature implementation. The compiler has an effective optimizer
2009-11-05 16:07:42 -07:00
(registerizer) and generates good code (although < code > gccgo< / code >
can do noticeably better sometimes).
< / dd >
< dt >
< code > 386< / code > (a.k.a. < code > x86< / code > or < code > x86-32< / code > ); < code > 8g,8l,8c,8a< / code >
< / dt >
2009-11-08 23:12:51 -07:00
< dd >
2010-08-24 18:00:50 -06:00
Comparable to the < code > amd64< / code > port.
2009-11-05 16:07:42 -07:00
< / dd >
< dt >
< code > arm< / code > (a.k.a. < code > ARM< / code > ); < code > 5g,5l,5c,5a< / code >
< / dt >
< dd >
2010-09-21 23:30:42 -06:00
Incomplete.
2011-01-19 21:07:38 -07:00
It only supports Linux binaries, the optimizer is incomplete,
and floating point uses the VFP unit.
2010-10-26 09:34:40 -06:00
However, all tests pass.
2011-01-19 21:07:38 -07:00
Work on the optimizer is continuing.
2010-09-21 23:30:42 -06:00
Tested against a Nexus One.
2009-11-05 16:07:42 -07:00
< / dd >
< / dl >
< p >
2011-03-01 14:54:22 -07:00
Except for things like low-level operating system interface code, the run-time
2009-11-05 16:07:42 -07:00
support is the same in all ports and includes a mark-and-sweep garbage collector
(a fancier one is in the works), efficient array and string slicing,
support for segmented stacks, and a strong goroutine implementation.
< / p >
< p >
2010-12-15 09:49:23 -07:00
The compilers can target the FreeBSD, Linux,
2010-08-24 18:00:50 -06:00
and OS X (a.k.a. Darwin) operating systems.
2010-12-07 14:31:26 -07:00
(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.)
2010-08-24 18:00:50 -06:00
The full set of supported combinations is listed in the discussion of
< a href = "#environment" > environment variables< / a > below.
2009-11-05 16:07:42 -07:00
< / p >
2010-09-15 22:01:02 -06:00
< / div >
2010-08-24 18:00:50 -06:00
< h2 id = "ctools" > Install C tools, if needed< / h2 >
2010-03-10 17:31:09 -07:00
2010-09-15 22:01:02 -06:00
< 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,
2011-04-26 19:39:22 -06:00
< li > GNU < tt > make< / tt > (version 3.81 or later),
2010-09-15 22:01:02 -06:00
< li > < tt > awk< / tt > , and
< li > the text editor < tt > ed< / tt > .
< / ul >
2010-03-10 17:31:09 -07:00
< / p >
2010-08-24 18:00:50 -06:00
< p > On OS X, they can be
installed as part of
< a href = "http://developer.apple.com/TOOLS/Xcode/" > Xcode< / a > .
< / p >
2010-03-10 17:31:09 -07:00
2011-04-13 18:28:59 -06:00
< p > On Ubuntu/Debian, use < code > sudo apt-get install bison ed gawk gcc libc6-dev
make< / code > . If you want to build 32-bit binaries on a 64-bit system you'll
also need the < code > libc6-dev-i386< / code > package.
2010-03-10 17:31:09 -07:00
< / p >
2010-09-15 22:01:02 -06:00
< h2 id = "mercurial" > Install Mercurial, if needed< / h2 >
2009-10-23 16:24:08 -06:00
< p >
2010-09-29 13:34:24 -06:00
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:
2010-09-15 22:01:02 -06:00
< / p >
< pre >
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 >
2011-02-02 16:53:32 -07:00
< p >
Mercurial versions 1.7.x and up require the configuration of
< a href = "http://mercurial.selenic.com/wiki/CACertificates" > Certification Authorities< / a >
(CAs). Error messages of the form:
< / p >
< pre >
warning: go.googlecode.com certificate with fingerprint b1:af: ... bc not verified (check hostfingerprints or web.cacerts config setting)
< / pre >
< p >
when using Mercurial indicate that the CAs are missing.
Check your Mercurial version (< code > hg --version< / code > ) and
< a href = "http://mercurial.selenic.com/wiki/CACertificates#Configuration_of_HTTPS_certificate_authorities" > configure the CAs< / a >
if necessary.
< / p >
2010-09-15 22:01:02 -06:00
< h2 id = "fetch" > Fetch the repository< / h2 >
2009-10-23 16:24:08 -06:00
2010-09-15 22:01:02 -06:00
< p >
2010-08-24 18:00:50 -06:00
< 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.
2009-10-23 16:24:08 -06:00
Then check out the repository:< / p >
< pre >
2010-08-24 18:00:50 -06:00
$ hg clone -r release https://go.googlecode.com/hg/ go
2009-10-23 16:24:08 -06:00
< / pre >
2010-08-24 18:00:50 -06:00
< h2 id = "install" > Install Go< / h2 >
2009-10-23 16:24:08 -06:00
< p >
2009-12-11 16:14:09 -07:00
To build the Go distribution, run
2009-10-23 16:24:08 -06:00
< / p >
< pre >
2010-08-24 18:00:50 -06:00
$ cd go/src
2010-01-25 01:09:46 -07:00
$ ./all.bash
2009-10-23 16:24:08 -06:00
< / pre >
< p >
2010-08-18 08:08:49 -06:00
If all goes well, it will finish by printing output like:
2009-10-23 16:24:08 -06:00
< / p >
< pre >
2011-02-14 07:27:02 -07:00
ALL TESTS PASSED
2010-08-18 08:08:49 -06:00
---
2010-08-24 18:00:50 -06:00
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.
2009-10-23 16:24:08 -06:00
< / pre >
< p >
2011-03-02 22:41:03 -07:00
where the details on the last few lines reflect the operating system,
2010-08-18 08:08:49 -06:00
architecture, and root directory used during the install.
2009-10-23 16:24:08 -06:00
< / p >
2010-09-15 22:01:02 -06:00
< div class = "detail" >
2010-08-24 18:00:50 -06:00
< p > For more information about ways to control the build,
see the discussion of < a href = "#environment" > environment variables< / a > below.< / p >
2010-09-15 22:01:02 -06:00
< / div >
2010-08-24 18:00:50 -06:00
< h2 id = "writing" > Writing programs< / h2 >
2009-10-23 16:24:08 -06:00
< p >
Given a file < code > file.go< / code > , compile it using
< / p >
< pre >
$ 6g file.go
< / pre >
< p >
< code > 6g< / code > is the Go compiler for < code > amd64< / code > ; it will write the output
in < code > file.6< / code > . The ‘ < code > 6< / code > ’ identifies
files for the < code > amd64< / code > architecture.
The identifier letters for < code > 386< / code > and < code > arm< / code >
are ‘ < code > 8< / code > ’ and ‘ < code > 5< / code > ’ .
That is, if you were compiling for < code > 386< / code > , you would use
< code > 8g< / code > and the output would be named < code > file.8< / code > .
< / p >
< p >
To link the file, use
< / p >
< pre >
$ 6l file.6
< / pre >
< p >
and to run it
< / p >
< pre >
$ ./6.out
< / pre >
< p > A complete example:
< / p >
< pre >
$ cat > hello.go < < EOF
package main
import "fmt"
func main() {
fmt.Printf("hello, world\n")
}
EOF
$ 6g hello.go
$ 6l hello.6
$ ./6.out
hello, world
$
< / pre >
< p >
There is no need to list < code > hello.6< / code > 's package dependencies
(in this case, package < code > fmt< / code > ) on the < code > 6l< / code >
command line.
The linker learns about them by reading < code > hello.6< / code > .
< / p >
2010-09-15 22:01:02 -06:00
< div class = "detail" >
2009-10-23 16:24:08 -06:00
< p >
To build more complicated programs, you will probably
2009-11-08 23:12:51 -07:00
want to use a
2009-10-23 16:24:08 -06:00
< code > Makefile< / code > .
2009-11-05 16:07:42 -07:00
There are examples in places like
2010-08-24 18:00:50 -06:00
< code > go/src/cmd/godoc/Makefile< / code >
and < code > go/src/pkg/*/Makefile< / code > .
2009-11-05 16:07:42 -07:00
The
< a href = "contribute.html" > document< / a >
about contributing to the Go project
gives more detail about
2009-10-23 16:24:08 -06:00
the process of building and testing Go programs.
< / p >
2010-09-15 22:01:02 -06:00
< / div >
< 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 >
2009-11-09 00:38:30 -07:00
2010-08-24 18:00:50 -06:00
< h2 id = "releases" > Keeping up with releases< / h2 >
2009-12-15 20:16:56 -07:00
2011-03-16 23:33:10 -06:00
< p >
The Go project maintains two stable tags in its Mercurial repository:
< code > release< / code > and < code > weekly< / code > .
The < code > weekly< / code > tag is updated about once a week, and should be used by
those who want to track the project's development.
The < code > release< / code > tag is given, less often, to those weekly releases
that have proven themselves to be robust.
< / p >
< p >
Most Go users will want to keep their Go installation at the latest
< code > release< / code > tag.
New releases are announced on the
< a href = "http://groups.google.com/group/golang-announce" > golang-announce< / a >
mailing list.
< / p >
< p >
2009-12-15 20:16:56 -07:00
To update an existing tree to the latest release, you can run:
< / p >
< pre >
2010-08-24 18:00:50 -06:00
$ cd go/src
2009-12-15 20:16:56 -07:00
$ hg pull
$ hg update release
2010-01-28 19:18:40 -07:00
$ ./all.bash
2009-12-15 20:16:56 -07:00
< / pre >
2011-03-16 23:33:10 -06:00
< p >
To use the < code > weekly< / code > tag run < code > hg update weekly< / code > instead.
< / p >
2010-08-24 18:00:50 -06:00
< h2 id = "community" > Community resources< / h2 >
2009-11-09 00:38:30 -07:00
< p >
For real-time help, there may be users or developers on
< code > #go-nuts< / code > on the < a href = "http://freenode.net/" > Freenode< / a > IRC server.
< / p >
< p >
The official mailing list for discussion of the Go language is
< a href = "http://groups.google.com/group/golang-nuts" > Go Nuts< / a > .
< / p >
< p >
Bugs can be reported using the < a href = "http://code.google.com/p/go/issues/list" > Go issue tracker< / a > .
< / p >
< p >
For those who wish to keep up with development,
there is another mailing list, < a href = "http://groups.google.com/group/golang-checkins" > golang-checkins< / a > ,
that receives a message summarizing each checkin to the Go repository.
< / p >
2010-08-24 18:00:50 -06:00
< h2 id = "environment" > Environment variables< / h2 >
< p >
2010-12-04 20:04:15 -07:00
The Go compilation environment can be customized by environment variables.
2010-08-24 18:00:50 -06:00
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.
2010-12-04 20:04:15 -07:00
These default to the values of < code > $GOHOSTOS< / code > and
< code > $GOHOSTARCH< / code > respectively (described below).
2009-11-09 00:38:30 -07:00
2010-08-24 18:00:50 -06:00
< p >
Choices for < code > $GOOS< / code > are < code > linux< / code > ,
< code > freebsd< / code > ,
< code > darwin< / code > (Mac OS X 10.5 or 10.6),
2010-12-08 02:27:45 -07:00
and < code > windows< / code > (Windows, an incomplete port).
2010-08-24 18:00:50 -06:00
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 >
2010-12-04 20:04:15 -07:00
< 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 >
2010-08-24 18:00:50 -06:00
< 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 >
2011-03-01 14:54:22 -07:00
The ARM architecture version the run-time libraries should target.
2010-08-24 18:00:50 -06:00
ARMv6 cores have more efficient synchronization primitives. Setting
2011-03-01 14:54:22 -07:00
< code > $GOARM< / code > to 5 will compile the run-time libraries using
2010-08-24 18:00:50 -06:00
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 >