From e07f089cb02790b6fedab92105eba09bd578aae7 Mon Sep 17 00:00:00 2001 From: Andrew Gerrand Date: Tue, 14 Feb 2012 17:02:28 +1100 Subject: [PATCH] doc: update install.html for binary distros, add install-source.html R=bsiegert, rsc, r CC=golang-dev https://golang.org/cl/5605047 --- doc/gccgo_install.html | 3 +- doc/install-source.html | 475 ++++++++++++++++++++++++++++++++++++++++ doc/install.html | 465 +++++++-------------------------------- 3 files changed, 561 insertions(+), 382 deletions(-) create mode 100644 doc/install-source.html diff --git a/doc/gccgo_install.html b/doc/gccgo_install.html index 085a305432b..d5fff7bf9ec 100644 --- a/doc/gccgo_install.html +++ b/doc/gccgo_install.html @@ -1,5 +1,6 @@

diff --git a/doc/install-source.html b/doc/install-source.html new file mode 100644 index 00000000000..7c4ab8155a5 --- /dev/null +++ b/doc/install-source.html @@ -0,0 +1,475 @@ + + +

Introduction

+ +

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

+ +
+ +

+There are two official Go compiler tool chains. +This document focuses on the gc Go +compiler and tools (6g, 8g etc.). +For information on how to use gccgo, a more traditional +compiler using the GCC back end, see +Setting up and using gccgo. +

+ +

+The Go compilers support three instruction sets. +There are important differences in the quality of the compilers for the different +architectures. +

+ +
+
+ amd64 (a.k.a. x86-64); 6g,6l,6c,6a +
+
+ The most mature implementation. The compiler has an effective + optimizer (registerizer) and generates good code (although + gccgo can do noticeably better sometimes). +
+
+ 386 (a.k.a. x86 or x86-32); 8g,8l,8c,8a +
+
+ Comparable to the amd64 port. +
+
+ arm (a.k.a. ARM); 5g,5l,5c,5a +
+
+ Supports only Linux binaries. Less tested than the other ports. +
+
+ +

+Except for things like low-level operating system interface code, the run-time +support is the same in all ports and includes a mark-and-sweep garbage +collector, efficient array and string slicing, and support for efficient +goroutines, such as stacks that grow and shrink on demand. +

+ +

+The compilers can target the FreeBSD, Linux, NetBSD, OpenBSD, OS X (Darwin), +and Windows operating systems. +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 a C compiler installed. +

+ +

+On OS X, a C compiler can be installed as part of +Xcode. +

+ +

+On Ubuntu/Debian, use sudo apt-get install gcc libc6-dev. +If you want to build 32-bit binaries on a 64-bit system you'll also need the +libc6-dev-i386 package. +

+ +

+TODO: add Windows compiler info +

+ +

Install Mercurial, if needed

+ +

+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==2.0
+
+ +

+On Ubuntu/Debian, +the Mercurial in your distribution's +package repository is most likely old and broken. +You might try this first: +

+ +
apt-get install python-setuptools python-dev build-essential
+ +

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

+

+ +

+Mercurial versions 1.7.x and up require the configuration of +Certification Authorities +(CAs). Error messages of the form: +

+ +
+warning: code.google.com certificate with fingerprint b1:af: ... bc not verified (check hostfingerprints or web.cacerts config setting)
+
+ +

+when using Mercurial indicate that the CAs are missing. +Check your Mercurial version (hg --version) and +configure the CAs +if necessary. +

+ + +

Fetch the repository

+ +

+

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 -u release https://code.google.com/p/go
+
+ +

Install Go

+ +

+To build the Go distribution, run +

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

+(To build under Windows use all.bat.) +

+ +

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

+ +
+ALL TESTS PASSED
+
+---
+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 the details on the last few lines reflect the operating system, +architecture, and root directory used during the install. +

+ +
+

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

+
+ + +

Testing your installation

+ +

+Check that Go is installed correctly by building a simple program. +

+ +

+Create a file named hello.go and put the following program in it: +

+ +
+package main
+
+import "fmt"
+
+func main() {
+    fmt.Printf("hello, world\n")
+}
+
+ +

+Then run it with the go tool: +

+ +
+$ go run hello.go
+hello, world
+
+ +

+If you see the "hello, world" message then Go is installed correctly. +

+ + +

What's next

+ +

+Start by taking A Tour of Go +or reading the Go Tutorial. +

+ +

+For more detail about the process of building and testing Go programs +read How to Write Go Code. +

+ +

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

+ + +

Community resources

+ +

