From a84e3baf9a4008aea78babca18048c96ec46d598 Mon Sep 17 00:00:00 2001 From: Ian Lance Taylor Date: Tue, 20 Mar 2012 14:16:34 -0700 Subject: [PATCH] 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 | 335 ++++++++++++++++++++++++++--------------- 1 file changed, 217 insertions(+), 118 deletions(-) diff --git a/doc/gccgo_install.html b/doc/gccgo_install.html index e769c2211bd..a8d7396e533 100644 --- a/doc/gccgo_install.html +++ b/doc/gccgo_install.html @@ -4,36 +4,59 @@ }-->

-This document explains how to use gccgo, a compiler for -the Go language. The gccgo compiler is a new frontend -for gcc, the widely used GNU compiler. Although the -frontend itself is under a BSD-style license, gccgo is -normally used as part of gcc and is then covered by +This document explains how to use gccgo, a compiler for +the Go language. The gccgo compiler is a new frontend +for GCC, the widely used GNU compiler. Although the +frontend itself is under a BSD-style license, gccgo is +normally used as part of GCC and is then covered by the GNU General Public -License. +License (the license covers gccgo itself as part of GCC; it +does not cover code generated by gccgo).

-Note that gccgo is not the 6g compiler; see -the Installing Go instructions for that +Note that gccgo is not the gc compiler; see +the Installing Go instructions for that compiler.

+

Releases

+ +

+The simplest way to install gccgo is to install a GCC binary release +built to include Go support. GCC binary releases are available from +various +websites and are typically included as part of GNU/Linux +distributions. We expect that most people who build these binaries +will include Go support. +

+ +

+The GCC 4.7.0 release includes Go support that is very close to +Go 1. 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. +

+

Source code

-The gccgo source code is accessible via Subversion. The -gcc web site +If you cannot use a release, or prefer to build gccgo for +yourself, +the gccgo source code is accessible via Subversion. The +GCC web site has instructions for getting the -gcc source code. The gccgo source code -is a branch of the main gcc code +GCC source code. The gccgo source code is included. As a +convenience, a stable version of the Go support is available in +a branch of the main GCC code repository: svn://gcc.gnu.org/svn/gcc/branches/gccgo. +This branch is periodically updated with stable Go compiler sources.

Note that although gcc.gnu.org is the most convenient way -to get the source code for the compiler, that is not where the master -sources live. If you want to contribute changes to the gccgo +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 Go frontend compiler, see Contributing to gccgo.

@@ -42,29 +65,37 @@ gccgo.

Building

-Building gccgo is just like building gcc +Building gccgo is just like building GCC with one or two additional options. See the instructions on the gcc web site. When you run configure, add the option --enable-languages=c,c++,go (along with other languages you may want to build). If you are targeting a 32-bit x86, -then you will want to build gccgo 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 configure option --with-arch=i586 (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 -m32 option, then use the configure +option --with-arch-32=i586. +

+ +

Gold

+ +

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

-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 a development version of -the gold linker. The easiest way to do this is to build -the GNU binutils, using --enable-gold=default when you run -the configure script, and to -use --with-ld=GOLD_BINARY when you -configure gccgo. A typical sequence would look like +To build gold yourself, build the GNU binutils, +using --enable-gold=default when you run +the configure script. Before building, you must install +the flex and bison packages. A typical sequence would look like this (you can replace /opt/gold with any directory to which you have write access):

@@ -72,6 +103,7 @@ which you have write access): 
 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

-A number of prerequisites are required to build gcc, as -described on the gcc web site. If -those are all available, then a typical build and install sequence -would look like this (only use the --with-ld option if -you built and installed the gold linker as described above): +However you install gold, when you configure gccgo, use the +option --with-ld=GOLD_BINARY. +

+ +

Prerequisites

+ +

+A number of prerequisites are required to build GCC, as +described on +the gcc web +site. It is important to install all the prerequisites before +running the gcc configure script. + +

Build commands

+ +

+Once all the prerequisites are installed, then a typical build and +install sequence would look like this (only use +the --with-ld option if you are using the gold linker as +described above): 

 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
+

A note on Ubuntu

+ +

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

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

Using gccgo

