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 (the license covers gccgo itself as part of GCC; it does not cover code generated by gccgo).
Note that gccgo is not the gc compiler; see
the Installing Go instructions for that
compiler.
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.1 release and all later 4.7 releases include a complete Go 1 compiler and libraries.
Due to timing, the GCC 4.8.0 and 4.8.1 releases are close to but not identical to Go 1.1. The GCC 4.8.2 release includes a complete Go 1.1.2 implementation.
The GCC 4.9 releases include a complete Go 1.2 implementation.
The GCC 5 releases include a complete implementation of the Go 1.4 user libraries. The Go 1.4 runtime is not fully merged, but that should not be visible to Go programs.
The GCC 6 releases include a complete implementation of the Go 1.6.1 user libraries. The Go 1.6 runtime is not fully merged, but that should not be visible to Go programs.
The GCC 7 releases are expected to include a complete implementation of the Go 1.8 user libraries. As with earlier releases, the Go 1.8 runtime is not fully merged, but that should not be visible to Go programs.
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 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 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.
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
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). 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.
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.
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):
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 ../src/configure --enable-gold=default --prefix=/opt/gold make make install
However you install gold, when you configure gccgo, use the
option --with-ld=GOLD_BINARY.
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.
The prerequisite libraries can be conveniently downloaded using the
script contrib/download_prerequisites in the GCC sources.
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 --prefix=/opt/gccgo --enable-languages=c,c++,go --with-ld=/opt/gold/bin/ld make make install
The gccgo compiler works like other gcc frontends. As of GCC 5 the gccgo
installation also includes a version of the go command,
which may be used to build Go programs as described at
https://golang.org/cmd/go.
To compile a file without using the go command:
gccgo -c file.go
That produces file.o. To link files together to form an
executable:
gccgo -o file file.o
To run the resulting file, you will need to tell the program where to find the compiled Go packages. There are a few ways to do this:
Set the LD_LIBRARY_PATH environment variable:
LD_LIBRARY_PATH=${prefix}/lib/gcc/MACHINE/VERSION
[or]
LD_LIBRARY_PATH=${prefix}/lib64/gcc/MACHINE/VERSION
export LD_LIBRARY_PATH
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 (replace lib with
lib64 if appropriate for your system):
go build -gccgoflags -Wl,-R,${prefix}/lib/gcc/MACHINE/VERSION
[or]
gccgo -o file file.o -Wl,-R,${prefix}/lib/gcc/MACHINE/VERSION
Use the -static-libgo option to link statically against
the compiled packages.
Use the -static option to do a fully static link (the
default for the gc compiler).
The gccgo compiler supports all GCC options
that are language independent, notably the -O
and -g options.
The -fgo-pkgpath=PKGPATH option may be used to set a
unique prefix for the package being compiled.
This option is automatically used by the go command, but you may want
to use it if you invoke gccgo directly.
This option is intended for use with large
programs that contain many packages, in order to allow multiple
packages to use the same identifier as the package name.
The PKGPATH may be any string; a good choice for the
string is the path used to import the package.
The -I and -L options, which are synonyms
for the compiler, may be used to set the search path for finding
imports.
These options are not needed if you build with the go command.
When you compile a file that exports something, the export information will be stored directly in the object file. If you build with gccgo directly, rather than with the go command, then when you import a package, you must tell gccgo how to find the file.
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.
FILE.gox
libFILE.so
libFILE.a
FILE.o
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
may pass the -I or -L option to
gccgo. Both options take directories to search. The
-L option is also passed to the linker.
The gccgo compiler does not currently (2015-06-15) record the file name of imported packages in the object file. You must arrange for the imported data to be linked into the program. Again, this is not necessary when building with the go command.
gccgo -c mypackage.go # Exports mypackage gccgo -c main.go # Imports mypackage gccgo -o main main.o mypackage.o # Explicitly links with mypackage.o
If you use the -g option when you compile, you can run
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
and interfaces will show up as two-element structures. Go
maps and channels are always represented as C pointers to run-time
structures.
When using gccgo there is limited interoperability with C,
or with C++ code compiled using extern "C".
Basic types map directly: an int32 in Go is
an int32_t in C, an int64 is
an int64_t, etc.
The Go type int is an integer that is the same size as a
pointer, and as such corresponds to the C type intptr_t.
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 {
const unsigned char *__data;
intptr_t __length;
};
You can't pass arrays between C and Go. However, a pointer to an
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 {
void *__values;
intptr_t __count;
intptr_t __capacity;
};
The type of a Go function is a pointer to a struct (this is subject to change). The first field in the struct points to the code of the function, which will be equivalent to a pointer to a C function whose parameter types are equivalent, with an additional trailing parameter. The trailing parameter is the closure, and the argument to pass is a pointer to the Go function struct. When a Go function returns more than one value, the C function returns a struct. For example, these functions are roughly equivalent:
func GoFunction(int) (int, float64)
struct { int i; float64 f; } CFunction(int, void*)
Go interface, channel, and map
types have no corresponding C type (interface is a
two-element struct and channel and map are
pointers to structs in C, but the structs are deliberately undocumented). C
enum types correspond to some integer type, but precisely
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 garbage collection. The exact guidelines in this area are undetermined, but it is likely that it will be permitted to pass a pointer to allocated memory from C to Go. The responsibility of eventually freeing the pointer will remain with C side, and of course if the C side frees the pointer 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.
Go code can call C functions directly using a Go extension implemented
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:
//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 syscall package):
var name = [4]byte{'f', 'o', 'o', 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).
Note that if the C function can block, such as in a call
to read, calling the C function may block the Go program.
Unless you have a clear understanding of what you are doing, all calls
between C and Go should be implemented through cgo or SWIG, as for
the gc compiler.
The name of Go functions accessed from C is subject to change. At present
the name of a Go function that does not have a receiver is
prefix.package.Functionname. The prefix is set by
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.
extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
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, 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.