Download and install – The Go Programming Language

  1. Documentation
  2. Download and install
  3. Configuring 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 typically used as part of GCC and then covered by the GNU General Public License (the license covers gccgo as part of GCC; it does not cover code generated by gccgo).

Note that gccgo is not the gc compiler; see the Go installation instructions for that compiler

.

Versions

The easiest way to install gccgo is to install a binary version of GCC created to include Go support. Binary versions of GCC are available on various websites and are usually included as part of GNU/Linux distributions. We expect most people who create these binaries to include support for Go.

GCC version 4.7.1 and all

later 4.7 versions include a complete Go 1 compiler and libraries.

Due to time, GCC versions 4.8.0 and 4.8.1 are close, but not identical to Go 1.1. GCC version 4.8.2 includes a full implementation of Go 1.1.2.

GCC 4.9 releases include a full implementation of Go

1.2. GCC 5 releases include a full implementation

of the Go 1.4 user libraries. The Go 1.4 runtime isn’t completely combined, but that shouldn’t be visible to Go programs.

GCC 6 releases include a full implementation of the Go 1.6.1 user libraries. The Go 1.6 runtime isn’t completely combined, but that shouldn’t be visible to Go programs.

GCC 7 releases include a full implementation of the Go 1.8.1 user libraries. As with previous versions, the Go 1.8 runtime isn’t completely merged, but that shouldn’t be visible to Go programs.

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

GCC 9 releases include a full implementation of Go 1.12.2. GCC 10 releases include a full implementation of Go 1.14.6. GCC 11 releases include a full implementation of

Go 1.16.3. GCC

versions 12 and 13 include a

full implementation of

the

Go 1.18

standard library.

However, GCC does not yet include support for generics

.

Source

code

If you can’t use a version, or prefer to compile gccgo yourself, the gccgo source code can be accessed through Git. The GCC website has instructions for obtaining the GCC source code. The gccgo source code is included. For your convenience, a stable version of Go support is available in the devel/gccgo branch of the GCC master code repository: git://gcc.gnu.org/git/gcc.git. This branch is regularly updated with stable sources from the Go compiler.

Note that while gcc.gnu.org is the most convenient way to get the source code for the Go frontend, it’s not where master fonts live. If you want to contribute changes to the Go frontend compiler, see Contributing to gccgo.

Building

Building gccgo is like building GCC with one or two additional options. See the instructions on the GCC website. When you run configure, add the -enable-languages=c,c++,go option (along with other languages you want to compile). If you’re aiming for a 32-bit x86, then you’ll want to compile gccgo to support locked compare and swap instructions by default; To do this, also use the configure -with-arch=i586 option (or a newer architecture, depending on where you need the programs to run). If you are targeting a 64-bit x86, but sometimes want to use the -m32 option, use the configure -with-arch-32=i586 option.

Gold

On x86 GNU/Linux systems, the gccgo compiler is capable of using a small, non-contiguous stack for goroutines. This allows programs to run many more goroutines, as each goroutine can use a relatively small stack. To do this, it is necessary to use version 2.22 or later of the Gold Linker. You can install GNU binutils 2.22 or later, or you can build gold yourself.

To build gold yourself, compile 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 you have write access to):

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

Regardless of how you install gold, when configuring gccgo, use the -with-ld=GOLD_BINARY option

.

Prerequisites

Several prerequisites are required to create GCC, as described on the gcc website. It is important to install all prerequisites before running the gcc configure script. Prerequisite libraries can be conveniently downloaded using the contrib/download_prerequisites script in GCC sources.

Build commands

Once all the prerequisites are installed, 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 install

Using

gccgo

The gccgo compiler works like other gcc frontends. Starting with GCC 5, the gccgo installation also includes a version of the go command, which can be used to compile Go programs as described in 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 several ways to do this

: Set the environment variable LD_LIBRARY_PATH: 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 compiling gccgo. For a binary installation, this is typically /usr. The use of lib or lib64 depends on the destination. Normally, 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 located.

  • Pass a -Wl,-R option

  • when linking (replace lib with lib64 if appropriate for your system):

    go to 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 statically link to compiled packages. Use

  • the -static option

  • to create a fully static link (the default for the gc compiler).

