diff options
Diffstat (limited to 'go/golang/go/doc/gccgo_install.html')
| -rw-r--r-- | go/golang/go/doc/gccgo_install.html | 534 |
1 files changed, 534 insertions, 0 deletions
diff --git a/go/golang/go/doc/gccgo_install.html b/go/golang/go/doc/gccgo_install.html new file mode 100644 index 00000000..a974bb36 --- /dev/null +++ b/go/golang/go/doc/gccgo_install.html @@ -0,0 +1,534 @@ +<!--{ + "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="https://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="https://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> + +<p> +The GCC 6 releases include a complete implementation of the Go 1.6.1 +user libraries. The Go 1.6 runtime is not fully merged, but that +should not be visible to Go programs. +</p> + +<p> +The GCC 7 releases include a complete implementation of the Go 1.8.1 +user libraries. As with earlier releases, the Go 1.8 runtime is not +fully merged, but that should not be visible to Go programs. +</p> + +<p> +The GCC 8 releases are expected to include a complete implementation +of the Go 1.10 release, depending on release timing. The Go 1.10 +runtime has now been fully merged into the GCC development sources, +and concurrent garbage collection is expected to be fully supported in +GCC 8. +</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="https://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="https://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="https://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> + +<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>int32</code> in Go is +an <code>int32_t</code> in C, an <code>int64</code> is +an <code>int64_t</code>, etc. +The Go type <code>int</code> is an integer that is the same size as a +pointer, and as such corresponds to the C type <code>intptr_t</code>. +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; + intptr_t __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; + intptr_t __count; + intptr_t __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> |