From 3e45412327a2654a77944249962b3652e6142299 Mon Sep 17 00:00:00 2001 From: Ondřej Surý Date: Mon, 17 Jan 2011 12:40:45 +0100 Subject: Imported Upstream version 2011.01.12 --- doc/install.html | 392 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 240 insertions(+), 152 deletions(-) (limited to 'doc/install.html') 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 @@ - + -

Introduction

+

Introduction

Go is an open source project, distributed under a BSD-style license. @@ -8,6 +8,8 @@ This document explains how to check out the sources, build them on your own machine, and run them.

+
+

There are two distinct ways to experiment with Go. This document focuses on the gc Go @@ -17,117 +19,6 @@ compiler using the GCC back end, see Setting up and using gccgo.

-

Environment variables

- -

-The Go compilation environment depends on three environment variables plus one optional variable: -

- -
-
- $GOROOT -
-
The root of the Go tree. Typically this is $HOME/go - but it can be any directory. -
- -
-$GOOS and $GOARCH -
-
- The name of the target operating system and compilation architecture. - Choices for $GOOS are linux, - freebsd, - darwin (Mac OS X 10.5 or 10.6), - and nacl (Native Client, an incomplete port). - Choices for $GOARCH are amd64 (64-bit x86, the most mature port), - 386 (32-bit x86), and - arm (32-bit ARM, an incomplete port). - The valid combinations of $GOOS and $GOARCH are: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
$GOOS $GOARCH
darwin 386
darwin amd64
freebsd 386
freebsd amd64
linux 386
linux amd64
linux arm
nacl 386
-

-

- -
-$GOBIN (optional) -
-
- The location where binaries will be installed. - The default is $HOME/bin. - After installing, you will want to arrange to add this - directory to your $PATH, so you can use the tools. -
- -
-$GOARM (optional, arm, default=6) -
-
- The ARM architecture version the runtime libraries should target. - ARMv6 cores have more efficient synchronization primitives. Setting - $GOARM 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. -
-
- -

-Note that $GOARCH and $GOOS identify the -target environment, not the environment you are running on. -In effect, you are always cross-compiling. -

- -

-Set these variables in your shell profile ($HOME/.bashrc, -$HOME/.profile, or equivalent). The settings might look -something like this: -

- -
-export GOROOT=$HOME/go
-export GOARCH=amd64
-export GOOS=linux
-
- -

-Double-check them by listing your environment. (You will need to launch -a new shell or terminal window for the changes to take effect.) -

- -
-$ env | grep '^GO'
-
- -

Ports

-

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. 386 (a.k.a. x86 or x86-32); 8g,8l,8c,8a

- Comparable to the amd64 port. Not as well soaked but - should be nearly as solid. - + Comparable to the amd64 port.
arm (a.k.a. ARM); 5g,5l,5c,5a
- 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.
@@ -169,74 +62,106 @@ support for segmented stacks, and a strong goroutine implementation.

-See the separate gccgo document -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 +Windows Port +page for details.) +The full set of supported combinations is listed in the discussion of +environment variables below.

-

Install C tools, if needed

+
-

The Go tool chain is written in C. To build it, you need -to have GCC, the standard C libraries, the parser generator Bison, -make, awk, and the text editor ed installed. On OS X, they can be -installed as part of -Xcode. On Linux, use +

Install C tools, if needed

+ +

The Go tool chain is written in C. +To build it, you need these programs installed: +

-
-$ sudo apt-get install bison gcc libc6-dev ed gawk make
-
+

On OS X, they can be +installed as part of +Xcode. +

-

-(or the equivalent on your Linux distribution). +

On Ubuntu/Debian, use sudo apt-get install bison ed gawk gcc libc6-dev make.

-

Fetch the repository

+

Install Mercurial, if needed

-If you do not have Mercurial installed (you do not have an hg command), -this command: +To perform the next step you must have Mercurial installed. (Check that you have an hg command.) This suffices to install Mercurial on most systems:

- 
-$ sudo easy_install mercurial
+sudo easy_install mercurial
+(On Ubuntu/Debian, you might try apt-get install python-setuptools +python-dev build-essential first. The Mercurial in your distribution's +package repository will most likely be old and broken.) +

+

+If that fails, try installing manually from the Mercurial Download page.

+

-

works on most systems. -(On Ubuntu/Debian, you might try apt-get install python-setuptools python-dev build-essential gcc first.) -If that fails, visit the Mercurial Download page.

+

Fetch the repository

-

Make sure the $GOROOT directory does not exist or is empty. +

+

Go will install to a directory named go. +Change to the directory that will be its parent +and make sure the go directory does not exist. Then check out the repository:

-$ hg clone -r release https://go.googlecode.com/hg/ $GOROOT
+$ hg clone -r release https://go.googlecode.com/hg/ go
-

Install Go

+

Install Go

To build the Go distribution, run 

-$ cd $GOROOT/src
+$ cd go/src
 $ ./all.bash

-If all goes well, it will finish by printing +If all goes well, it will finish by printing output like: 

 --- 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.

-where N is a number that varies from release to release. +where N 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.

-

Writing programs

+
+ +

For more information about ways to control the build, +see the discussion of environment variables below.

+
+ +

Writing programs

Given a file file.go, compile it using @@ -299,34 +224,57 @@ command line. The linker learns about them by reading hello.6.

+

To build more complicated programs, you will probably want to use a Makefile. There are examples in places like -$GOROOT/src/cmd/godoc/Makefile -and $GOROOT/src/pkg/*/Makefile. +go/src/cmd/godoc/Makefile +and go/src/pkg/*/Makefile. The document about contributing to the Go project gives more detail about the process of building and testing Go programs.

+
-

Keeping up with releases

+

What's next

+ +

+Start by reading the Go Tutorial. +

+ +

+Build a web application by following the Wiki +Codelab. +

+ +

+Read Effective Go to learn about writing +idiomatic Go code. +

+ +

+For the full story, consult Go's extensive +documentation. +

+ +

Keeping up with releases

New releases are announced on the Go Nuts mailing list. To update an existing tree to the latest release, you can run: 

-$ cd $GOROOT/src
+$ cd go/src
 $ hg pull
 $ hg update release
 $ ./all.bash
-

Community resources

+

Community resources

For real-time help, there may be users or developers on @@ -348,4 +296,144 @@ there is another mailing list, Environment variables + +

+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. +

+ +
+
+ $GOROOT +
+
+ The root of the Go tree, often $HOME/go. + This defaults to the parent of the directory where all.bash is run. + If you choose not to set $GOROOT, you must + run gomake instead of make or gmake + when developing Go programs using the conventional makefiles. +
+ +
+ $GOROOT_FINAL +
+
+ The value assumed by installed binaries and scripts when + $GOROOT is not set. + It defaults to the value used for $GOROOT. + If you want to build the Go tree in one location + but move it elsewhere after the build, set + $GOROOT_FINAL to the eventual location. +
+ +
+$GOOS and $GOARCH +
+
+ The name of the target operating system and compilation architecture. + These default to the values of $GOHOSTOS and + $GOHOSTARCH respectively (described below). +

+ Choices for $GOOS are linux, + freebsd, + darwin (Mac OS X 10.5 or 10.6), + and windows (Windows, an incomplete port). + Choices for $GOARCH are amd64 (64-bit x86, the most mature port), + 386 (32-bit x86), and + arm (32-bit ARM, an incomplete port). + The valid combinations of $GOOS and $GOARCH are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
$GOOS $GOARCH
darwin 386
darwin amd64
freebsd 386
freebsd amd64
linux 386
linux amd64
linux arm incomplete
windows 386 incomplete
+

+ +
+$GOHOSTOS and $GOHOSTARCH +
+
+ The name of the host operating system and compilation architecture. + These default to the local system's operating system and + architecture. + +

+ Valid choices are the same as for $GOOS and + $GOARCH, listed above. + The specified values must be compatible with the local system. + For example, you should not set $GOHOSTARCH to + arm on an x86 system. +

+ +
+$GOBIN +
+
+ The location where binaries will be installed. + The default is $GOROOT/bin. + After installing, you will want to arrange to add this + directory to your $PATH, so you can use the tools. +
+ +
+$GOARM (arm, default=6) +
+
+ The ARM architecture version the runtime libraries should target. + ARMv6 cores have more efficient synchronization primitives. Setting + $GOARM 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. +
+
+ +

+Note that $GOARCH and $GOOS identify the +target 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 GOARCH to 386, +not amd64. +

+ +

+If you choose to override the defaults, +set these variables in your shell profile ($HOME/.bashrc, +$HOME/.profile, or equivalent). The settings might look +something like this: +

+ +
+export GOROOT=$HOME/go
+export GOARCH=386
+export GOOS=linux
+
-- cgit v1.2.3