From: Russ Cox Date: Fri, 23 Oct 2009 22:24:08 +0000 (-0700) Subject: write install docs X-Git-Tag: weekly.2009-11-06~207 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=fb39a4d676dc185bc961c38b84bc7d428418d2ee;p=gostls13.git write install docs R=r CC=go-dev http://go/go-review/1015004 --- diff --git a/doc/contribute.html b/doc/contribute.html index 389305706f..80aac32ead 100644 --- a/doc/contribute.html +++ b/doc/contribute.html @@ -1 +1,6 @@ + + TODO(go-dev): Write this document. +Have to work on the tools first. + + diff --git a/doc/install.html b/doc/install.html index 389305706f..1ab7b1422b 100644 --- a/doc/install.html +++ b/doc/install.html @@ -1 +1,197 @@ -TODO(go-dev): Write this document. + + +

Introduction

+ +

+There are two distinct ways to experiment with Go. +This document explains how to check out, build, and use the 6g Go +compiler and tools. +For information on how to use gccgo, a more traditional +compiler using the gcc back end, see +Setting up and using gccgo. +

+ +

Environment variables

+ +

The Go compilation environment depends on three environment +variables that you should set in your .bashrc or equivalent, +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 darwin (OS X), linux, +and nacl (Native Client, an incomplete port). +Choices for $GOARCH are amd64 (64-bit x86, the most stable port), +386 (32-bit x86, an unoptimized but stable port), and +arm (32-bit ARM, an incomplete port). +The valid combinations are +linux/amd64, +linux/arm, +linux/386, +darwin/amd64, +darwin/386, +and +nacl/386. +
+
$GOBIN (optional)
+
The location where binaries will be installed. +If you set $GOBIN, you need to ensure that it +is in your $PATH so that newly built Go-specific +command such as the compiler can be found during the build. +The default, $HOME/bin, may already be in your $PATH. +
+
+ +

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

+ +

+After setting these variables in your .bashrc, double-check them by +listing your environment. +

+ +
+$ env | grep '^GO'
+
+ +

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. +If that fails, visit the Mercurial Download page.

+ +

Make sure the $GOROOT directory does not exist or is empty. +Then check out the repository:

+ + +
+$ hg clone http://r45/ $GOROOT
+
+ +

Install Go

+ +

You need to have the parser generator Bison installed. +It is installed as part of Xcode on OS X. +If you need it on Linux, +

+ +
+$ sudo apt-get install bison
+
+ +

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

+ +

+To build the Go distribution, make sure $GOBIN +(or $HOME/bin if $GOBIN is not set) +is in your $PATH and then run +

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

+If all.bash goes well, it will finish by printing +

+ +
+--- cd ../test
+N known bugs; 0 unexpected bugs
+
+ +

+where N is a number that varies from release to release. +

+ +

Writing programs

+ +

+Given a file file.go, compile it using +

+ +
+$ 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")
+}
+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. +

+ +

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

+