-The gccgo 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 go command. However if you have the go +command from an installation of the gc compiler, you can +use it with gccgo by passing the option -compiler gccgo +to go build or go install or go +test. +

-To compile a file: +To compile a file without using the go command: +

 gccgo -c file.go
@@ -112,6 +184,7 @@ gccgo -c file.go
 

 That produces file.o. To link files together to form an
 executable:
+

 
 
 gccgo -o file file.o
@@ -119,44 +192,68 @@ gccgo -o file file.o
 
 

 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
-LD_LIBRARY_PATH in your environment:
+find the compiled Go packages.  There are a few ways to do this:
+

+
+
    
+
  • 
+
    
+Set the LD_LIBRARY_PATH environment variable:
+
    
 
 
    -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
 
    
 
 
    
-or by passing a -Wl,-R option when you link:
+Here ${prefix} is the --prefix option used
+when building gccgo.  For a binary install this is
+normally /usr.  Whether to use lib
+or lib64 depends on the target.
+Typically lib64 is correct for x86_64 systems,
+and lib is correct for other systems.  The idea is to
+name the directory where libgo.so is found.
+
    
+
+
    • 
+
+
  • 
+
    
+Passing a -Wl,-R option when you link:
+
    
 
 
    -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
 
    
+
    • 
 
+
  • 
 
    
-or you can use the -static-libgo link-time option to link
-statically against libgo, or you can do a fully static link (static
-linking is the default for the 6l Go linker).  On most
-systems, a static link will look something like:
-
-
    -gccgo -o file file.o -static -L /usr/lib/nptl -lgobegin -lgo -lpthread
-
    
+Use the -static-libgo option to link statically against
+the compiled packages.
+
    
+
    • 
 
+
  • 
 
    
-You may get a warning about not creating an .eh_frame_hdr
-section; this has nothing to do with Go, and may be ignored. In the
-future the requirement of explicitly specifying
--L /usr/lib/nptl -lgobegin -lgo -lpthread
-may be removed.
-
+Use the -static option to do a fully static link (the
+default for the gc compiler).
+
    
+
    • 
+

 
 
Options

 
 

-The gccgo compiler supports all gcc options
+The gccgo compiler supports all GCC options
 that are language independent, notably the -O
 and -g options.
+

 
 

 The -fgo-prefix=PREFIX 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 PREFIX may be any string; a good choice for the
 string is the directory where the package will be installed.
-
-

-The -fno-require-return-statement 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 6g.
+

 
 

 The -I and -L options, which are synonyms
 for the compiler, may be used to set the search path for finding
 imports.
-
+

 
 
Imports

 
 

-When you compile a file which exports something, the export
-information will be stored directly in the object file. When
-you import a package, you must tell gccgo how to
+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 gccgo how to
 find the file.
 
 

-When you import the package FILE with gccgo,
+When you import the package FILE 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.
 FILE.gox, when used, will typically contain
 nothing but export data. This can be generated from
 FILE.o via
+

 
 
 objcopy -j .go_export FILE.o FILE.gox
 

 
 

-The gccgo compiler will look in the current
-directory for import files. In more complex scenarios you
+The gccgo compiler will look in the current
+directory for import files.  In more complex scenarios you
 may pass the -I or -L option to
-gccgo. Both options take directories to search. The
+gccgo.  Both options take directories to search. The
 -L option is also passed to the linker.
+

 
-The gccgo compiler does not currently (2009-11-06) record
+

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

 
 
 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
 

 
-
Unimplemented

-
-

-Some Go features are not yet implemented in gccgo.  As of
-2010-08-23, the following are not implemented:
-
-
    
-
  • 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.
-

-
 
Debugging

 
 

 If you use the -g option when you compile, you can run
-gdb on your executable.  The debugger doesn't (yet)
-know anything about Go. However, you can set breakpoints, single-step,
+gdb on your executable.  The debugger has only limited
+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
-print *stringvar. In general Go strings, maps, channels
-and interfaces are always represented as C pointers.
+had C/C++ types.  For numeric types this doesn't matter.  Go strings
+and interfaces will show up as two-element structures.  Go
+maps and channels are always represented as C pointers to run-time
+structures.
+

 
 
C Interoperability

 
 

-When using gccgo there is limited interoperability with C,
+When using gccgo there is limited interoperability with C,
 or with C++ code compiled using extern "C".