+For real-time help, there may be users or developers on +#go-nuts on the Freenode IRC server. +

+ +

+The official mailing list for discussion of the Go language is +Go Nuts. +

+ +

+Bugs can be reported using the Go issue tracker. +

+ +

+For those who wish to keep up with development, +there is another mailing list, golang-checkins, +that receives a message summarizing each checkin to the Go repository. +

+ + +

Keeping up with releases

+ +

+The Go project maintains two stable tags in its Mercurial repository: +release and weekly. +The weekly tag is updated about once a week, and should be used by +those who want to track the project's development. +The release tag is given, less often, to those weekly releases +that have proven themselves to be robust. +

+ +

+Most Go users will want to keep their Go installation at the latest +release tag. +New releases are announced on the +golang-announce +mailing list. +

+ +

+To update an existing tree to the latest release, you can run: +

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

+To use the weekly tag run hg update weekly instead. +

+ + +

Optional 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 + darwin (Mac OS X 10.5 and above), freebsd, + linux, netbsd, openbsd, + plan9, and windows. + Choices for $GOARCH are + amd64 (64-bit x86, the most mature port), + 386 (32-bit x86), and arm (32-bit ARM). + The valid combinations of $GOOS and $GOARCH are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
$GOOS $GOARCH
darwin 386
darwin amd64
freebsd 386
freebsd amd64
linux 386
linux amd64
linux arm
netbsd 386
netbsd amd64
openbsd 386
openbsd amd64
plan9 386
windows 386
windows amd64
+

+

+ +
+$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 run-time libraries should target. + Setting $GOARM to 5 causes the linker to emit calls + to a software floating point implementation instead of using + hardware floating point support. +

+
+ +

+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
+export GOOS=linux
+
diff --git a/doc/install.html b/doc/install.html index b3d48e379a7..04d466b7e54 100644 --- a/doc/install.html +++ b/doc/install.html @@ -5,257 +5,140 @@

Introduction

-

Go is an open source project, distributed under a -BSD-style license. -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 -compiler and tools (6g, 8g etc.). -For information on how to use gccgo, a more traditional -compiler using the GCC back end, see -Setting up and using gccgo. +Go is an open source project with a BSD-style license. +There are two official Go compiler toolchains: the gc Go compiler +and the gccgo compiler that is part of the GNU C Compiler (GCC).

-The Go compilers support three instruction sets. -There are important differences in the quality of the compilers for the different -architectures. -

- -
-
- amd64 (a.k.a. x86-64); 6g,6l,6c,6a -
-
- The most mature implementation. The compiler has an effective optimizer - (registerizer) and generates good code (although gccgo - can do noticeably better sometimes). -
-
- 386 (a.k.a. x86 or x86-32); 8g,8l,8c,8a -
-
- Comparable to the amd64 port. -
-
- arm (a.k.a. ARM); 5g,5l,5c,5a -
-
- Incomplete. - It only supports Linux binaries, the optimizer is incomplete, - and floating point uses the VFP unit. - However, all tests pass. - Work on the optimizer is continuing. - Tested against a Nexus One. -
-
- -

-Except for things like low-level operating system interface code, the run-time -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. +The gc compiler is the more mature and well-tested of the two. +This page is about installing a binary distribution of the gc +compiler.

-The compilers can target the FreeBSD, Linux, OpenBSD -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. +For information about installing the gc compiler from source, see +Installing Go from source. +For information about installing gccgo, see +Setting up and using gccgo.

-
- -

Install C tools, if needed

- -

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

-

- -

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

- -

On Ubuntu/Debian, use sudo apt-get install bison gawk gcc libc6-dev -make. If you want to build 32-bit binaries on a 64-bit system you'll -also need the libc6-dev-i386 package. -

- -

Install Mercurial, if needed

+

Obtaining the Go tools

