"Fossies" - the Fresh Open Source Software Archive

Member "go/doc/gccgo_install.html" (9 Sep 2020, 17028 Bytes) of package /windows/misc/go1.14.9.windows-386.zip:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <!--{
    2     "Title": "Setting up and using gccgo",
    3     "Path": "/doc/install/gccgo"
    4 }-->
    6 <p>
    7 This document explains how to use gccgo, a compiler for
    8 the Go language. The gccgo compiler is a new frontend
    9 for GCC, the widely used GNU compiler. Although the
   10 frontend itself is under a BSD-style license, gccgo is
   11 normally used as part of GCC and is then covered by
   12 the <a href="https://www.gnu.org/licenses/gpl.html">GNU General Public
   13 License</a> (the license covers gccgo itself as part of GCC; it
   14 does not cover code generated by gccgo).
   15 </p>
   17 <p>
   18 Note that gccgo is not the <code>gc</code> compiler; see
   19 the <a href="/doc/install.html">Installing Go</a> instructions for that
   20 compiler.
   21 </p>
   23 <h2 id="Releases">Releases</h2>
   25 <p>
   26 The simplest way to install gccgo is to install a GCC binary release
   27 built to include Go support. GCC binary releases are available from
   28 <a href="https://gcc.gnu.org/install/binaries.html">various
   29 websites</a> and are typically included as part of GNU/Linux
   30 distributions. We expect that most people who build these binaries
   31 will include Go support.
   32 </p>
   34 <p>
   35 The GCC 4.7.1 release and all later 4.7 releases include a complete
   36 <a href="/doc/go1.html">Go 1</a> compiler and libraries.
   37 </p>
   39 <p>
   40 Due to timing, the GCC 4.8.0 and 4.8.1 releases are close to but not
   41 identical to Go 1.1. The GCC 4.8.2 release includes a complete Go
   42 1.1.2 implementation.
   43 </p>
   45 <p>
   46 The GCC 4.9 releases include a complete Go 1.2 implementation.
   47 </p>
   49 <p>
   50 The GCC 5 releases include a complete implementation of the Go 1.4
   51 user libraries. The Go 1.4 runtime is not fully merged, but that
   52 should not be visible to Go programs.
   53 </p>
   55 <p>
   56 The GCC 6 releases include a complete implementation of the Go 1.6.1
   57 user libraries. The Go 1.6 runtime is not fully merged, but that
   58 should not be visible to Go programs.
   59 </p>
   61 <p>
   62 The GCC 7 releases include a complete implementation of the Go 1.8.1
   63 user libraries. As with earlier releases, the Go 1.8 runtime is not
   64 fully merged, but that should not be visible to Go programs.
   65 </p>
   67 <p>
   68 The GCC 8 releases include a complete implementation of the Go 1.10.1
   69 release. The Go 1.10 runtime has now been fully merged into the GCC
   70 development sources, and concurrent garbage collection is fully
   71 supported.
   72 </p>
   74 <p>
   75 The GCC 9 releases include a complete implementation of the Go 1.12.2
   76 release.
   77 </p>
   79 <h2 id="Source_code">Source code</h2>
   81 <p>
   82 If you cannot use a release, or prefer to build gccgo for
   83 yourself,
   84 the gccgo source code is accessible via Subversion. The
   85 GCC web site
   86 has <a href="https://gcc.gnu.org/svn.html">instructions for getting the
   87 GCC source code</a>. The gccgo source code is included. As a
   88 convenience, a stable version of the Go support is available in
   89 a branch of the main GCC code
   90 repository: <code>svn://gcc.gnu.org/svn/gcc/branches/gccgo</code>.
   91 This branch is periodically updated with stable Go compiler sources.
   92 </p>
   94 <p>
   95 Note that although <code>gcc.gnu.org</code> is the most convenient way
   96 to get the source code for the Go frontend, it is not where the master
   97 sources live. If you want to contribute changes to the Go frontend
   98 compiler, see <a href="/doc/gccgo_contribute.html">Contributing to
   99 gccgo</a>.
  100 </p>
  103 <h2 id="Building">Building</h2>
  105 <p>
  106 Building gccgo is just like building GCC
  107 with one or two additional options. See
  108 the <a href="https://gcc.gnu.org/install/">instructions on the gcc web
  109 site</a>. When you run <code>configure</code>, add the
  110 option <code>--enable-languages=c,c++,go</code> (along with other
  111 languages you may want to build). If you are targeting a 32-bit x86,
  112 then you will want to build gccgo to default to
  113 supporting locked compare and exchange instructions; do this by also
  114 using the <code>configure</code> option <code>--with-arch=i586</code>
  115 (or a newer architecture, depending on where you need your programs to
  116 run). If you are targeting a 64-bit x86, but sometimes want to use
  117 the <code>-m32</code> option, then use the <code>configure</code>
  118 option <code>--with-arch-32=i586</code>.
  119 </p>
  121 <h3 id="Gold">Gold</h3>
  123 <p>
  124 On x86 GNU/Linux systems the gccgo compiler is able to
  125 use a small discontiguous stack for goroutines. This permits programs
  126 to run many more goroutines, since each goroutine can use a relatively
  127 small stack. Doing this requires using the gold linker version 2.22
  128 or later. You can either install GNU binutils 2.22 or later, or you
  129 can build gold yourself.
  130 </p>
  132 <p>
  133 To build gold yourself, build the GNU binutils,
  134 using <code>--enable-gold=default</code> when you run
  135 the <code>configure</code> script. Before building, you must install
  136 the flex and bison packages. A typical sequence would look like
  137 this (you can replace <code>/opt/gold</code> with any directory to
  138 which you have write access):
  139 </p>
  141 <pre>
  142 cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
  143 [password is "anoncvs"]
  144 [The next command will create a directory named src, not binutils]
  145 cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils
  146 mkdir binutils-objdir
  147 cd binutils-objdir
  148 ../src/configure --enable-gold=default --prefix=/opt/gold
  149 make
  150 make install
  151 </pre>
  153 <p>
  154 However you install gold, when you configure gccgo, use the
  155 option <code>--with-ld=<var>GOLD_BINARY</var></code>.
  156 </p>
  158 <h3 id="Prerequisites">Prerequisites</h3>
  160 <p>
  161 A number of prerequisites are required to build GCC, as
  162 described on
  163 the <a href="https://gcc.gnu.org/install/prerequisites.html">gcc web
  164 site</a>. It is important to install all the prerequisites before
  165 running the gcc <code>configure</code> script.
  166 The prerequisite libraries can be conveniently downloaded using the
  167 script <code>contrib/download_prerequisites</code> in the GCC sources.
  169 <h3 id="Build_commands">Build commands</h3>
  171 <p>
  172 Once all the prerequisites are installed, then a typical build and
  173 install sequence would look like this (only use
  174 the <code>--with-ld</code> option if you are using the gold linker as
  175 described above):
  176 </p>
  178 <pre>
  179 svn checkout svn://gcc.gnu.org/svn/gcc/branches/gccgo gccgo
  180 mkdir objdir
  181 cd objdir
  182 ../gccgo/configure --prefix=/opt/gccgo --enable-languages=c,c++,go --with-ld=/opt/gold/bin/ld
  183 make
  184 make install
  185 </pre>
  187 <h2 id="Using_gccgo">Using gccgo</h2>
  189 <p>
  190 The gccgo compiler works like other gcc frontends. As of GCC 5 the gccgo
  191 installation also includes a version of the <code>go</code> command,
  192 which may be used to build Go programs as described at
  193 <a href="https://golang.org/cmd/go">https://golang.org/cmd/go</a>.
  194 </p>
  196 <p>
  197 To compile a file without using the <code>go</code> command:
  198 </p>
  200 <pre>
  201 gccgo -c file.go
  202 </pre>
  204 <p>
  205 That produces <code>file.o</code>. To link files together to form an
  206 executable:
  207 </p>
  209 <pre>
  210 gccgo -o file file.o
  211 </pre>
  213 <p>
  214 To run the resulting file, you will need to tell the program where to
  215 find the compiled Go packages. There are a few ways to do this:
  216 </p>
  218 <ul>
  219 <li>
  220 <p>
  221 Set the <code>LD_LIBRARY_PATH</code> environment variable:
  222 </p>
  224 <pre>
  225 LD_LIBRARY_PATH=${prefix}/lib/gcc/MACHINE/VERSION
  226 [or]
  227 LD_LIBRARY_PATH=${prefix}/lib64/gcc/MACHINE/VERSION
  228 export LD_LIBRARY_PATH
  229 </pre>
  231 <p>
  232 Here <code>${prefix}</code> is the <code>--prefix</code> option used
  233 when building gccgo. For a binary install this is
  234 normally <code>/usr</code>. Whether to use <code>lib</code>
  235 or <code>lib64</code> depends on the target.
  236 Typically <code>lib64</code> is correct for x86_64 systems,
  237 and <code>lib</code> is correct for other systems. The idea is to
  238 name the directory where <code>libgo.so</code> is found.
  239 </p>
  241 </li>
  243 <li>
  244 <p>
  245 Passing a <code>-Wl,-R</code> option when you link (replace lib with
  246 lib64 if appropriate for your system):
  247 </p>
  249 <pre>
  250 go build -gccgoflags -Wl,-R,${prefix}/lib/gcc/MACHINE/VERSION
  251 [or]
  252 gccgo -o file file.o -Wl,-R,${prefix}/lib/gcc/MACHINE/VERSION
  253 </pre>
  254 </li>
  256 <li>
  257 <p>
  258 Use the <code>-static-libgo</code> option to link statically against
  259 the compiled packages.
  260 </p>
  261 </li>
  263 <li>
  264 <p>
  265 Use the <code>-static</code> option to do a fully static link (the
  266 default for the <code>gc</code> compiler).
  267 </p>
  268 </li>
  269 </ul>
  271 <h2 id="Options">Options</h2>
  273 <p>
  274 The gccgo compiler supports all GCC options
  275 that are language independent, notably the <code>-O</code>
  276 and <code>-g</code> options.
  277 </p>
  279 <p>
  280 The <code>-fgo-pkgpath=PKGPATH</code> option may be used to set a
  281 unique prefix for the package being compiled.
  282 This option is automatically used by the go command, but you may want
  283 to use it if you invoke gccgo directly.
  284 This option is intended for use with large
  285 programs that contain many packages, in order to allow multiple
  286 packages to use the same identifier as the package name.
  287 The <code>PKGPATH</code> may be any string; a good choice for the
  288 string is the path used to import the package.
  289 </p>
  291 <p>
  292 The <code>-I</code> and <code>-L</code> options, which are synonyms
  293 for the compiler, may be used to set the search path for finding
  294 imports.
  295 These options are not needed if you build with the go command.
  296 </p>
  298 <h2 id="Imports">Imports</h2>
  300 <p>
  301 When you compile a file that exports something, the export
  302 information will be stored directly in the object file.
  303 If you build with gccgo directly, rather than with the go command,
  304 then when you import a package, you must tell gccgo how to find the
  305 file.
  306 </p>
  308 <p>
  309 When you import the package <var>FILE</var> with gccgo,
  310 it will look for the import data in the following files, and use the
  311 first one that it finds.
  313 <ul>
  314 <li><code><var>FILE</var>.gox</code>
  315 <li><code>lib<var>FILE</var>.so</code>
  316 <li><code>lib<var>FILE</var>.a</code>
  317 <li><code><var>FILE</var>.o</code>
  318 </ul>
  320 <p>
  321 <code><var>FILE</var>.gox</code>, when used, will typically contain
  322 nothing but export data. This can be generated from
  323 <code><var>FILE</var>.o</code> via
  324 </p>
  326 <pre>
  327 objcopy -j .go_export FILE.o FILE.gox
  328 </pre>
  330 <p>
  331 The gccgo compiler will look in the current
  332 directory for import files. In more complex scenarios you
  333 may pass the <code>-I</code> or <code>-L</code> option to
  334 gccgo. Both options take directories to search. The
  335 <code>-L</code> option is also passed to the linker.
  336 </p>
  338 <p>
  339 The gccgo compiler does not currently (2015-06-15) record
  340 the file name of imported packages in the object file. You must
  341 arrange for the imported data to be linked into the program.
  342 Again, this is not necessary when building with the go command.
  343 </p>
  345 <pre>
  346 gccgo -c mypackage.go              # Exports mypackage
  347 gccgo -c main.go                   # Imports mypackage
  348 gccgo -o main main.o mypackage.o   # Explicitly links with mypackage.o
  349 </pre>
  351 <h2 id="Debugging">Debugging</h2>
  353 <p>
  354 If you use the <code>-g</code> option when you compile, you can run
  355 <code>gdb</code> on your executable. The debugger has only limited
  356 knowledge about Go. You can set breakpoints, single-step,
  357 etc. You can print variables, but they will be printed as though they
  358 had C/C++ types. For numeric types this doesn't matter. Go strings
  359 and interfaces will show up as two-element structures. Go
  360 maps and channels are always represented as C pointers to run-time
  361 structures.
  362 </p>
  364 <h2 id="C_Interoperability">C Interoperability</h2>
  366 <p>
  367 When using gccgo there is limited interoperability with C,
  368 or with C++ code compiled using <code>extern "C"</code>.
  369 </p>
  371 <h3 id="Types">Types</h3>
  373 <p>
  374 Basic types map directly: an <code>int32</code> in Go is
  375 an <code>int32_t</code> in C, an <code>int64</code> is
  376 an <code>int64_t</code>, etc.
  377 The Go type <code>int</code> is an integer that is the same size as a
  378 pointer, and as such corresponds to the C type <code>intptr_t</code>.
  379 Go <code>byte</code> is equivalent to C <code>unsigned char</code>.
  380 Pointers in Go are pointers in C.
  381 A Go <code>struct</code> is the same as C <code>struct</code> with the
  382 same fields and types.
  383 </p>
  385 <p>
  386 The Go <code>string</code> type is currently defined as a two-element
  387 structure (this is <b style="color: red;">subject to change</b>):
  388 </p>
  390 <pre>
  391 struct __go_string {
  392   const unsigned char *__data;
  393   intptr_t __length;
  394 };
  395 </pre>
  397 <p>
  398 You can't pass arrays between C and Go. However, a pointer to an
  399 array in Go is equivalent to a C pointer to the
  400 equivalent of the element type.
  401 For example, Go <code>*[10]int</code> is equivalent to C <code>int*</code>,
  402 assuming that the C pointer does point to 10 elements.
  403 </p>
  405 <p>
  406 A slice in Go is a structure. The current definition is
  407 (this is <b style="color: red;">subject to change</b>):
  408 </p>
  410 <pre>
  411 struct __go_slice {
  412   void *__values;
  413   intptr_t __count;
  414   intptr_t __capacity;
  415 };
  416 </pre>
  418 <p>
  419 The type of a Go function is a pointer to a struct (this is
  420 <b style="color: red;">subject to change</b>). The first field in the
  421 struct points to the code of the function, which will be equivalent to
  422 a pointer to a C function whose parameter types are equivalent, with
  423 an additional trailing parameter. The trailing parameter is the
  424 closure, and the argument to pass is a pointer to the Go function
  425 struct.
  427 When a Go function returns more than one value, the C function returns
  428 a struct. For example, these functions are roughly equivalent:
  429 </p>
  431 <pre>
  432 func GoFunction(int) (int, float64)
  433 struct { int i; float64 f; } CFunction(int, void*)
  434 </pre>
  436 <p>
  437 Go <code>interface</code>, <code>channel</code>, and <code>map</code>
  438 types have no corresponding C type (<code>interface</code> is a
  439 two-element struct and <code>channel</code> and <code>map</code> are
  440 pointers to structs in C, but the structs are deliberately undocumented). C
  441 <code>enum</code> types correspond to some integer type, but precisely
  442 which one is difficult to predict in general; use a cast. C <code>union</code>
  443 types have no corresponding Go type. C <code>struct</code> types containing
  444 bitfields have no corresponding Go type. C++ <code>class</code> types have
  445 no corresponding Go type.
  446 </p>
  448 <p>
  449 Memory allocation is completely different between C and Go, as Go uses
  450 garbage collection. The exact guidelines in this area are undetermined,
  451 but it is likely that it will be permitted to pass a pointer to allocated
  452 memory from C to Go. The responsibility of eventually freeing the pointer
  453 will remain with C side, and of course if the C side frees the pointer
  454 while the Go side still has a copy the program will fail. When passing a
  455 pointer from Go to C, the Go function must retain a visible copy of it in
  456 some Go variable. Otherwise the Go garbage collector may delete the
  457 pointer while the C function is still using it.
  458 </p>
  460 <h3 id="Function_names">Function names</h3>
  462 <p>
  463 Go code can call C functions directly using a Go extension implemented
  464 in gccgo: a function declaration may be preceded by
  465 <code>//extern NAME</code>. For example, here is how the C function
  466 <code>open</code> can be declared in Go:
  467 </p>
  469 <pre>
  470 //extern open
  471 func c_open(name *byte, mode int, perm int) int
  472 </pre>
  474 <p>
  475 The C function naturally expects a NUL-terminated string, which in
  476 Go is equivalent to a pointer to an array (not a slice!) of
  477 <code>byte</code> with a terminating zero byte. So a sample call
  478 from Go would look like (after importing the <code>syscall</code> package):
  479 </p>
  481 <pre>
  482 var name = [4]byte{'f', 'o', 'o', 0};
  483 i := c_open(&amp;name[0], syscall.O_RDONLY, 0);
  484 </pre>
  486 <p>
  487 (this serves as an example only, to open a file in Go please use Go's
  488 <code>os.Open</code> function instead).
  489 </p>
  491 <p>
  492 Note that if the C function can block, such as in a call
  493 to <code>read</code>, calling the C function may block the Go program.
  494 Unless you have a clear understanding of what you are doing, all calls
  495 between C and Go should be implemented through cgo or SWIG, as for
  496 the <code>gc</code> compiler.
  497 </p>
  499 <p>
  500 The name of Go functions accessed from C is subject to change. At present
  501 the name of a Go function that does not have a receiver is
  502 <code>prefix.package.Functionname</code>. The prefix is set by
  503 the <code>-fgo-prefix</code> option used when the package is compiled;
  504 if the option is not used, the default is <code>go</code>.
  505 To call the function from C you must set the name using
  506 a GCC extension.
  507 </p>
  509 <pre>
  510 extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
  511 </pre>
  513 <h3 id="Automatic_generation_of_Go_declarations_from_C_source_code">
  514 Automatic generation of Go declarations from C source code</h3>
  516 <p>
  517 The Go version of GCC supports automatically generating
  518 Go declarations from C code. The facility is rather awkward, and most
  519 users should use the <a href="/cmd/cgo">cgo</a> program with
  520 the <code>-gccgo</code> option instead.
  521 </p>
  523 <p>
  524 Compile your C code as usual, and add the option
  525 <code>-fdump-go-spec=<var>FILENAME</var></code>. This will create the
  526 file <code><var>FILENAME</var></code> as a side effect of the
  527 compilation. This file will contain Go declarations for the types,
  528 variables and functions declared in the C code. C types that can not
  529 be represented in Go will be recorded as comments in the Go code. The
  530 generated file will not have a <code>package</code> declaration, but
  531 can otherwise be compiled directly by gccgo.
  532 </p>
  534 <p>
  535 This procedure is full of unstated caveats and restrictions and we make no
  536 guarantee that it will not change in the future. It is more useful as a
  537 starting point for real Go code than as a regular procedure.
  538 </p>