@include gcc-common.texi
@c Copyright years for this manual.
-@set copyrights-go 2010
+@set copyrights-go 2010, 2011, 2012
@copying
@c man begin COPYRIGHT
How you can share and copy this manual.
* Invoking gccgo:: How to run gccgo.
* Import and Export:: Importing and exporting package data.
-* C Interoperability:: Calling C from Go and vice-vera.
+* C Interoperability:: Calling C from Go and vice-versa.
* Index:: Index.
@end menu
@item -L@var{dir}
@cindex @option{-L}
-When compiling, synonymous with @option{-I}. When linking, specify a
-library search directory, as with @command{gcc}.
+When linking, specify a library search directory, as with
+@command{gcc}.
+
+@item -fgo-pkgpath=@var{string}
+@cindex @option{-fgo-pkgpath}
+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 @option{-I} option.
@item -fgo-prefix=@var{string}
@cindex @option{-fgo-prefix}
+An alternative to @option{-fgo-pkgpath}. The argument will be
+combined with the package name from the source file to produce the
+package path. If @option{-fgo-pkgpath} is used, @option{-fgo-prefix}
+will be ignored.
+
Go permits a single program to include more than one package with the
-same name. This option is required to make this work with
-@command{gccgo}. The argument to this option may be any string. Each
-package with the same name must use a distinct @option{-fgo-prefix}
-option. The argument is typically the full path under which the
-package will be installed, as that must obviously be unique.
+same name in the @code{package} clause in the source file, though
+obviously the two packages must be imported using different pathnames.
+In order for this to work with @command{gccgo}, either
+@option{-fgo-pkgpath} or @option{-fgo-prefix} must be specified when
+compiling a package.
+
+Using either @option{-fgo-pkgpath} or @option{-fgo-prefix} disables
+the special treatment of the @code{main} package and permits that
+package to be imported like any other.
@item -frequire-return-statement
@itemx -fno-require-return-statement
more return parameters but lack an explicit @code{return} statement.
This warning may be disabled using
@option{-fno-require-return-statement}.
+
+@item -fgo-check-divide-zero
+@cindex @option{-fgo-check-divide-zero}
+@cindex @option{-fno-go-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 @code{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
+@option{-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.
+
+@item -fgo-check-divide-overflow
+@cindex @option{-fgo-check-divide-overflow}
+@cindex @option{-fno-go-check-divide-overflow}
+Add explicit checks for division overflow. For example, division
+overflow occurs when computing @code{INT_MIN / -1}. In Go this should
+be wrapped, to produce @code{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
+@option{-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.
@end table
@c man end
package is imported, @command{gccgo} must be able to find the file.
@cindex @file{.gox}
-When Go code imports the package @file{gopackage}, @command{gccgo}
+When Go code imports the package @file{@var{gopackage}}, @command{gccgo}
will look for the import data using the following filenames, using the
first one that it finds.
@end table
The compiler will search for these files in the directories named by
-any @option{-I} or @option{-L} 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
-@samp{-I.}).
+any @option{-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 @samp{-I.}).
The compiler will extract the export information directly from the
compiled object file. The file @file{@var{gopackage}.gox} will
@node Function Names
@section Function Names
-@cindex @code{__asm__}
+@cindex @code{extern}
+@cindex external names
Go code can call C functions directly using a Go extension implemented
-in @command{gccgo}: a function declaration may be followed by
-@code{__asm__ ("@var{name}")}. For example, here is how the C function
-@code{open} can be declared in Go:
+in @command{gccgo}: a function declaration may be preceded by a
+comment giving the external name. The comment must be at the
+beginning of the line and must start with @code{//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 @code{open} can be
+declared in Go:
@smallexample
-func c_open(name *byte, mode int, perm int) int __asm__ ("open");
+//extern open
+func c_open(name *byte, mode int, perm int) int
@end smallexample
The C function naturally expects a nul terminated string, which in Go
@option{-fgo-prefix} option used when the package is compiled; if the
option is not used, the default is simply @code{go}. To call the
function from C you must set the name using the @command{gcc}
-extension similar to the @command{gccgo} extension.
+@code{__asm__} extension.
@smallexample
extern int go_function(int) __asm__ ("myprefix.mypackage.Function");