doc/gccgo_install.html - go - Git at Google

 <!--{
 	"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>

 <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>

 <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.  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>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(&amp;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.org/wiki/index.php/GCCGoRTEMS"><code>RTEMS</code> Wiki page</a>.
	<!--{
	"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>

	<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>

	<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. 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>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.org/wiki/index.php/GCCGoRTEMS"><code>RTEMS</code> Wiki page</a>.