-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==2.0
-
-(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.

+Visit the +Go project's downloads page +and select the binary distribution that matches +your operating system and processor architecture.

-Mercurial versions 1.7.x and up require the configuration of -Certification Authorities -(CAs). Error messages of the form: -

-
-warning: code.google.com certificate with fingerprint b1:af: ... bc not verified (check hostfingerprints or web.cacerts config setting)
-
-

-when using Mercurial indicate that the CAs are missing. -Check your Mercurial version (hg --version) and -configure the CAs -if necessary. +Official binary distributions are available +for the FreeBSD, Linux, Mac OS X, and Windows operating systems +and the 32-bit (386) and 64-bit (amd64) +x86 processor architectures.

-

Fetch the repository

+

+If a binary distribution is not available for your +OS/arch combination you may want to try +installing from source or +installing gccgo instead of gc. +

+ +

Installing the Go tools

-

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:

+The Go binary distributions assume they will be installed in +/usr/local/go, but it is possible to install them in a different +location. If you do this, you will need to set the GOROOT +environment variable to that directory when using the Go tools. +

+ +

+For example, if you installed Go to your home directory you should add the +following commands to $HOME/.profile: +

-$ hg clone -u release https://code.google.com/p/go
+export GOROOT=$HOME/go
+export PATH=$PATH:$GOROOT/bin
-

Install Go

+

FreeBSD and Linux

-To build the Go distribution, run +Extract the archive into /usr/local, creating a Go tree in +/usr/local/go (typically this must be run as root or through +sudo): 

-$ cd go/src
-$ ./all.bash
+tar -C /usr/local go.release.go1.tar.gz

-If all goes well, it will finish by printing output like: +Add /usr/local/go/bin to the PATH environment +variable. You can do this by adding this line to your /etc/profile +(for a system-wide installation) or $HOME/.profile: 

-ALL TESTS PASSED
-
----
-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.
+export PATH=$PATH:/usr/local/go/bin
+

Mac OS X

+

-where the details on the last few lines reflect the operating system, -architecture, and root directory used during the install. +Open the .pkg file and follow the prompts to install the Go tools. +The package installs the Go distribution to /usr/local/go.

-
+

+The package should put the /usr/local/go/bin directory in your +PATH environment variable. You may need to restart any open +Terminal sessions for the change to take effect. +

-

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

-
- -

Writing programs

+

Windows

-Given a file file.go, compile it using +TODO: windows installation instructions. +

+ +

Testing your installation

+ +

+Check that Go is installed correctly by building a simple program, as follows. +

+ +

+Create a file named hello.go and put the following program in it: 

-$ 6g file.go
-
- -

-6g is the Go compiler for amd64; it will write the output -in file.6. The ‘6’ identifies -files for the amd64 architecture. -The identifier letters for 386 and arm -are ‘8’ and ‘5’. -That is, if you were compiling for 386, you would use -8g and the output would be named file.8. -

- -

-To link the file, use -

- -
-$ 6l file.6
-
- -

-and to run it -

- -
-$ ./6.out
-
- -

A complete example: -

- -
-$ cat >hello.go <<EOF
 package main
 
 import "fmt"
 
 func main() {
-	fmt.Printf("hello, world\n")
+    fmt.Printf("hello, world\n")
 }
-EOF
-$ 6g hello.go
-$ 6l hello.6
-$ ./6.out
-hello, world
-$

-There is no need to list hello.6's package dependencies -(in this case, package fmt) on the 6l -command line. -The linker learns about them by reading hello.6. +Then run it with the go tool:

-
+
+$ go run hello.go
+hello, world
+
+

-To build more complicated programs, you will probably -want to use a -Makefile. -There are examples in places like -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. +If you see the "hello, world" message then your Go installation is working.

-

What's next

@@ -264,6 +147,11 @@ Start by taking A Tour of Go or reading the Go Tutorial.

+

+For more detail about the process of building and testing Go programs +read How to Write Go Code. +

+

Build a web application by following the Wiki Codelab. @@ -279,39 +167,6 @@ For the full story, consult Go's extensive documentation.

-

Keeping up with releases

- -

-The Go project maintains two stable tags in its Mercurial repository: -release and weekly. -The weekly tag is updated about once a week, and should be used by -those who want to track the project's development. -The release tag is given, less often, to those weekly releases -that have proven themselves to be robust. -

- -

-Most Go users will want to keep their Go installation at the latest -release tag. -New releases are announced on the -golang-announce -mailing list. -

- -

-To update an existing tree to the latest release, you can run: -

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

-To use the weekly tag run hg update weekly instead. -

Community resources

@@ -326,158 +181,6 @@ The official mailing list for discussion of the Go language is

-Bugs can be reported using the Go issue tracker. +Bugs should be reported using the +Go issue tracker.

- -

-For those who wish to keep up with development, -there is another mailing list, golang-checkins, -that receives a message summarizing each checkin to the Go repository. -

- -

Optional 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 go tool make 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 - darwin (Mac OS X 10.5 or 10.6), - freebsd, linux, openbsd, - 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
openbsd 386
openbsd amd64
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 run-time libraries should target. - Setting $GOARM to 5 causes the linker to emit calls - to a software floating point implementation instead of using - hardware floating point support. -
-
- -

-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
-export GOOS=linux
-