2009-10-14 16:49:20 -06:00
|
|
|
<!-- Setting up and using gccgo -->
|
|
|
|
|
|
|
|
<p>
|
|
|
|
This document explains how to use <code>gccgo</code>, a compiler for
|
|
|
|
the Go language. The <code>gccgo</code> compiler is a new frontend
|
2009-11-08 00:42:58 -07:00
|
|
|
for <code>gcc</code>, the widely used GNU compiler. Although the
|
|
|
|
frontend itself is under a BSD-style license, <code>gccgo</code> is
|
|
|
|
normally used as part of <code>gcc</code> and is then covered by
|
2009-10-14 16:49:20 -06:00
|
|
|
the <a href="http://www.gnu.org/licenses/gpl.html">GNU General Public
|
|
|
|
License</a>.
|
2009-11-06 15:16:47 -07:00
|
|
|
</p>
|
2009-10-14 16:49:20 -06:00
|
|
|
|
2009-11-06 15:16:47 -07:00
|
|
|
<p>
|
2009-10-14 16:49:20 -06:00
|
|
|
Note that <code>gccgo</code> is not the <code>6g</code> compiler; see
|
2009-11-06 15:16:47 -07:00
|
|
|
the <a href="install.html">Installing Go</a> instructions for that
|
|
|
|
compiler.
|
|
|
|
</p>
|
2009-10-14 16:49:20 -06:00
|
|
|
|
|
|
|
<h2 id="Source_code">Source code</h2>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
The <code>gccgo</code> source code is accessible via Subversion. The
|
|
|
|
<code>gcc</code> web site
|
|
|
|
has <a href="http://gcc.gnu.org/svn.html">instructions for getting the
|
|
|
|
<code>gcc</code> source code</a>. The <code>gccgo</code> source code
|
|
|
|
is a branch of the main <code>gcc</code> code
|
|
|
|
repository: <code>svn://gcc.gnu.org/svn/gcc/branches/gccgo</code>.
|
2009-11-06 15:16:47 -07:00
|
|
|
</p>
|
2009-10-14 16:49:20 -06:00
|
|
|
|
2010-01-29 17:37:20 -07:00
|
|
|
<p>
|
|
|
|
Note that although <code>gcc.gnu.org</code> is the most convenient way
|
|
|
|
to get the source code for the compiler, that is not where the master
|
|
|
|
sources live. If you want to contribute changes to the gccgo
|
|
|
|
compiler, see <a href="gccgo_contribute.html">Contributing to
|
|
|
|
gccgo</a>.
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
2009-10-14 16:49:20 -06:00
|
|
|
<h2 id="Building">Building</h2>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Building <code>gccgo</code> is just like building <code>gcc</code>
|
2009-11-18 13:48:48 -07:00
|
|
|
with one or two additional options. See
|
2009-10-14 16:49:20 -06:00
|
|
|
the <a href="http://gcc.gnu.org/install/">instructions on the gcc web
|
|
|
|
site</a>. When you run <code>configure</code>, add the
|
2009-11-18 13:48:48 -07:00
|
|
|
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 <code>gccgo</code> 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).
|
2009-11-06 15:16:47 -07:00
|
|
|
</p>
|
|
|
|
|
2009-12-29 15:59:08 -07:00
|
|
|
<p>
|
|
|
|
On x86 GNU/Linux systems the <code>gccgo</code> 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 development version of
|
|
|
|
the <code>gold</code> linker. The easiest way to do this is to build
|
|
|
|
the GNU binutils, using <code>--enable-gold</code> when you run
|
|
|
|
the <code>configure</code> script, and to
|
|
|
|
use <code>--with-ld=GOLD_BINARY</code> when you
|
|
|
|
configure <code>gccgo</code>. 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"]
|
|
|
|
cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils
|
|
|
|
mkdir binutils-objdir
|
|
|
|
cd binutils-objdir
|
|
|
|
../src/configure --enable-gold --prefix=/opt/gold
|
|
|
|
make
|
|
|
|
make install
|
|
|
|
</pre>
|
|
|
|
|
2009-11-06 15:16:47 -07:00
|
|
|
<p>
|
|
|
|
A number of prerequisites are required to build <code>gcc</code>, as
|
2009-12-29 15:59:08 -07:00
|
|
|
described on the <a href="http://gcc.gnu.org/">gcc web site</a>. If
|
|
|
|
those are all available, then a typical build and install sequence
|
|
|
|
would look like this (only use the <code>--with-ld</code> option if
|
|
|
|
you built and installed the gold linker as described above):
|
|
|
|
</p>
|
2009-11-06 15:16:47 -07:00
|
|
|
|
|
|
|
<pre>
|
|
|
|
svn checkout svn://gcc.gnu.org/svn/gcc/branches/gccgo gccgo
|
|
|
|
mkdir objdir
|
|
|
|
cd objdir
|
2009-12-29 15:59:08 -07:00
|
|
|
../gccgo/configure --enable-languages=c,c++,go --with-ld=/opt/gold/bin/ld
|
2009-11-06 15:16:47 -07:00
|
|
|
make
|
|
|
|
make install
|
|
|
|
</pre>
|
2009-10-14 16:49:20 -06:00
|
|
|
|
|
|
|
<h2 id="Using_gccgo">Using gccgo</h2>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
The <code>gccgo</code> compiler works like other gcc frontends.
|
|
|
|
|
|
|
|
<p>
|
|
|
|
To compile a file:
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
gccgo -c file.go
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
That produces <code>file.o</code>. To link files together to form an
|
|
|
|
executable:
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
gccgo -o file file.o
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
To run the resulting file, you will need to tell the program where to
|
2011-03-01 14:54:22 -07:00
|
|
|
find the compiled Go packages. This can be done either by setting
|
2009-10-14 16:49:20 -06:00
|
|
|
<code>LD_LIBRARY_PATH</code> in your environment:
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
LD_LIBRARY_PATH=/usr/lib/gcc/MACHINE/VERSION
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
or by passing a <code>-Wl,-R</code> option when you link:
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
gccgo -o file file.o -Wl,-R,/usr/lib/gcc/MACHINE/VERSION
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
or you can use the <code>-static-libgo</code> link-time option to link
|
|
|
|
statically against libgo, or you can do a fully static link (static
|
|
|
|
linking is the default for the <code>6l</code> Go linker). On most
|
|
|
|
systems, a static link will look something like:
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
gccgo -o file file.o -static -L /usr/lib/nptl -lgobegin -lgo -lpthread
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
You may get a warning about not creating an <code>.eh_frame_hdr</code>
|
|
|
|
section; this has nothing to do with Go, and may be ignored. In the
|
|
|
|
future the requirement of explicitly specifying
|
|
|
|
<code>-L /usr/lib/nptl -lgobegin -lgo -lpthread</code>
|
|
|
|
may be removed.
|
|
|
|
|
|
|
|
|
2010-01-29 17:37:20 -07:00
|
|
|
<h2 id="Options">Options</h2>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
The <code>gccgo</code> compiler supports all <code>gcc</code> options
|
|
|
|
that are language independent, notably the <code>-O</code>
|
|
|
|
and <code>-g</code> options.
|
|
|
|
|
|
|
|
<p>
|
|
|
|
The <code>-fgo-prefix=PREFIX</code> option may be used to set a unique
|
|
|
|
prefix for the package being compiled. 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>PREFIX</code> may be any string; a good choice for the
|
|
|
|
string is the directory where the package will be installed.
|
|
|
|
|
|
|
|
<p>
|
|
|
|
The <code>-fno-require-return-statement</code> option may be used to
|
|
|
|
disable the compiler error about functions missing return statements.
|
|
|
|
Note that there is no way to disable this error in <code>6g</code>.
|
|
|
|
|
|
|
|
<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.
|
|
|
|
|
|
|
|
|
2009-10-14 16:49:20 -06:00
|
|
|
<h2 id="Imports">Imports</h2>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
When you compile a file which exports something, the export
|
|
|
|
information will be stored directly in the object file. When
|
|
|
|
you import a package, you must tell <code>gccgo</code> how to
|
|
|
|
find the file.
|
|
|
|
|
|
|
|
<p>
|
|
|
|
When you import the package <var>FILE</var> with <code>gccgo</code>,
|
|
|
|
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><var>FILE</var>.o</code>
|
|
|
|
<li><code>lib<var>FILE</var>.so</code>
|
|
|
|
<li><code>lib<var>FILE</var>.a</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
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
objcopy -j .go_export FILE.o FILE.gox
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
The <code>gccgo</code> 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
|
|
|
|
<code>gccgo</code>. Both options take directories to search. The
|
|
|
|
<code>-L</code> option is also passed to the linker.
|
|
|
|
|
2009-11-06 15:16:47 -07:00
|
|
|
The <code>gccgo</code> compiler does not currently (2009-11-06) record
|
2009-10-14 16:49:20 -06:00
|
|
|
the file name of imported packages in the object file. You must
|
|
|
|
arrange for the imported data to be linked into the program.
|
|
|
|
|
|
|
|
<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="Unimplemented">Unimplemented</h2>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Some Go features are not yet implemented in <code>gccgo</code>. As of
|
2010-08-23 18:50:30 -06:00
|
|
|
2010-08-23, the following are not implemented:
|
2009-10-14 16:49:20 -06:00
|
|
|
|
|
|
|
<ul>
|
2010-01-29 17:37:20 -07:00
|
|
|
<li>goroutines are implemented as NPTL threads. If you can not use
|
|
|
|
the gold linker as described above, they are created with a fixed
|
|
|
|
stack size, and the number of goroutines that may be created at
|
|
|
|
one time is limited.
|
2009-10-14 16:49:20 -06:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
<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 doesn't (yet)
|
|
|
|
know anything about Go. However, 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
|
|
|
|
will show up as pointers to structures; to see the value
|
|
|
|
<code>print *stringvar</code>. In general Go strings, maps, channels
|
|
|
|
and interfaces are always represented as C pointers.
|
|
|
|
|
|
|
|
<h2 id="C_Interoperability">C Interoperability</h2>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
When using <code>gccgo</code> there is limited interoperability with C,
|
|
|
|
or with C++ code compiled using <code>extern "C"</code>.
|
|
|
|
|
|
|
|
<h3 id="Types">Types</h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Basic types map directly: an <code>int</code> in Go is an <code>int</code>
|
|
|
|
in C, etc. 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>
|
2010-08-23 18:50:30 -06:00
|
|
|
The Go <code>string</code> type is currently defined as a two-element
|
|
|
|
structure (this is <b style="color: red;">subject to change</b>):
|
2009-10-14 16:49:20 -06:00
|
|
|
|
|
|
|
<pre>
|
|
|
|
struct __go_string {
|
2010-08-23 18:50:30 -06:00
|
|
|
const unsigned char *__data;
|
|
|
|
int __length;
|
2009-10-14 16:49:20 -06:00
|
|
|
};
|
|
|
|
</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>
|
|
|
|
A slice in Go is a structure. The current definition is
|
|
|
|
(this is <b style="color: red;">subject to change</b>):
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
struct __go_slice {
|
|
|
|
void *__values;
|
|
|
|
int __count;
|
|
|
|
int __capacity;
|
|
|
|
};
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
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:
|
|
|
|
|
|
|
|
<pre>
|
2011-01-19 21:07:38 -07:00
|
|
|
func GoFunction(int) (int, float64)
|
|
|
|
struct { int i; float64 f; } CFunction(int)
|
2009-10-14 16:49:20 -06:00
|
|
|
</pre>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
A pointer to a Go function is equivalent to a pointer to a C function
|
|
|
|
when the functions have equivalent types.
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Go <code>interface</code>, <code>channel</code>, and <code>map</code>
|
2010-08-23 18:50:30 -06:00
|
|
|
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
|
2009-10-14 16:49:20 -06:00
|
|
|
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>
|
|
|
|
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.
|
|
|
|
|
|
|
|
<h3 id="Function_names">Function names</h3>
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Go code can call C functions directly using a Go extension implemented
|
|
|
|
in <code>gccgo</code>: a function declaration may be followed by
|
|
|
|
<code>__asm__("NAME")</code>. For example, here is how the C function
|
|
|
|
<code>open</code> can be declared in Go:
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
func c_open(name *byte, mode int, perm int) int __asm__ ("open");
|
|
|
|
</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>os</code> package):
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
var name = [4]byte{'f', 'o', 'o', 0};
|
|
|
|
i := c_open(&name[0], os.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>
|
|
|
|
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
|
2010-08-23 18:50:30 -06:00
|
|
|
<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 simply <code>go</code>.
|
|
|
|
To call the function from C you must set the name using
|
|
|
|
a <code>gcc</code> extension similar to the <code>gccgo</code>
|
2009-10-14 16:49:20 -06:00
|
|
|
extension.
|
|
|
|
|
|
|
|
<pre>
|
2010-08-23 18:50:30 -06:00
|
|
|
extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
|
2009-10-14 16:49:20 -06:00
|
|
|
</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 <code>gcc</code> supports automatically generating
|
|
|
|
Go declarations from C code. The facility is rather awkward at present,
|
|
|
|
and a better mechanism is under development.
|
|
|
|
|
|
|
|
<p>
|
|
|
|
Compile your C code as usual, but replace <code>-c</code> with
|
|
|
|
<code>-S -ggo</code>. The result will be an assembler file
|
|
|
|
with a <code>.s</code> extension. This assembler file will contain
|
|
|
|
comments beginning with #GO. Those comments are declarations in the Go
|
|
|
|
language for the C types, variables and functions declared in the C code.
|
|
|
|
C types which can not be represented in Go will contain the string INVALID.
|
|
|
|
Unsupported macro definitions will be recorded as <code>unknowndefine</code>,
|
|
|
|
and uses of <code>#undef</code> will be recorded as <code>undef</code>.
|
|
|
|
So it is very approximately possible to get Go code by running
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
gcc -S -ggo foo.c
|
|
|
|
grep '#GO' foo.s | grep -v INVALID | grep -v unknowndefine | grep -v undef > foo.go
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
<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.
|
2010-07-20 01:06:20 -06:00
|
|
|
|
2010-08-29 17:58:27 -06:00
|
|
|
<h2 id="RTEMS_Port">RTEMS Port</h2>
|
2010-07-20 01:06:20 -06:00
|
|
|
<p>
|
2010-08-29 17:58:27 -06:00
|
|
|
The <code>gccgo</code> compiler has been ported to <a href="http://www.rtems.com/">
|
2010-07-20 01:06:20 -06:00
|
|
|
<code>RTEMS</code></a>. <code>RTEMS</code> is a real-time executive
|
|
|
|
that provides a high performance environment for embedded applications
|
|
|
|
on a range of processors and embedded hardware. The current <code>gccgo</code>
|
|
|
|
port is for x86. The goal is to extend the port to most of the
|
|
|
|
<a href="http://www.rtems.org/wiki/index.php/SupportedCPUs">
|
|
|
|
architectures supported by <code>RTEMS</code></a>. For more information on the port,
|
|
|
|
as well as instructions on how to install it, please see this
|
|
|
|
<a href="http://www.rtems.com/wiki/index.php/GCCGoRTEMS"><code>RTEMS</code> Wiki page</a>.
|