mirror of
https://github.com/golang/go
synced 2024-09-05 16:04:50 +00:00
![Suriyaa Sundararuban](/assets/img/avatar_default.png)
Change-Id: I9d2d25df067ca573589db5ff18296a5ec33866be Reviewed-on: https://go-review.googlesource.com/118595 Reviewed-by: Ian Lance Taylor <iant@golang.org>
535 lines
17 KiB
HTML
535 lines
17 KiB
HTML
<!--{
|
|
"Title": "Setting up and using gccgo",
|
|
"Path": "/doc/install/gccgo"
|
|
}-->
|
|
|
|
<p>
|
|
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 <a href="https://www.gnu.org/licenses/gpl.html">GNU General Public
|
|
License</a> (the license covers gccgo itself as part of GCC; it
|
|
does not cover code generated by gccgo).
|
|
</p>
|
|
|
|
<p>
|
|
Note that gccgo is not the <code>gc</code> compiler; see
|
|
the <a href="/doc/install.html">Installing Go</a> instructions for that
|
|
compiler.
|
|
</p>
|
|
|
|
<h2 id="Releases">Releases</h2>
|
|
|
|
<p>
|
|
The simplest way to install gccgo is to install a GCC binary release
|
|
built to include Go support. GCC binary releases are available from
|
|
<a href="https://gcc.gnu.org/install/binaries.html">various
|
|
websites</a> and are typically included as part of GNU/Linux
|
|
distributions. We expect that most people who build these binaries
|
|
will include Go support.
|
|
</p>
|
|
|
|
<p>
|
|
The GCC 4.7.1 release and all later 4.7 releases include a complete
|
|
<a href="/doc/go1.html">Go 1</a> compiler and libraries.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
The GCC 4.9 releases include a complete Go 1.2 implementation.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
The GCC 8 releases are expected to include a complete implementation
|
|
of the Go 1.10 release, depending on release timing. The Go 1.10
|
|
runtime has now been fully merged into the GCC development sources,
|
|
and concurrent garbage collection is expected to be fully supported in
|
|
GCC 8.
|
|
</p>
|
|
|
|
<h2 id="Source_code">Source code</h2>
|
|
|
|
<p>
|
|
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 <a href="https://gcc.gnu.org/svn.html">instructions for getting the
|
|
GCC source code</a>. 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: <code>svn://gcc.gnu.org/svn/gcc/branches/gccgo</code>.
|
|
This branch is periodically updated with stable Go compiler sources.
|
|
</p>
|
|
|
|
<p>
|
|
Note that although <code>gcc.gnu.org</code> 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 <a href="/doc/gccgo_contribute.html">Contributing to
|
|
gccgo</a>.
|
|
</p>
|
|
|
|
|
|
<h2 id="Building">Building</h2>
|
|
|
|
<p>
|
|
Building gccgo is just like building GCC
|
|
with one or two additional options. See
|
|
the <a href="https://gcc.gnu.org/install/">instructions on the gcc web
|
|
site</a>. When you run <code>configure</code>, add the
|
|
option <code>--enable-languages=c,c++,go</code> (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 <code>configure</code> option <code>--with-arch=i586</code>
|
|
(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 <code>-m32</code> option, then use the <code>configure</code>
|
|
option <code>--with-arch-32=i586</code>.
|
|
</p>
|
|
|
|
<h3 id="Gold">Gold</h3>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
To build gold yourself, build the GNU binutils,
|
|
using <code>--enable-gold=default</code> when you run
|
|
the <code>configure</code> script. Before building, you must install
|
|
the flex and bison packages. A typical sequence would look like
|
|
this (you can replace <code>/opt/gold</code> with any directory to
|
|
which you have write access):
|
|
</p>
|
|
|
|
<pre>
|
|
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
|
|
</pre>
|
|
|
|
<p>
|
|
However you install gold, when you configure gccgo, use the
|
|
option <code>--with-ld=<var>GOLD_BINARY</var></code>.
|
|
</p>
|
|
|
|
<h3 id="Prerequisites">Prerequisites</h3>
|
|
|
|
<p>
|
|
A number of prerequisites are required to build GCC, as
|
|
described on
|
|
the <a href="https://gcc.gnu.org/install/prerequisites.html">gcc web
|
|
site</a>. It is important to install all the prerequisites before
|
|
running the gcc <code>configure</code> script.
|
|
The prerequisite libraries can be conveniently downloaded using the
|
|
script <code>contrib/download_prerequisites</code> in the GCC sources.
|
|
|
|
<h3 id="Build_commands">Build commands</h3>
|
|
|
|
<p>
|
|
Once all the prerequisites are installed, then a typical build and
|
|
install sequence would look like this (only use
|
|
the <code>--with-ld</code> option if you are using the gold linker as
|
|
described above):
|
|
</p>
|
|
|
|
<pre>
|
|
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
|
|
</pre>
|
|
|
|
<h2 id="Using_gccgo">Using gccgo</h2>
|
|
|
|
<p>
|
|
The gccgo compiler works like other gcc frontends. As of GCC 5 the gccgo
|
|
installation also includes a version of the <code>go</code> command,
|
|
which may be used to build Go programs as described at
|
|
<a href="https://golang.org/cmd/go">https://golang.org/cmd/go</a>.
|
|
</p>
|
|
|
|
<p>
|
|
To compile a file without using the <code>go</code> command:
|
|
</p>
|
|
|
|
<pre>
|
|
gccgo -c file.go
|
|
</pre>
|
|
|
|
<p>
|
|
That produces <code>file.o</code>. To link files together to form an
|
|
executable:
|
|
</p>
|
|
|
|
<pre>
|
|
gccgo -o file file.o
|
|
</pre>
|
|
|
|
<p>
|
|
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:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>
|
|
Set the <code>LD_LIBRARY_PATH</code> environment variable:
|
|
</p>
|
|
|
|
<pre>
|
|
LD_LIBRARY_PATH=${prefix}/lib/gcc/MACHINE/VERSION
|
|
[or]
|
|
LD_LIBRARY_PATH=${prefix}/lib64/gcc/MACHINE/VERSION
|
|
export LD_LIBRARY_PATH
|
|
</pre>
|
|
|
|
<p>
|
|
Here <code>${prefix}</code> is the <code>--prefix</code> option used
|
|
when building gccgo. For a binary install this is
|
|
normally <code>/usr</code>. Whether to use <code>lib</code>
|
|
or <code>lib64</code> depends on the target.
|
|
Typically <code>lib64</code> is correct for x86_64 systems,
|
|
and <code>lib</code> is correct for other systems. The idea is to
|
|
name the directory where <code>libgo.so</code> is found.
|
|
</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<p>
|
|
Passing a <code>-Wl,-R</code> option when you link (replace lib with
|
|
lib64 if appropriate for your system):
|
|
</p>
|
|
|
|
<pre>
|
|
go build -gccgoflags -Wl,-R,${prefix}/lib/gcc/MACHINE/VERSION
|
|
[or]
|
|
gccgo -o file file.o -Wl,-R,${prefix}/lib/gcc/MACHINE/VERSION
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
<p>
|
|
Use the <code>-static-libgo</code> option to link statically against
|
|
the compiled packages.
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>
|
|
Use the <code>-static</code> option to do a fully static link (the
|
|
default for the <code>gc</code> compiler).
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h2 id="Options">Options</h2>
|
|
|
|
<p>
|
|
The gccgo compiler supports all GCC options
|
|
that are language independent, notably the <code>-O</code>
|
|
and <code>-g</code> options.
|
|
</p>
|
|
|
|
<p>
|
|
The <code>-fgo-pkgpath=PKGPATH</code> 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 <code>PKGPATH</code> may be any string; a good choice for the
|
|
string is the path used to import the package.
|
|
</p>
|
|
|
|
<p>
|
|
The <code>-I</code> and <code>-L</code> 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.
|
|
</p>
|
|
|
|
<h2 id="Imports">Imports</h2>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
When you import the package <var>FILE</var> with gccgo,
|
|
it will look for the import data in the following files, and use the
|
|
first one that it finds.
|
|
|
|
<ul>
|
|
<li><code><var>FILE</var>.gox</code>
|
|
<li><code>lib<var>FILE</var>.so</code>
|
|
<li><code>lib<var>FILE</var>.a</code>
|
|
<li><code><var>FILE</var>.o</code>
|
|
</ul>
|
|
|
|
<p>
|
|
<code><var>FILE</var>.gox</code>, when used, will typically contain
|
|
nothing but export data. This can be generated from
|
|
<code><var>FILE</var>.o</code> via
|
|
</p>
|
|
|
|
<pre>
|
|
objcopy -j .go_export FILE.o FILE.gox
|
|
</pre>
|
|
|
|
<p>
|
|
The gccgo compiler will look in the current
|
|
directory for import files. In more complex scenarios you
|
|
may pass the <code>-I</code> or <code>-L</code> option to
|
|
gccgo. Both options take directories to search. The
|
|
<code>-L</code> option is also passed to the linker.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<pre>
|
|
gccgo -c mypackage.go # Exports mypackage
|
|
gccgo -c main.go # Imports mypackage
|
|
gccgo -o main main.o mypackage.o # Explicitly links with mypackage.o
|
|
</pre>
|
|
|
|
<h2 id="Debugging">Debugging</h2>
|
|
|
|
<p>
|
|
If you use the <code>-g</code> option when you compile, you can run
|
|
<code>gdb</code> 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.
|
|
</p>
|
|
|
|
<h2 id="C_Interoperability">C Interoperability</h2>
|
|
|
|
<p>
|
|
When using gccgo there is limited interoperability with C,
|
|
or with C++ code compiled using <code>extern "C"</code>.
|
|
</p>
|
|
|
|
<h3 id="Types">Types</h3>
|
|
|
|
<p>
|
|
Basic types map directly: an <code>int32</code> in Go is
|
|
an <code>int32_t</code> in C, an <code>int64</code> is
|
|
an <code>int64_t</code>, etc.
|
|
The Go type <code>int</code> is an integer that is the same size as a
|
|
pointer, and as such corresponds to the C type <code>intptr_t</code>.
|
|
Go <code>byte</code> is equivalent to C <code>unsigned char</code>.
|
|
Pointers in Go are pointers in C.
|
|
A Go <code>struct</code> is the same as C <code>struct</code> with the
|
|
same fields and types.
|
|
</p>
|
|
|
|
<p>
|
|
The Go <code>string</code> type is currently defined as a two-element
|
|
structure (this is <b style="color: red;">subject to change</b>):
|
|
</p>
|
|
|
|
<pre>
|
|
struct __go_string {
|
|
const unsigned char *__data;
|
|
intptr_t __length;
|
|
};
|
|
</pre>
|
|
|
|
<p>
|
|
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 <code>*[10]int</code> is equivalent to C <code>int*</code>,
|
|
assuming that the C pointer does point to 10 elements.
|
|
</p>
|
|
|
|
<p>
|
|
A slice in Go is a structure. The current definition is
|
|
(this is <b style="color: red;">subject to change</b>):
|
|
</p>
|
|
|
|
<pre>
|
|
struct __go_slice {
|
|
void *__values;
|
|
intptr_t __count;
|
|
intptr_t __capacity;
|
|
};
|
|
</pre>
|
|
|
|
<p>
|
|
The type of a Go function is a pointer to a struct (this is
|
|
<b style="color: red;">subject to change</b>). 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:
|
|
</p>
|
|
|
|
<pre>
|
|
func GoFunction(int) (int, float64)
|
|
struct { int i; float64 f; } CFunction(int, void*)
|
|
</pre>
|
|
|
|
<p>
|
|
Go <code>interface</code>, <code>channel</code>, and <code>map</code>
|
|
types have no corresponding C type (<code>interface</code> is a
|
|
two-element struct and <code>channel</code> and <code>map</code> are
|
|
pointers to structs in C, but the structs are deliberately undocumented). C
|
|
<code>enum</code> types correspond to some integer type, but precisely
|
|
which one is difficult to predict in general; use a cast. C <code>union</code>
|
|
types have no corresponding Go type. C <code>struct</code> types containing
|
|
bitfields have no corresponding Go type. C++ <code>class</code> types have
|
|
no corresponding Go type.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<h3 id="Function_names">Function names</h3>
|
|
|
|
<p>
|
|
Go code can call C functions directly using a Go extension implemented
|
|
in gccgo: a function declaration may be preceded by
|
|
<code>//extern NAME</code>. For example, here is how the C function
|
|
<code>open</code> can be declared in Go:
|
|
</p>
|
|
|
|
<pre>
|
|
//extern open
|
|
func c_open(name *byte, mode int, perm int) int
|
|
</pre>
|
|
|
|
<p>
|
|
The C function naturally expects a NUL-terminated string, which in
|
|
Go is equivalent to a pointer to an array (not a slice!) of
|
|
<code>byte</code> with a terminating zero byte. So a sample call
|
|
from Go would look like (after importing the <code>syscall</code> package):
|
|
</p>
|
|
|
|
<pre>
|
|
var name = [4]byte{'f', 'o', 'o', 0};
|
|
i := c_open(&name[0], syscall.O_RDONLY, 0);
|
|
</pre>
|
|
|
|
<p>
|
|
(this serves as an example only, to open a file in Go please use Go's
|
|
<code>os.Open</code> function instead).
|
|
</p>
|
|
|
|
<p>
|
|
Note that if the C function can block, such as in a call
|
|
to <code>read</code>, 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 <code>gc</code> compiler.
|
|
</p>
|
|
|
|
<p>
|
|
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
|
|
<code>prefix.package.Functionname</code>. The prefix is set by
|
|
the <code>-fgo-prefix</code> option used when the package is compiled;
|
|
if the option is not used, the default is <code>go</code>.
|
|
To call the function from C you must set the name using
|
|
a GCC extension.
|
|
</p>
|
|
|
|
<pre>
|
|
extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
|
|
</pre>
|
|
|
|
<h3 id="Automatic_generation_of_Go_declarations_from_C_source_code">
|
|
Automatic generation of Go declarations from C source code</h3>
|
|
|
|
<p>
|
|
The Go version of GCC supports automatically generating
|
|
Go declarations from C code. The facility is rather awkward, and most
|
|
users should use the <a href="/cmd/cgo">cgo</a> program with
|
|
the <code>-gccgo</code> option instead.
|
|
</p>
|
|
|
|
<p>
|
|
Compile your C code as usual, and add the option
|
|
<code>-fdump-go-spec=<var>FILENAME</var></code>. This will create the
|
|
file <code><var>FILENAME</var></code> 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 <code>package</code> declaration, but
|
|
can otherwise be compiled directly by gccgo.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|