diff options
Diffstat (limited to 'doc/gccgo_install.html')
-rw-r--r-- | doc/gccgo_install.html | 327 |
1 files changed, 213 insertions, 114 deletions
diff --git a/doc/gccgo_install.html b/doc/gccgo_install.html index e769c2211..a8d7396e5 100644 --- a/doc/gccgo_install.html +++ b/doc/gccgo_install.html @@ -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 <code>gccgo</code> compiler is able to +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 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 +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> @@ -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> -<pre> -gccgo -o file file.o -Wl,-R,/usr/lib/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: +Passing a <code>-Wl,-R</code> option when you link: +</p> <pre> -gccgo -o file file.o -static -L /usr/lib/nptl -lgobegin -lgo -lpthread +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> -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-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 <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(&name[0], os.O_RDONLY, 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> 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 -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, |