languages/go
languages/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-09-04 23:44:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: general update of gccgo_install

Browse source 
Fixes #3325.

R=golang-dev, bradfitz, minux.ma, r
CC=golang-dev
https://golang.org/cl/5858043
This commit is contained in:
Ian Lance Taylor 2012-03-20 14:16:34 -07:00
parent 65dc7dc90b
commit a84e3baf9a
1 changed files with 217 additions and 118 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

335
doc/gccgo_install.html
View file

@ -4,36 +4,59 @@
}-->
<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
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
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>.
License</a> (the license covers gccgo itself as part of GCC; it
does not cover code generated by gccgo).
</p>
<p>
Note that <code>gccgo</code> is not the <code>6g</code> compiler; see
the <a href="/doc/install">Installing Go</a> instructions for that
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.0 release includes Go support that is very close to
<a href="/doc/go1.html">Go 1</a>. Due to release timing it will not
include the last few changes to the Go 1 libraries. The GCC 4.7.1
release should include a complete Go 1 compiler and libraries.
</p>
<h2 id="Source_code">Source code</h2>
<p>
The <code>gccgo</code> source code is accessible via Subversion. The
<code>gcc</code> web site
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
<code>gcc</code> source code</a>. The <code>gccgo</code> source code
is a branch of the main <code>gcc</code> code
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 compiler, that is not where the master
sources live. If you want to contribute changes to the gccgo
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>
@ -42,29 +65,37 @@ gccgo</a>.
<h2 id="Building">Building</h2>
<p>
Building <code>gccgo</code> is just like building <code>gcc</code>
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 <code>gccgo</code> to default to
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).
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>
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=default</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
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>
@ -72,6 +103,7 @@ which you have write access):
<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
@ -81,29 +113,69 @@ make install
</pre>
<p>
A number of prerequisites are required to build <code>gcc</code>, as
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):
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.
<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 --enable-languages=c,c++,go --with-ld=/opt/gold/bin/ld
../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 current versions of gcc disagree on
where system libraries and header files are found. This is not a
gccgo issue, and we hope this will be resolved soon. Until it is,
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 <code>gccgo</code> compiler works like other gcc frontends.
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:
To compile a file without using the <code>go</code> command:
</p>
<pre>
gccgo -c file.go
@ -112,6 +184,7 @@ gccgo -c file.go
<p>
That produces <code>file.o</code>. To link files together to form an
executable:
</p>
<pre>
gccgo -o file file.o
@ -119,44 +192,68 @@ gccgo -o file file.o
<p>
To run the resulting file, you will need to tell the program where to
find the compiled Go packages. This can be done either by setting
<code>LD_LIBRARY_PATH</code> in your environment:
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=/usr/lib/gcc/MACHINE/VERSION
LD_LIBRARY_PATH=${prefix}/lib/gcc/MACHINE/VERSION
[or]
LD_LIBRARY_PATH=${prefix}/lib64/gcc/MACHINE/VERSION
export LD_LIBRARY_PATH
</pre>
<p>
or by passing a <code>-Wl,-R</code> option when you link:
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,/usr/lib/gcc/MACHINE/VERSION
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>
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>
Use the <code>-static-libgo</code> option to link statically against
the compiled packages.
</p>
</li>
<li>
<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.
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 <code>gccgo</code> compiler supports all <code>gcc</code> options
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
@ -165,28 +262,24 @@ 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>
<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 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
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 <code>gccgo</code>,
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.
@ -201,21 +294,25 @@ first one that it finds.
<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 <code>gccgo</code> compiler will look in the current
directory for import files. In more complex scenarios you
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
<code>gccgo</code>. Both options take directories to search. The
gccgo. Both options take directories to search. The
<code>-L</code> option is also passed to the linker.
</p>
The <code>gccgo</code> compiler does not currently (2009-11-06) record
<p>
The gccgo compiler does not currently (2012-03-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
@ -223,48 +320,41 @@ 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, the following are not implemented:
<ul>
<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.
</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,
<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
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.
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 <code>gccgo</code> there is limited interoperability with C,
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, etc. Go <code>byte</code> is equivalent to C <code>unsigned char</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 {
@ -279,10 +369,12 @@ 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 {
@ -294,9 +386,10 @@ struct __go_slice {
<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
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:
</p>
<pre>
func GoFunction(int) (int, float64)
@ -305,7 +398,9 @@ struct { int i; float64 f; } CFunction(int)
<p>
A pointer to a Go function is equivalent to a pointer to a C function
when the functions have equivalent types.
when the functions have equivalent types (this is
<b style="color: red;">subject to change</b>).
</p>
<p>
Go <code>interface</code>, <code>channel</code>, and <code>map</code>
@ -317,6 +412,7 @@ 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
@ -328,33 +424,38 @@ 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 <code>gccgo</code>: a function declaration may be followed by
<code>__asm__("NAME")</code>. For example, here is how the C function
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>
func c_open(name *byte, mode int, perm int) int __asm__ ("open");
//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>os</code> package):
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], os.O_RDONLY, 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>
The name of Go functions accessed from C is subject to change. At present
@ -363,8 +464,8 @@ the name of a Go function that does not have a receiver is
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 <code>gcc</code> extension similar to the <code>gccgo</code>
extension.
a GCC extension.
</p>
<pre>
extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
@ -374,37 +475,35 @@ extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
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.
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, but replace <code>-c</code> with
<code>-S&nbsp;-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>
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 <code>gccgo</code> compiler has been ported to <a href="http://www.rtems.com/">
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 <code>gccgo</code>
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,