Options

The gccgo compiler supports all GCC options that are language-independent, especially the -O and -g options

.

The -fgo-pkgpath=PKGPATH option can 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, to allow multiple packages to use the same identifier as the package name. The PKGPATH can be any string; A good choice for the chain is the path used to import the package.

The -I and -L options, which are synonymous with the compiler, can be used to set the search path for searching for imports. These options are not necessary if you compile with the go command.

Imports

When you compile a file that exports something, the export information is stored directly in the object file. If you compile with gccgo directly, rather than with the go command, when you import a package, you must tell gccgo how to find the file.

When you import the FILE package with gccgo, it searches for the import data in the following files and uses the first one it finds.

FILE.gox

  • libFILE.so
  • libFILE.a
  • FILE.or
  • 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 search the current directory for import files. In more complex scenarios, you can 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) register the filename of imported packages in the object file. You must arrange for the imported data to be linked to the program. Again, this is not necessary when compiling with the go command.

gccgo -c mypackage.go # Export mypackage gccgo -c main.go # Import mypackage gccgo -o main main.o mypackage.o # Explicit links to mypackage.o

Debugging

If you use the -g option when compiling, you can run gdb in the executable. The debugger has only limited knowledge about Go. You can set breakpoints, single step, etc. You can print variables, but they will print as if they were C/C++ typed. For numeric types this does not matter. Go strings and interfaces will be displayed as two-element structures. Go maps and channels are always represented as C pointers to runtime structures.

C

interoperability

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

Types

Basic type maps directly: an int32 in Go is a int32_t in C, an int64 is a int64_t, and so on. The Go int type is an integer that is the same size as a pointer and, as such, corresponds to type C intptr_t. Go byte is equivalent to C unsigned char. Pointers in Go are pointers in C. A Go structure is the same as a C structure with the same fields and types.

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

struct __go_string { const unsigned char *__data; intptr_t __length; };

You cannot 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 pointer C points to 10 elements.

A segment 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 structure (this is subject to change). The first field of the structure 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 end parameter. The final parameter is the closure and the argument to pass is a pointer to the structure of the Go function. When a Go function returns more than one value, the C function returns a structure. For example, these functions are approximately equivalent:

func GoFunction(int) (int, float64) struct { int i; float64 f; } CFunction(int, void*) The interface, channel, and

Go map types do not have the corresponding C type (the interface is a two-element structure and the channel and map are pointers to C structures, but the structures are not deliberately documented). The types of enumeration C correspond to some integer type, but precisely which one is difficult to predict in general; Use a cast. C junction types do not have the corresponding Go type. C structure types that contain bit fields do not have the 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 indeterminate, but it is likely that a pointer will be allowed to be passed to the mapped memory from C to Go. The responsibility for eventually releasing the pointer will remain with side C and, of course, if side C releases the pointer while side Go still has a copy, the program will fail. When you pass 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 can 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 can be preceded by //extern NAME. For example, here’s how you can declare the

C function open in Go: //extern open func c_open(name *byte, mode int, perm int) int

The C function naturally expects a string terminated in NUL, which in Go is equivalent to a pointer to an array (not a slice!) of byte with a zero byte terminated. Therefore, a sample Go call 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 only as an example, to open a file in Go, use the operating system of Go’s open function instead).

Note that if function C can crash, such as in a call to read, calling function C can 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, such as for the gc compiler.

The name of Go functions accessed from C is subject to change. Currently, the name of a Go function that does not have a sink is prefix.package.Functionname. The prefix is set using the -fgo-prefix option used when the package is compiled; If the option is not used, the default value 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”);

Automatic

generation of Go statements from C source code The Go version of

GCC supports automatic generation of Go statements from C code. The installation is quite inconvenient, and most users should use the cgo program with the -gccgo option instead.

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

This procedure is full of unstated warnings and restrictions and we do not guarantee that it will not change in the future. It is more useful as a starting point for actual Go code than as a regular procedure.