     [file gcc-common.texi not included]

Copyright © 2010-2017 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, the Front-Cover Texts being (a) (see below), and with the Back-Cover Texts being (b) (see below). A copy of the license is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU software.  Copies published by the Free Software Foundation raise funds for GNU development.

Introduction
************

This manual describes how to use gccgo, the GNU compiler for the Go programming language.  This manual is specifically about gccgo.  For more information about the Go programming language in general, including language specifications and standard package documentation, see http://golang.org/.

     [file gpl_v3.texi not included]

     [file fdl.texi not included]

Invoking gccgo
**************

The gccgo command is a frontend to gcc and supports many of the same options.  See Option Summary (Using the GNU Compiler Collection (GCC)).  This manual only documents the options specific to gccgo.

The gccgo command may be used to compile Go source code into an object file, link a collection of object files together, or do both in sequence.

Go source code is compiled as packages.  A package consists of one or more Go source files.  All the files in a single package must be compiled together, by passing all the files as arguments to gccgo.  A single invocation of gccgo may only compile a single package.

One Go package may import a different Go package.  The imported package must have already been compiled; gccgo will read the import data directly from the compiled package.  When this package is later linked, the compiled form of the package must be included in the link command.

Go programs must generally be compiled with debugging information, and -g1 is the default as described below.  Stripping a Go program will generally cause it to misbehave or fail.

-IDIR
     Specify a directory to use when searching for an import package at compile time.

-LDIR
     When linking, specify a library search directory, as with gcc.

-fgo-pkgpath=STRING
     Set the package path to use.  This sets the value returned by the PkgPath method of reflect.Type objects.  It is also used for the names of globally visible symbols.  The argument to this option should normally be the string that will be used to import this package after it has been installed; in other words, a pathname within the directories specified by the -I option.

-fgo-prefix=STRING
     An alternative to -fgo-pkgpath.  The argument will be combined with the package name from the source file to produce the package path.  If -fgo-pkgpath is used, -fgo-prefix will be ignored.

     Go permits a single program to include more than one package with the same name in the package clause in the source file, though obviously the two packages must be imported using different pathnames. In order for this to work with gccgo, either -fgo-pkgpath or -fgo-prefix must be specified when compiling a package.

     Using either -fgo-pkgpath or -fgo-prefix disables the special treatment of the main package and permits that package to be imported like any other.

-fgo-relative-import-path=DIR
     A relative import is an import that starts with ./ or ../.  If this option is used, gccgo will use DIR as a prefix for the relative import when searching for it.

-frequire-return-statement
-fno-require-return-statement
     By default gccgo will warn about functions which have one or more return parameters but lack an explicit return statement. This warning may be disabled using -fno-require-return-statement.

-fgo-check-divide-zero
     Add explicit checks for division by zero.  In Go a division (or modulos) by zero causes a panic.  On Unix systems this is detected in the runtime by catching the SIGFPE signal.  Some processors, such as PowerPC, do not generate a SIGFPE on division by zero.  Some runtimes do not generate a signal that can be caught.  On those systems, this option may be used.  Or the checks may be removed via -fno-go-check-divide-zero.  This option is currently on by default, but in the future may be off by default on systems that do not require it.

-fgo-check-divide-overflow
     Add explicit checks for division overflow.  For example, division overflow occurs when computing INT_MIN / -1.  In Go this should be wrapped, to produce INT_MIN.  Some processors, such as x86, generate a trap on division overflow.  On those systems, this option may be used.  Or the checks may be removed via -fno-go-check-divide-overflow.  This option is currently on by default, but in the future may be off by default on systems that do not require it.

-fgo-optimize-allocs
     Use escape analysis to allocate objects on the stack rather than the heap when possible.  In the future this may be the default.

-fgo-debug-escapeN
     Output escape analysis debugging information.  Larger values of N generate more information.

-fgo-c-header=FILE
     Write top-level named Go struct definitions to FILE as C code. This is used when compiling the runtime package.

-fgo-compiling-runtime
     Apply special rules for compiling the runtime package.  Implicit memory allocation is forbidden.  Some additional compiler directives are supported.

