-
Notifications
You must be signed in to change notification settings - Fork 0
/
gccgo_install.html
529 lines (445 loc) · 16.6 KB
/
gccgo_install.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
<!--{
"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>
<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:[email protected]:/cvs/src login
[password is "anoncvs"]
[The next command will create a directory named src, not binutils]
cvs -z 9 -d :pserver:[email protected]:/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. 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 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:
</p>
<pre>
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>
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-prefix=PREFIX</code> option may be used to set a unique
prefix for the package being compiled. 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>PREFIX</code> may be any string; a good choice for the
string is the directory where the package will be installed.
</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 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 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 (2013-06-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
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>.