summaryrefslogtreecommitdiff
path: root/gcc/go/gccgo.texi
blob: dc8b0225a239aa8119670c2eecc398998c429d10 (plain)
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
\input texinfo @c -*-texinfo-*-
@setfilename gccgo.info
@settitle The GNU Go Compiler

@c Merge the standard indexes into a single one.
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp

@include gcc-common.texi

@c Copyright years for this manual.
@set copyrights-go 2010

@copying
@c man begin COPYRIGHT
Copyright @copyright{} @value{copyrights-go} Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, the Front-Cover Texts being (a) (see below), and
with the Back-Cover Texts being (b) (see below).
A copy of the license is included in the
@c man end
section entitled ``GNU Free Documentation License''.
@ignore
@c man begin COPYRIGHT
man page gfdl(7).
@c man end
@end ignore

@c man begin COPYRIGHT

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@c man end
@end copying

@ifinfo
@format
@dircategory Software development
@direntry
* Gccgo: (gccgo).           A GCC-based compiler for the Go language
@end direntry
@end format

@insertcopying
@end ifinfo

@titlepage
@title The GNU Go Compiler
@versionsubtitle
@author Ian Lance Taylor

@page
@vskip 0pt plus 1filll
Published by the Free Software Foundation @*
51 Franklin Street, Fifth Floor@*
Boston, MA 02110-1301, USA@*
@sp 1
@insertcopying
@end titlepage
@contents
@page

@node Top
@top Introduction

