doc: general update of gccgo_install

Fixes #3325.

R=golang-dev, bradfitz, minux.ma, r
CC=golang-dev
https://golang.org/cl/5858043

doc/gccgo_install.html

@@ -4,36 +4,59 @@
 }-->
 
 <p>
-This document explains how to use <code>gccgo</code>, a compiler for
+This document explains how to use gccgo, a compiler for
-the Go language.  The <code>gccgo</code> compiler is a new frontend
+the Go language.  The gccgo compiler is a new frontend
-for <code>gcc</code>, the widely used GNU compiler.  Although the
+for GCC, the widely used GNU compiler.  Although the
-frontend itself is under a BSD-style license, <code>gccgo</code> is
+frontend itself is under a BSD-style license, gccgo is
-normally used as part of <code>gcc</code> and is then covered by
+normally used as part of GCC and is then covered by
 the <a href="http://www.gnu.org/licenses/gpl.html">GNU General Public
-License</a>.
+License</a> (the license covers gccgo itself as part of GCC; it
+does not cover code generated by gccgo).
 </p>
 
 <p>
-Note that <code>gccgo</code> is not the <code>6g</code> compiler; see
+Note that gccgo is not the <code>gc</code> compiler; see
-the <a href="/doc/install">Installing Go</a> instructions for that
+the <a href="/doc/install.html">Installing Go</a> instructions for that
 compiler.
 </p>
 
+<h2 id="Releases">Releases</h2>
+
+<p>
+The simplest way to install gccgo is to install a GCC binary release
+built to include Go support.  GCC binary releases are available from
+<a href="http://gcc.gnu.org/install/binaries.html">various
+websites</a> and are typically included as part of GNU/Linux
+distributions.  We expect that most people who build these binaries
+will include Go support.
+</p>
+
+<p>
+The GCC 4.7.0 release includes Go support that is very close to
+<a href="/doc/go1.html">Go 1</a>.  Due to release timing it will not
+include the last few changes to the Go 1 libraries.  The GCC 4.7.1
+release should include a complete Go 1 compiler and libraries.
+</p>
+
 <h2 id="Source_code">Source code</h2>
 
 <p>
-The <code>gccgo</code> source code is accessible via Subversion.  The
+If you cannot use a release, or prefer to build gccgo for
-<code>gcc</code> web site
+yourself, 
+the gccgo source code is accessible via Subversion.  The
+GCC web site
 has <a href="http://gcc.gnu.org/svn.html">instructions for getting the
-<code>gcc</code> source code</a>.  The <code>gccgo</code> source code
+GCC source code</a>.  The gccgo source code is included.  As a
-is a branch of the main <code>gcc</code> code
+convenience, a stable version of the Go support is available in
+a branch of the main GCC code
 repository: <code>svn://gcc.gnu.org/svn/gcc/branches/gccgo</code>.
+This branch is periodically updated with stable Go compiler sources.
 </p>
 
 <p>
 Note that although <code>gcc.gnu.org</code> is the most convenient way
-to get the source code for the compiler, that is not where the master
+to get the source code for the Go frontend, it is not where the master
-sources live.  If you want to contribute changes to the gccgo
+sources live.  If you want to contribute changes to the Go frontend
 compiler, see <a href="/doc/gccgo_contribute.html">Contributing to
 gccgo</a>.
 </p>
@@ -42,29 +65,37 @@ gccgo</a>.
 <h2 id="Building">Building</h2>
 
 <p>
-Building <code>gccgo</code> is just like building <code>gcc</code>
+Building gccgo is just like building GCC
 with one or two additional options.  See
 the <a href="http://gcc.gnu.org/install/">instructions on the gcc web
 site</a>.  When you run <code>configure</code>, add the
 option <code>--enable-languages=c,c++,go</code> (along with other
 languages you may want to build).  If you are targeting a 32-bit x86,
-then you will want to build <code>gccgo</code> to default to
+then you will want to build gccgo to default to
 supporting locked compare and exchange instructions; do this by also
 using the <code>configure</code> option <code>--with-arch=i586</code>
 (or a newer architecture, depending on where you need your programs to
-run).
+run).  If you are targeting a 64-bit x86, but sometimes want to use
+the <code>-m32</code> option, then use the <code>configure</code>
+option <code>--with-arch-32=i586</code>.
+</p>
+
+<h3 id="Gold">Gold</h3>
+
+<p>
+On x86 GNU/Linux systems the gccgo compiler is able to
+use a small discontiguous stack for goroutines.  This permits programs
+to run many more goroutines, since each goroutine can use a relatively
+small stack.  Doing this requires using the gold linker version 2.22
+or later.  You can either install GNU binutils 2.22 or later, or you
+can build gold yourself.
 </p>
 
 <p>