-g
     This is the standard gcc option (see Debugging Options (Using the GNU Compiler Collection (GCC))).  It is mentioned here because by default gccgo turns on debugging information generation with the equivalent of the standard option -g1.  This is because Go programs require debugging information to be available in order to get backtrace information.  An explicit -g0 may be used to disable the generation of debugging information, in which case certain standard library functions, such as runtime.Callers, will not operate correctly.

Import and Export
*****************

When gccgo compiles a package which exports anything, the export information will be stored directly in the object file.  When a package is imported, gccgo must be able to find the file.

When Go code imports the package GOPACKAGE, gccgo will look for the import data using the following filenames, using the first one that it finds.

GOPACKAGE.gox

libGOPACKAGE.so

libGOPACKAGE.a

GOPACKAGE.o

The compiler will search for these files in the directories named by any -I options, in order in which the directories appear on the command line.  The compiler will then search several standard system directories.  Finally the compiler will search the current directory (to search the current directory earlier, use -I.).

The compiler will extract the export information directly from the compiled object file.  The file GOPACKAGE.gox will typically contain nothing but export data.  This can be generated from GOPACKAGE.o via

     objcopy -j .go_export GOPACKAGE.o GOPACKAGE.gox

For example, it may be desirable to extract the export information from several different packages into their independent GOPACKAGE.gox files, and then to combine the different package object files together into a single shared library or archive.

At link time you must explicitly tell gccgo which files to link together into the executable, as is usual with gcc. This is different from the behavior of other Go compilers.

Compiler Directives
*******************

The Go compiler supports a few compiler directives.  A compiler directive uses a // comment at the start of a line.  There must be no space between the // and the name of the directive.

//line FILE:LINE
     The //line directive specifies that the source line that follows should be recorded as having come from the given file path and line number.  Successive lines are recorded using increasing line numbers, until the next directive.  This directive typically appears in machine-generated code, so that compilers and debuggers will show lines in the original input to the generator.

//extern EXTERN_NAME
     The extern directive sets the externally visible name of the next function declaration.  See Function Names.

//go:compile GO_NAME EXTERN_NAME
     The go:compile directives sets the externally visible name of a function definition or declaration.  See Function Names.

//go:noescape
     The //go:noescape directive specifies that the next declaration in the file, which must be a func without a body (meaning that it has an implementation not written in Go) does not allow any of the pointers passed as arguments to escape into the heap or into the values returned from the function. This information can be used during the compiler's escape analysis of Go code calling the function.

//go:nosplit
     The //go:nosplit directive specifies that the next function declared in the file must not include a stack overflow check. This is most commonly used by low-level runtime sources invoked at times when it is unsafe for the calling goroutine to be preempted.

//go:noinline
     The //go:noinline directive specifies that the next function defined in the file may not be inlined.

C Interoperability
******************

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

This information is provided largely for documentation purposes.  For ordinary use it is best to build programs with the go tool and then use import "C", as described at http://golang.org/cmd/cgo.

C Type Interoperability
=======================

Basic types map directly: an int in Go is an int in C, 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 field names and types.

The Go string type is currently defined as a two-element structure:

     struct __go_string {
       const unsigned char *__data;
       int __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:

     struct __go_slice {
       void *__values;
       int __count;
       int __capacity;
     };

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:

     func GoFunction(int) (int, float)
     struct { int i; float f; } CFunction(int)

A pointer to a Go function is equivalent to a pointer to a C function when the functions have equivalent types.

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.

Function Names
==============

Go code can call C functions directly using the //extern or //go:linkname compiler directives.  An //extern directive must be at the beginning of the line and must start with //extern.  This must be followed by a space and then the external name of the function.  The function declaration must be on the line immediately after the comment.  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

You can do the same thing using the //go:linkname compiler directive.  The //go:linkname directive must be at the start of the line.  It is followed by whitespace, the name of the Go function, more whitespace, and the external name of the function.  Unlike //extern, //go:linkname does not need to appear immediately adjacent to the function definition or declaration.

     //go:linkname c_open 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):

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

Note that 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 the name of a Go function that does not have a receiver is pkgpath.Functionname.  The PKGPATH is set by the -fgo-pkgpath option used when the package is compiled; if the option is not used, the default is go.PACKAGENAME.  To call the function from C you must set the name using the gcc __asm__ extension.

     extern int go_function(int) __asm__ ("mypkgpath.Function");