This manual describes how to use @command{gccgo}, the GNU compiler for
the Go programming language.  This manual is specifically about
@command{gccgo}.  For more information about the Go programming
language in general, including language specifications and standard
package documentation, see @uref{http://golang.org/}.

@menu
* Copying::                     The GNU General Public License.
* GNU Free Documentation License::
                                How you can share and copy this manual.
* Invoking gccgo::              How to run gccgo.
* Import and Export::           Importing and exporting package data.
* C Interoperability::          Calling C from Go and vice-versa.
* Index::                       Index.
@end menu


@include gpl_v3.texi

@include fdl.texi


@node Invoking gccgo
@chapter Invoking gccgo

@c man title gccgo A GCC-based compiler for the Go language

@ignore
@c man begin SYNOPSIS gccgo
gccgo [@option{-c}|@option{-S}]
      [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
      [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
      [@option{-o} @var{outfile}] @var{infile}@dots{}

Only the most useful options are listed here; see below for the
remainder.
@c man end
@c man begin SEEALSO
gpl(7), gfdl(7), fsf-funding(7), gcc(1)
and the Info entries for @file{gccgo} and @file{gcc}.
@c man end
@end ignore

@c man begin DESCRIPTION gccgo

The @command{gccgo} command is a frontend to @command{gcc} and
supports many of the same options.  @xref{Option Summary, , Option
Summary, gcc, Using the GNU Compiler Collection (GCC)}.  This manual
only documents the options specific to @command{gccgo}.

The @command{gccgo} command may be used to compile Go source code into
an object file, link a collection of object files together, or do both
in sequence.

Go source code is compiled as packages.  A package consists of one or
more Go source files.  All the files in a single package must be
compiled together, by passing all the files as arguments to
@command{gccgo}.  A single invocation of @command{gccgo} may only
compile a single package.

One Go package may @code{import} a different Go package.  The imported
package must have already been compiled; @command{gccgo} will read
the import data directly from the compiled package.  When this package
is later linked, the compiled form of the package must be included in
the link command.

@c man end

@c man begin OPTIONS gccgo

@table @gcctabopt
@item -I@var{dir}
@cindex @option{-I}
Specify a directory to use when searching for an import package at
compile time.

@item -L@var{dir}
@cindex @option{-L}
When linking, specify a library search directory, as with
@command{gcc}.

@item -fgo-prefix=@var{string}
@cindex @option{-fgo-prefix}
Go permits a single program to include more than one package with the
same name.  This option is required to make this work with
@command{gccgo}.  The argument to this option may be any string.  Each
package with the same name must use a distinct @option{-fgo-prefix}
option.  The argument is typically the full path under which the
package will be installed, as that must obviously be unique.

@item -frequire-return-statement
@itemx -fno-require-return-statement
@cindex @option{-frequire-return-statement}
@cindex @option{-fno-require-return-statement}
By default @command{gccgo} will warn about functions which have one or
more return parameters but lack an explicit @code{return} statement.
This warning may be disabled using
@option{-fno-require-return-statement}.
@end table

@c man end

@node Import and Export
@chapter Import and Export

When @command{gccgo} compiles a package which exports anything, the
export information will be stored directly in the object file.  When a
package is imported, @command{gccgo} must be able to find the file.

@cindex @file{.gox}
When Go code imports the package @file{@var{gopackage}}, @command{gccgo}
will look for the import data using the following filenames, using the
first one that it finds.

@table @file
@item @var{gopackage}.gox
@item lib@var{gopackage}.so
@item lib@var{gopackage}.a
@item @var{gopackage}.o
@end table

The compiler will search for these files in the directories named by
any @option{-I} options, in order in which the directories appear on
the command line.  The compiler will then search several standard
system directories.  Finally the compiler will search the current
directory (to search the current directory earlier, use @samp{-I.}).

The compiler will extract the export information directly from the
compiled object file.  The file @file{@var{gopackage}.gox} will
typically contain nothing but export data.  This can be generated from
@file{@var{gopackage}.o} via

@smallexample
objcopy -j .go_export @var{gopackage}.o @var{gopackage}.gox
@end smallexample

For example, it may be desirable to extract the export information
from several different packages into their independent
@file{@var{gopackage}.gox} files, and then to combine the different
package object files together into a single shared library or archive.

At link time you must explicitly tell @command{gccgo} which files to
link together into the executable, as is usual with @command{gcc}.
This is different from the behaviour of other Go compilers.

@node C Interoperability
@chapter C Interoperability

When using @command{gccgo} there is limited interoperability with C,
or with C++ code compiled using @code{extern "C"}.

@menu
* C Type Interoperability::     How C and Go types match up.
* Function Names::              How Go functions are named.
@end menu

@node C Type Interoperability
@section C Type Interoperability

Basic types map directly: an @code{int} in Go is an @code{int} in C,
etc.  Go @code{byte} is equivalent to C @code{unsigned char}.
Pointers in Go are pointers in C.  A Go @code{struct} is the same as C
@code{struct} with the same field names and types.

@cindex @code{string} in C
The Go @code{string} type is currently defined as a two-element
structure:

@smallexample
struct __go_string @{
  const unsigned char *__data;
  int __length;
@};
@end smallexample

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} is equivalent to C
@code{int*}, assuming that the C pointer does point to 10 elements.

@cindex @code{slice} in C
A slice in Go is a structure.  The current definition is:

@smallexample
struct __go_slice @{
  void *__values;
  int __count;
  int __capacity;
@};
@end smallexample

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 functions have equivalent types:

@smallexample
func GoFunction(int) (int, float)
struct @{ int i; float f; @} CFunction(int)
@end smallexample

A pointer to a Go function is equivalent to a pointer to a C function
when the functions have equivalent types.

Go @code{interface}, @code{channel}, and @code{map} types have no
corresponding C type (@code{interface} is a two-element struct and
@code{channel} and @code{map} are pointers to structs in C, but the
structs are deliberately undocumented).  C @code{enum} types
correspond to some integer type, but precisely which one is difficult
to predict in general; use a cast.  C @code{union} types have no
corresponding Go type.  C @code{struct} types containing bitfields
have no corresponding Go type.  C++ @code{class} types have no
corresponding Go type.

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.

@node Function Names
@section Function Names

@cindex @code{__asm__}
Go code can call C functions directly using a Go extension implemented
in @command{gccgo}: a function declaration may be followed by
@code{__asm__ ("@var{name}")}. For example, here is how the C function
@code{open} can be declared in Go:

@smallexample
func c_open(name *byte, mode int, perm int) int __asm__ ("open");
@end smallexample

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}
with a terminating zero byte.  So a sample call from Go would look
like (after importing the @code{os} package):

@smallexample
var name = [4]byte@{'f', 'o', 'o', 0@};
i := c_open(&name[0], os.O_RDONLY, 0);
@end smallexample

Note that this serves as an example only.  To open a file in Go please
use Go's @code{os.Open} function instead.

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}.  The prefix is set by the
@option{-fgo-prefix} option used when the package is compiled; if the
option is not used, the default is simply @code{go}.  To call the
function from C you must set the name using the @command{gcc}
extension similar to the @command{gccgo} extension.

@smallexample
extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
@end smallexample

@node Index
@unnumbered Index

@printindex cp

@bye