-On x86 GNU/Linux systems the <code>gccgo</code> compiler is able to
+To build gold yourself, build the GNU binutils,
-use a small discontiguous stack for goroutines.  This permits programs
+using <code>--enable-gold=default</code> when you run
-to run many more goroutines, since each goroutine can use a relatively
+the <code>configure</code> script.  Before building, you must install
-small stack.  Doing this requires using a development version of
+the flex and bison packages.  A typical sequence would look like
-the <code>gold</code> linker.  The easiest way to do this is to build
-the GNU binutils, using <code>--enable-gold=default</code> when you run
-the <code>configure</code> script, and to
-use <code>--with-ld=GOLD_BINARY</code> when you
-configure <code>gccgo</code>.  A typical sequence would look like
 this (you can replace <code>/opt/gold</code> with any directory to
 which you have write access):
 </p>
@@ -72,6 +103,7 @@ which you have write access):
 <pre>
 cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
 [password is "anoncvs"]
+[The next command will create a directory named src, not binutils]
 cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils
 mkdir binutils-objdir
 cd binutils-objdir
@@ -81,29 +113,69 @@ make install
 </pre>
 
 <p>
-A number of prerequisites are required to build <code>gcc</code>, as
+However you install gold, when you configure gccgo, use the
-described on the <a href="http://gcc.gnu.org/">gcc web site</a>.  If
+option <code>--with-ld=<var>GOLD_BINARY</var></code>.
-those are all available, then a typical build and install sequence
+</p>
-would look like this (only use the <code>--with-ld</code> option if
+
-you built and installed the gold linker as described above):
+<h3 id="Prerequisites">Prerequisites</h3>
+
+<p>
+A number of prerequisites are required to build GCC, as
+described on
+the <a href="http://gcc.gnu.org/install/prerequisites.html">gcc web
+site</a>.  It is important to install all the prerequisites before
+running the gcc <code>configure</code> script.
+
+<h3 id="Build_commands">Build commands</h3>
+
+<p>
+Once all the prerequisites are installed, then a typical build and
+install sequence would look like this (only use
+the <code>--with-ld</code> option if you are using the gold linker as
+described above):
 </p>
 
 <pre>
 svn checkout svn://gcc.gnu.org/svn/gcc/branches/gccgo gccgo
 mkdir objdir
 cd objdir
-../gccgo/configure --enable-languages=c,c++,go --with-ld=/opt/gold/bin/ld
+../gccgo/configure --prefix=/opt/gccgo --enable-languages=c,c++,go --with-ld=/opt/gold/bin/ld
 make
 make install
 </pre>
 
+<h3 id="Ubuntu">A note on Ubuntu</h3>
+
+<p>
+Current versions of Ubuntu and current versions of gcc disagree on
+where system libraries and header files are found.  This is not a
+gccgo issue, and we hope this will be resolved soon.  Until it is,
+setting these environment variables while configuring and building
+gccgo may fix the problem.
+</p>
+
+<pre>
+LIBRARY_PATH=/usr/lib/x86_64-linux-gnu
+C_INCLUDE_PATH=/usr/include/x86_64-linux-gnu
+CPLUS_INCLUDE_PATH=/usr/include/x86_64-linux-gnu
+export LIBRARY_PATH C_INCLUDE_PATH CPLUS_INCLUDE_PATH
+</pre>
+
 <h2 id="Using_gccgo">Using gccgo</h2>
 
 <p>
-The <code>gccgo</code> compiler works like other gcc frontends.
+The gccgo compiler works like other gcc frontends.  The gccgo
+installation does not currently include a version of
+the <code>go</code> command.  However if you have the <code>go</code>
+command from an installation of the <code>gc</code> compiler, you can
+use it with gccgo by passing the option <code>-compiler gccgo</code>
+to <code>go build</code> or <code>go install</code> or <code>go
+test</code>.
+</p>
 
 <p>
-To compile a file:
+To compile a file without using the <code>go</code> command:
+</p>
 
 <pre>
 gccgo -c file.go
@@ -112,6 +184,7 @@ gccgo -c file.go
 <p>
 That produces <code>file.o</code>. To link files together to form an
 executable:
+</p>
 
 <pre>
 gccgo -o file file.o
@@ -119,44 +192,68 @@ gccgo -o file file.o
 
 <p>
 To run the resulting file, you will need to tell the program where to