+

 
 
Types

 
 

 Basic types map directly: an int in Go is an int
-in C, etc. Go byte is equivalent to C unsigned char.
+in C, an int32 is an int32_t,
+etc.  Go byte is equivalent to C unsigned
+char.
 Pointers in Go are pointers in C. A Go struct is the same as C
 struct with the same fields and types.
+

 
 

 The Go string type is currently defined as a two-element
 structure (this is subject to change):
+

 
 
 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 *[10]int is equivalent to C int*,
 assuming that the C pointer does point to 10 elements.
+

 
 

 A slice in Go is a structure.  The current definition is
 (this is subject to change):
+

 
 
 struct __go_slice {
@@ -294,9 +386,10 @@ struct __go_slice {
 
 

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

 
 
 func GoFunction(int) (int, float64)
@@ -305,7 +398,9 @@ struct { int i; float64 f; } CFunction(int)
 
 

 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
+subject to change).
+

 
 

 Go interface, channel, and map
@@ -317,6 +412,7 @@ which one is difficult to predict in general; use a cast. C union
 types have no corresponding Go type. C struct types containing
 bitfields have no corresponding Go type. C++ class types have
 no corresponding Go type.
+

 
 

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

 
 
Function names

 
 

 Go code can call C functions directly using a Go extension implemented
-in gccgo: a function declaration may be followed by
-__asm__("NAME"). For example, here is how the C function
+in gccgo: a function declaration may be preceded by
+//extern NAME.  For example, here is how the C function
 open can be declared in Go:
+

 
 
-func c_open(name *byte, mode int, perm int) int __asm__ ("open");
+//extern open
+func c_open(name *byte, mode int, perm int) int
 

 
 

 The C function naturally expects a NUL-terminated string, which in
 Go is equivalent to a pointer to an array (not a slice!) of
 byte with a terminating zero byte. So a sample call
-from Go would look like (after importing the os package):
+from Go would look like (after importing the syscall package):
+

 
 
 var name = [4]byte{'f', 'o', 'o', 0};
-i := c_open(&name[0], os.O_RDONLY, 0);
+i := c_open(&name[0], syscall.O_RDONLY, 0);
 

 
 

 (this serves as an example only, to open a file in Go please use Go's
 os.Open function instead).
+

 
 

 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 -fgo-prefix option used when the package is compiled;
 if the option is not used, the default is go.
 To call the function from C you must set the name using
-a gcc extension similar to the gccgo
-extension.
+a GCC extension.
+

 
 
 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
 
 

-The Go version of gcc supports automatically generating
-Go declarations from C code. The facility is rather awkward at present,
-and a better mechanism is under development.
+The Go version of GCC supports automatically generating
+Go declarations from C code. The facility is rather awkward, and most
+users should use the cgo program with
+the -gccgo option instead.
+

 
 

-Compile your C code as usual, but replace -c with
--S -ggo. The result will be an assembler file
-with a .s extension. This assembler file will contain
-comments beginning with #GO. Those comments are declarations in the Go
-language for the C types, variables and functions declared in the C code.
-C types which can not be represented in Go will contain the string INVALID.
-Unsupported macro definitions will be recorded as unknowndefine,
-and uses of #undef will be recorded as undef.
-So it is very approximately possible to get Go code by running
-
-
-gcc -S -ggo foo.c
-grep '#GO' foo.s | grep -v INVALID | grep -v unknowndefine | grep -v undef > foo.go
-

+Compile your C code as usual, and add the option
+-fdump-go-spec=FILENAME.  This will create the
+file FILENAME as a side effect of the
+compilation.  This file will contain Go declarations for the types,
+variables and functions declared in the C code.  C types that can not
+be represented in Go will be recorded as comments in the Go code.  The
+generated file will not have a package declaration, but
+can otherwise be compiled directly by gccgo.
+

 
 

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

 
 
RTEMS Port

 

-The gccgo compiler has been ported to 
+The gccgo compiler has been ported to 
 RTEMS. RTEMS is a real-time executive
 that provides a high performance environment for embedded applications
-on a range of processors and embedded hardware. The current gccgo
+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
 
 architectures supported by RTEMS. For more information on the port,