| <!--{ |
| "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="http://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="http://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> |
| |
| <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="http://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="http://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="http://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> |
| |
| <h3 id="Ubuntu">A note on Ubuntu</h3> |
| |
| <p> |
| Current versions of Ubuntu and versions of GCC before 4.8 disagree on |
| where system libraries and header files are found. This is not a |
| gccgo issue. When building older versions of GCC, setting these |
| environment variables while configuring and building gccgo may fix the |
| problem. |
| </p> |
| |
| <pre> |
| LIBRARY_PATH=/usr/lib/x86_64-linux-gnu |
| C_INCLUDE_PATH=/usr/include/x86_64-linux-gnu |
| CPLUS_INCLUDE_PATH=/usr/include/x86_64-linux-gnu |
| export LIBRARY_PATH C_INCLUDE_PATH CPLUS_INCLUDE_PATH |
| </pre> |
| |
| <h2 id="Using_gccgo">Using gccgo</h2> |
| |
| <p> |
| The gccgo compiler works like other gcc frontends. The gccgo |
| installation does not currently include a version of |
| the <code>go</code> command. However if you have the <code>go</code> |
| command from an installation of the <code>gc</code> compiler, you can |
| use it with gccgo by passing the option <code>-compiler gccgo</code> |
| to <code>go build</code> or <code>go install</code> or <code>go |
| test</code>. |
| </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: |
| </p> |
| |
| <pre> |
| gccgo -o file file.o -Wl,-R,${prefix}/lib/gcc/MACHINE/VERSION |
| [or] |
| gccgo -o file file.o -Wl,-R,${prefix}/lib64/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-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> |
| |
| <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. |
| </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. When |
| you import a package, you must tell gccgo how to |
| find the file. |
| |
| <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 (2013-06-20) record |
| the file name of imported packages in the object file. You must |
| arrange for the imported data to be linked into the program. |
| </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>int</code> in Go is an <code>int</code> |
| in C, an <code>int32</code> is an <code>int32_t</code>, |
| 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> |
| |
| <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; |
| int __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; |
| int __count; |
| int __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> |
| |
| <h2 id="RTEMS_Port">RTEMS Port</h2> |
| <p> |
| The gccgo compiler has been ported to <a href="http://www.rtems.com/"> |
| <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 gccgo |
| 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>. |