-find the compiled Go packages. This can be done either by setting
+find the compiled Go packages.  There are a few ways to do this:
-<code>LD_LIBRARY_PATH</code> in your environment:
+</p>
+
+<ul>
+<li>
+<p>
+Set the <code>LD_LIBRARY_PATH</code> environment variable:
+</p>
 
 <pre>
-LD_LIBRARY_PATH=/usr/lib/gcc/MACHINE/VERSION
+LD_LIBRARY_PATH=${prefix}/lib/gcc/MACHINE/VERSION
+[or]
+LD_LIBRARY_PATH=${prefix}/lib64/gcc/MACHINE/VERSION
+export LD_LIBRARY_PATH
 </pre>
 
 <p>
-or by passing a <code>-Wl,-R</code> option when you link:
+Here <code>${prefix}</code> is the <code>--prefix</code> option used
+when building gccgo.  For a binary install this is
+normally <code>/usr</code>.  Whether to use <code>lib</code>
+or <code>lib64</code> depends on the target.
+Typically <code>lib64</code> is correct for x86_64 systems,
+and <code>lib</code> is correct for other systems.  The idea is to
+name the directory where <code>libgo.so</code> is found.
+</p>
+
+</li>
+
+<li>
+<p>
+Passing a <code>-Wl,-R</code> option when you link:
+</p>
 
 <pre>
-gccgo -o file file.o -Wl,-R,/usr/lib/gcc/MACHINE/VERSION
+gccgo -o file file.o -Wl,-R,${prefix}/lib/gcc/MACHINE/VERSION
+[or]
+gccgo -o file file.o -Wl,-R,${prefix}/lib64/gcc/MACHINE/VERSION
 </pre>
+</li>
 
+<li>
 <p>
-or you can use the <code>-static-libgo</code> link-time option to link
+Use the <code>-static-libgo</code> option to link statically against
-statically against libgo, or you can do a fully static link (static
+the compiled packages.
-linking is the default for the <code>6l</code> Go linker).  On most
+</p>
-systems, a static link will look something like:
+</li>
-
-<pre>
-gccgo -o file file.o -static -L /usr/lib/nptl -lgobegin -lgo -lpthread
-</pre>
 
+<li>
 <p>
-You may get a warning about not creating an <code>.eh_frame_hdr</code>
+Use the <code>-static</code> option to do a fully static link (the
-section; this has nothing to do with Go, and may be ignored. In the
+default for the <code>gc</code> compiler).
-future the requirement of explicitly specifying
+</p>
-<code>-L /usr/lib/nptl -lgobegin -lgo -lpthread</code>
+</li>
-may be removed.
+</ul>
-
 
 <h2 id="Options">Options</h2>
 
 <p>
-The <code>gccgo</code> compiler supports all <code>gcc</code> options
+The gccgo compiler supports all GCC options
 that are language independent, notably the <code>-O</code>
 and <code>-g</code> options.
+</p>
 
 <p>
 The <code>-fgo-prefix=PREFIX</code> option may be used to set a unique
@@ -165,28 +262,24 @@ use with large programs that contain many packages, in order to allow
 multiple packages to use the same identifier as the package name.
 The <code>PREFIX</code> may be any string; a good choice for the
 string is the directory where the package will be installed.
-
+</p>
-<p>
-The <code>-fno-require-return-statement</code> option may be used to
-disable the compiler error about functions missing return statements.
-Note that there is no way to disable this error in <code>6g</code>.
 
 <p>
 The <code>-I</code> and <code>-L</code> options, which are synonyms
 for the compiler, may be used to set the search path for finding
 imports.
-
+</p>
 
 <h2 id="Imports">Imports</h2>
 
 <p>
-When you compile a file which exports something, the export
+When you compile a file that exports something, the export
 information will be stored directly in the object file.  When
-you import a package, you must tell <code>gccgo</code> how to
+you import a package, you must tell gccgo how to
 find the file.
 
 <p>
-When you import the package <var>FILE</var> with <code>gccgo</code>,
+When you import the package <var>FILE</var> with gccgo,
 it will look for the import data in the following files, and use the
 first one that it finds.
 
@@ -201,21 +294,25 @@ first one that it finds.
 <code><var>FILE</var>.gox</code>, when used, will typically contain
 nothing but export data. This can be generated from
 <code><var>FILE</var>.o</code> via
+</p>
 
 <pre>
 objcopy -j .go_export FILE.o FILE.gox
 </pre>
 
 <p>
-The <code>gccgo</code> compiler will look in the current
+The gccgo compiler will look in the current
 directory for import files.  In more complex scenarios you
 may pass the <code>-I</code> or <code>-L</code> option to
