Setting up and using gccgo

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.

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.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 include a complete implementation of the Go 1.8.1 user libraries. As with earlier releases, the Go 1.8 runtime is not fully merged, but that should not be visible to Go programs.

The GCC 8 releases include a complete implementation of the Go 1.10.1 release. The Go 1.10 runtime has now been fully merged into the GCC development sources, and concurrent garbage collection is fully supported.

The GCC 9 releases include a complete implementation of the Go 1.12.2 release.

The GCC 10 releases include a complete implementation of the Go 1.14.6 release.

The GCC 11 releases include a complete implementation of the Go 1.16.3 release.

The GCC 12 and 13 releases include a complete implementation of the Go 1.18 standard library. However, GCC does not yet include support for generics.

Source code

If you cannot use a release, or prefer to build gccgo for yourself, the gccgo source code is accessible via Git. 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 the devel/gccgo branch of the main GCC code repository: git://gcc.gnu.org/git/gcc.git. 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

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.

Gold

Note: The gold linker is deprecated as of GNU Binutils 2.44 (February 2025) and may be removed in future releases. Consider using lld (LLVM's linker) as an alternative, which also supports split stacks on x86_64.

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 linker that supports split stacks. The gold linker version 2.22 or later supports this feature, as does lld.

If you still need to use gold, you can either install GNU binutils 2.22 or later (note: as of binutils 2.44, gold is in a separate binutils-with-gold tarball), 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):

git clone git://sourceware.org/git/binutils-gdb.git
mkdir binutils-objdir
cd binutils-objdir
../binutils-gdb/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. Similarly, for lld use --with-ld=/path/to/ld.lld.

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. The prerequisite libraries can be conveniently downloaded using the script contrib/download_prerequisites in the GCC sources.

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

git clone --branch devel/gccgo git://gcc.gnu.org/git/gcc.git gccgo
mkdir objdir
cd objdir
../gccgo/configure --prefix=/opt/gccgo --enable-languages=c,c++,go --with-ld=/opt/gold/bin/ld
make
make install

Using gccgo

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://go.dev/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).

Options

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.

Imports

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

Debugging

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.

C Interoperability

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

Types

Basic types map directly: an int32 in Go is an