From 86920ad81d50e920a099ec2d75ee719ae3f145ff Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Tue, 24 Aug 2010 20:00:50 -0400 Subject: [PATCH] build: update, streamline documentation for new $GOBIN R=adg, r CC=golang-dev https://golang.org/cl/2025041 --- README | 39 ++---- doc/install.html | 344 +++++++++++++++++++++++------------------------ 2 files changed, 179 insertions(+), 204 deletions(-) diff --git a/README b/README index aa71c49e941..8bf9e7b8cf6 100644 --- a/README +++ b/README @@ -14,33 +14,18 @@ under the BSD-style license found in the LICENSE file. Binary Distribution Notes -If you have just untarred a binary Go distribution, then there are some -environment variables you'll need to set in your .profile (or equivalent): +If you have just untarred a binary Go distribution, you need to set +the environment variable $GOROOT to the full path of the go +directory (the one containing this README). You can omit the +variable if you unpack it into /usr/local/go, or if you rebuild +from sources by running all.bash (see doc/install.html). +You should also add the Go binary directory $GOROOT/bin +to your shell's path. - GOOS should be set to your operating system (eg, linux), - GOARCH should be your processor architecture (eg, amd64), - GOROOT should be the directory you extracted the tarball to, - GOBIN should point to $GOROOT/bin. +For example, if you extracted the tar file into $HOME/go, you might +put the following in your .profile: -For example, if you downloaded the tarball - - go.release.YYYY-MM-DD.linux-amd64.tar.gz - -and extracted it to - - /home/username/go - -you would set the following variables: - - export GOOS=linux - export GOARCH=amd64 - export GOROOT=/home/username/go - export GOBIN=$GOROOT/bin - -See doc/install.html for more detail about these flags. - -Additionally, $GOROOT should be in your $PATH: - - export PATH=PATH:$GOROOT - + export GOROOT=$HOME/go + export PATH=$PATH:$GOROOT/bin +See doc/install.html for more details. diff --git a/doc/install.html b/doc/install.html index 601edc515a1..05771260cd7 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. @@ -17,146 +17,6 @@ compiler using the GCC back end, see Setting up and using gccgo.

-

Environment variables

- -

-The Go compilation environment can be customized by five 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. - Although this variable is optional, the examples and typescripts below - use it as shorthand for the location where you installed Go. - 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 local system's operating system and - 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 -
-
- 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 (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=amd64  # optional
-export GOOS=linux    # optional
-
- -

-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 @@ -176,17 +36,16 @@ 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. + Still a work in progress. + It only supports Linux binaries, floating point is weak, and the + optimizer is not enabled. Tested against QEMU and an android phone. - Only supports Linux binaries.
@@ -198,57 +57,54 @@ 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, Native Client, +and OS X (a.k.a. Darwin) operating systems. +(A port to Microsoft Windows is in progress but incomplete.) +The full set of supported combinations is listed in the discussion of +environment variables below.

-

Install C tools, if needed

+

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 +make, awk, and the text editor ed installed.

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

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

-

+

On Linux, use sudo apt-get install bison ed gawk gcc libc6-dev make (or the equivalent on your Linux distribution).

-

Fetch the repository

+

Fetch the repository

If you do not have Mercurial installed (you do not have an hg command), -this command: -

- -
-$ sudo easy_install mercurial
-
- -

works on most systems. +sudo easy_install mercurial 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.

-

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
@@ -261,16 +117,22 @@ If all goes well, it will finish by printing output like: N known bugs; 0 unexpected bugs --- -Installed Go for darwin/amd64 in /Users/you/go; the compiler is 6g. +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 -and the details on the last line will reflect the operating system, +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 @@ -338,8 +200,8 @@ 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 @@ -347,20 +209,20 @@ gives more detail about the process of building and testing Go programs.

-

Keeping up with releases

+

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 @@ -382,4 +244,132 @@ there is another mailing list, Environment variables +

+The Go compilation environment can be customized by five 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 local system's operating system and + 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 incomplete
nacl 386
windows 386 incomplete
+

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