-<code>gccgo</code>. Both options take directories to search. The
+gccgo.  Both options take directories to search. The
 <code>-L</code> option is also passed to the linker.
+</p>
 
-The <code>gccgo</code> compiler does not currently (2009-11-06) record
+<p>
+The gccgo compiler does not currently (2012-03-20) record
 the file name of imported packages in the object file. You must
 arrange for the imported data to be linked into the program.
+</p>
 
 <pre>
 gccgo -c mypackage.go              # Exports mypackage
@@ -223,48 +320,41 @@ gccgo -c main.go                   # Imports mypackage
 gccgo -o main main.o mypackage.o   # Explicitly links with mypackage.o
 </pre>
 
-<h2 id="Unimplemented">Unimplemented</h2>
-
-<p>
-Some Go features are not yet implemented in <code>gccgo</code>.  As of
-2010-08-23, the following are not implemented:
-
-<ul>
-<li>goroutines are implemented as NPTL threads.  If you can not use
-    the gold linker as described above, they are created with a fixed
-    stack size, and the number of goroutines that may be created at
-    one time is limited.
-</ul>
-
 <h2 id="Debugging">Debugging</h2>
 
 <p>
 If you use the <code>-g</code> option when you compile, you can run
-<code>gdb</code> on your executable.  The debugger doesn't (yet)
+<code>gdb</code> on your executable.  The debugger has only limited
-know anything about Go. However, you can set breakpoints, single-step,
+knowledge about Go.  You can set breakpoints, single-step,
 etc.  You can print variables, but they will be printed as though they
 had C/C++ types.  For numeric types this doesn't matter.  Go strings
-will show up as pointers to structures; to see the value
+and interfaces will show up as two-element structures.  Go
-<code>print *stringvar</code>. In general Go strings, maps, channels
+maps and channels are always represented as C pointers to run-time
-and interfaces are always represented as C pointers.
+structures.
+</p>
 
 <h2 id="C_Interoperability">C Interoperability</h2>
 
 <p>
-When using <code>gccgo</code> there is limited interoperability with C,
+When using gccgo there is limited interoperability with C,
 or with C++ code compiled using <code>extern "C"</code>.
+</p>
 
 <h3 id="Types">Types</h3>
 
 <p>
 Basic types map directly: an <code>int</code> in Go is an <code>int</code>
-in C, etc. Go <code>byte</code> is equivalent to C <code>unsigned char</code>.
+in C, an <code>int32</code> is an <code>int32_t</code>,
+etc.  Go <code>byte</code> is equivalent to C <code>unsigned
+char</code>.
 Pointers in Go are pointers in C. A Go <code>struct</code> is the same as C
 <code>struct</code> with the same fields and types.
+</p>
 
 <p>
 The Go <code>string</code> type is currently defined as a two-element
 structure (this is <b style="color: red;">subject to change</b>):
+</p>
 
 <pre>
 struct __go_string {
@@ -279,10 +369,12 @@ array in Go is equivalent to a C pointer to the
 equivalent of the element type.
 For example, Go <code>*[10]int</code> is equivalent to C <code>int*</code>,
 assuming that the C pointer does point to 10 elements.
+</p>
 
 <p>
 A slice in Go is a structure.  The current definition is
 (this is <b style="color: red;">subject to change</b>):
+</p>
 
 <pre>
 struct __go_slice {
@@ -297,6 +389,7 @@ The type of a Go function with no receiver is equivalent to a C function
 whose parameter types are equivalent.  When a Go function returns more
 than one value, the C function returns a struct.  For example, these
 functions have equivalent types:
+</p>
 
 <pre>
 func GoFunction(int) (int, float64)
@@ -305,7 +398,9 @@ struct { int i; float64 f; } CFunction(int)
 
 <p>
 A pointer to a Go function is equivalent to a pointer to a C function
-when the functions have equivalent types.
+when the functions have equivalent types (this is
+<b style="color: red;">subject to change</b>).
+</p>
 
 <p>
 Go <code>interface</code>, <code>channel</code>, and <code>map</code>
@@ -317,6 +412,7 @@ which one is difficult to predict in general; use a cast. C <code>union</code>
 types have no corresponding Go type. C <code>struct</code> types containing
 bitfields have no corresponding Go type. C++ <code>class</code> types have
 no corresponding Go type.
+</p>
 
 <p>
 Memory allocation is completely different between C and Go, as Go uses
@@ -328,33 +424,38 @@ while the Go side still has a copy the program will fail. When passing a
 pointer from Go to C, the Go function must retain a visible copy of it in
 some Go variable. Otherwise the Go garbage collector may delete the
 pointer while the C function is still using it.
+</p>
 
 <h3 id="Function_names">Function names</h3>
 
 <p>
 Go code can call C functions directly using a Go extension implemented
-in <code>gccgo</code>: a function declaration may be followed by
+in gccgo: a function declaration may be preceded by
-<code>__asm__("NAME")</code>. For example, here is how the C function
+<code>//extern NAME</code>.  For example, here is how the C function
 <code>open</code> can be declared in Go:
+</p>
 
 <pre>
-func c_open(name *byte, mode int, perm int) int __asm__ ("open");
+//extern open
+func c_open(name *byte, mode int, perm int) int
 </pre>
 
 <p>
 The C function naturally expects a NUL-terminated string, which in
 Go is equivalent to a pointer to an array (not a slice!) of
 <code>byte</code> with a terminating zero byte. So a sample call
-from Go would look like (after importing the <code>os</code> package):
+from Go would look like (after importing the <code>syscall</code> package):
+</p>
 
 <pre>
 var name = [4]byte{'f', 'o', 'o', 0};
-i := c_open(&amp;name[0], os.O_RDONLY, 0);
+i := c_open(&amp;name[0], syscall.O_RDONLY, 0);
 </pre>
 
 <p>
 (this serves as an example only, to open a file in Go please use Go's
 <code>os.Open</code> function instead).
+</p>
 
 <p>
 The name of Go functions accessed from C is subject to change. At present
@@ -363,8 +464,8 @@ the name of a Go function that does not have a receiver is
 the <code>-fgo-prefix</code> option used when the package is compiled;
 if the option is not used, the default is <code>go</code>.
 To call the function from C you must set the name using
-a <code>gcc</code> extension similar to the <code>gccgo</code>
+a GCC extension.
-extension.
+</p>
 
 <pre>
 extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
@@ -374,37 +475,35 @@ extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
 Automatic generation of Go declarations from C source code</h3>
 
 <p>
-The Go version of <code>gcc</code> supports automatically generating
+The Go version of GCC supports automatically generating
-Go declarations from C code. The facility is rather awkward at present,
+Go declarations from C code. The facility is rather awkward, and most
-and a better mechanism is under development.
+users should use the <a href="/cmd/cgo">cgo</a> program with
+the <code>-gccgo</code> option instead.
+</p>
 
 <p>
-Compile your C code as usual, but replace <code>-c</code> with
+Compile your C code as usual, and add the option
-<code>-S&nbsp;-ggo</code>. The result will be an assembler file
+<code>-fdump-go-spec=<var>FILENAME</var></code>.  This will create the
-with a <code>.s</code> extension. This assembler file will contain
+file <code><var>FILENAME</var></code> as a side effect of the
-comments beginning with #GO. Those comments are declarations in the Go
+compilation.  This file will contain Go declarations for the types,
-language for the C types, variables and functions declared in the C code.
+variables and functions declared in the C code.  C types that can not
-C types which can not be represented in Go will contain the string INVALID.
+be represented in Go will be recorded as comments in the Go code.  The
-Unsupported macro definitions will be recorded as <code>unknowndefine</code>,
+generated file will not have a <code>package</code> declaration, but
-and uses of <code>#undef</code> will be recorded as <code>undef</code>.
+can otherwise be compiled directly by gccgo.
-So it is very approximately possible to get Go code by running
+</p>
-
-<pre>
-gcc -S -ggo foo.c
-grep '#GO' foo.s | grep -v INVALID | grep -v unknowndefine | grep -v undef > foo.go
-</pre>
 
 <p>
 This procedure is full of unstated caveats and restrictions and we make no
 guarantee that it will not change in the future. It is more useful as a
 starting point for real Go code than as a regular procedure.
+</p>
 
 <h2 id="RTEMS_Port">RTEMS Port</h2>
 <p>
-The <code>gccgo</code> compiler has been ported to <a href="http://www.rtems.com/">
+The gccgo compiler has been ported to <a href="http://www.rtems.com/">
 <code>RTEMS</code></a>. <code>RTEMS</code> is a real-time executive
 that provides a high performance environment for embedded applications
-on a range of processors and embedded hardware. The current <code>gccgo</code>
+on a range of processors and embedded hardware. The current gccgo
 port is for x86. The goal is to extend the port to most of the
 <a href="http://www.rtems.org/wiki/index.php/SupportedCPUs">
 architectures supported by <code>RTEMS</code></a>. For more information on the port,