111
|
1 \input texinfo @c -*-texinfo-*-
|
|
2 @setfilename gccgo.info
|
|
3 @settitle The GNU Go Compiler
|
|
4
|
|
5 @c Merge the standard indexes into a single one.
|
|
6 @syncodeindex fn cp
|
|
7 @syncodeindex vr cp
|
|
8 @syncodeindex ky cp
|
|
9 @syncodeindex pg cp
|
|
10 @syncodeindex tp cp
|
|
11
|
|
12 @include gcc-common.texi
|
|
13
|
|
14 @c Copyright years for this manual.
|
131
|
15 @set copyrights-go 2010-2018
|
111
|
16
|
|
17 @copying
|
|
18 @c man begin COPYRIGHT
|
|
19 Copyright @copyright{} @value{copyrights-go} Free Software Foundation, Inc.
|
|
20
|
|
21 Permission is granted to copy, distribute and/or modify this document
|
|
22 under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
23 any later version published by the Free Software Foundation; with no
|
|
24 Invariant Sections, the Front-Cover Texts being (a) (see below), and
|
|
25 with the Back-Cover Texts being (b) (see below).
|
|
26 A copy of the license is included in the
|
|
27 @c man end
|
|
28 section entitled ``GNU Free Documentation License''.
|
|
29 @ignore
|
|
30 @c man begin COPYRIGHT
|
|
31 man page gfdl(7).
|
|
32 @c man end
|
|
33 @end ignore
|
|
34
|
|
35 @c man begin COPYRIGHT
|
|
36
|
|
37 (a) The FSF's Front-Cover Text is:
|
|
38
|
|
39 A GNU Manual
|
|
40
|
|
41 (b) The FSF's Back-Cover Text is:
|
|
42
|
|
43 You have freedom to copy and modify this GNU Manual, like GNU
|
|
44 software. Copies published by the Free Software Foundation raise
|
|
45 funds for GNU development.
|
|
46 @c man end
|
|
47 @end copying
|
|
48
|
|
49 @ifinfo
|
|
50 @format
|
|
51 @dircategory Software development
|
|
52 @direntry
|
|
53 * Gccgo: (gccgo). A GCC-based compiler for the Go language
|
|
54 @end direntry
|
|
55 @end format
|
|
56
|
|
57 @insertcopying
|
|
58 @end ifinfo
|
|
59
|
|
60 @titlepage
|
|
61 @title The GNU Go Compiler
|
|
62 @versionsubtitle
|
|
63 @author Ian Lance Taylor
|
|
64
|
|
65 @page
|
|
66 @vskip 0pt plus 1filll
|
|
67 Published by the Free Software Foundation @*
|
|
68 51 Franklin Street, Fifth Floor@*
|
|
69 Boston, MA 02110-1301, USA@*
|
|
70 @sp 1
|
|
71 @insertcopying
|
|
72 @end titlepage
|
|
73 @contents
|
|
74 @page
|
|
75
|
|
76 @node Top
|
|
77 @top Introduction
|
|
78
|
|
79 This manual describes how to use @command{gccgo}, the GNU compiler for
|
|
80 the Go programming language. This manual is specifically about
|
|
81 @command{gccgo}. For more information about the Go programming
|
|
82 language in general, including language specifications and standard
|
|
83 package documentation, see @uref{http://golang.org/}.
|
|
84
|
|
85 @menu
|
|
86 * Copying:: The GNU General Public License.
|
|
87 * GNU Free Documentation License::
|
|
88 How you can share and copy this manual.
|
|
89 * Invoking gccgo:: How to run gccgo.
|
|
90 * Import and Export:: Importing and exporting package data.
|
|
91 * Compiler Directives:: Comments to control compilation.
|
|
92 * C Interoperability:: Calling C from Go and vice-versa.
|
|
93 * Index:: Index.
|
|
94 @end menu
|
|
95
|
|
96
|
|
97 @include gpl_v3.texi
|
|
98
|
|
99 @include fdl.texi
|
|
100
|
|
101
|
|
102 @node Invoking gccgo
|
|
103 @chapter Invoking gccgo
|
|
104
|
|
105 @c man title gccgo A GCC-based compiler for the Go language
|
|
106
|
|
107 @ignore
|
|
108 @c man begin SYNOPSIS gccgo
|
|
109 gccgo [@option{-c}|@option{-S}]
|
|
110 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
|
|
111 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
|
|
112 [@option{-o} @var{outfile}] @var{infile}@dots{}
|
|
113
|
|
114 Only the most useful options are listed here; see below for the
|
|
115 remainder.
|
|
116 @c man end
|
|
117 @c man begin SEEALSO
|
|
118 gpl(7), gfdl(7), fsf-funding(7), gcc(1)
|
|
119 and the Info entries for @file{gccgo} and @file{gcc}.
|
|
120 @c man end
|
|
121 @end ignore
|
|
122
|
|
123 @c man begin DESCRIPTION gccgo
|
|
124
|
|
125 The @command{gccgo} command is a frontend to @command{gcc} and
|
|
126 supports many of the same options. @xref{Option Summary, , Option
|
|
127 Summary, gcc, Using the GNU Compiler Collection (GCC)}. This manual
|
|
128 only documents the options specific to @command{gccgo}.
|
|
129
|
|
130 The @command{gccgo} command may be used to compile Go source code into
|
|
131 an object file, link a collection of object files together, or do both
|
|
132 in sequence.
|
|
133
|
|
134 Go source code is compiled as packages. A package consists of one or
|
|
135 more Go source files. All the files in a single package must be
|
|
136 compiled together, by passing all the files as arguments to
|
|
137 @command{gccgo}. A single invocation of @command{gccgo} may only
|
|
138 compile a single package.
|
|
139
|
|
140 One Go package may @code{import} a different Go package. The imported
|
|
141 package must have already been compiled; @command{gccgo} will read
|
|
142 the import data directly from the compiled package. When this package
|
|
143 is later linked, the compiled form of the package must be included in
|
|
144 the link command.
|
|
145
|
|
146 Go programs must generally be compiled with debugging information, and
|
|
147 @option{-g1} is the default as described below. Stripping a Go
|
|
148 program will generally cause it to misbehave or fail.
|
|
149
|
|
150 @c man end
|
|
151
|
|
152 @c man begin OPTIONS gccgo
|
|
153
|
|
154 @table @gcctabopt
|
|
155 @item -I@var{dir}
|
|
156 @cindex @option{-I}
|
|
157 Specify a directory to use when searching for an import package at
|
|
158 compile time.
|
|
159
|
|
160 @item -L@var{dir}
|
|
161 @cindex @option{-L}
|
|
162 When linking, specify a library search directory, as with
|
|
163 @command{gcc}.
|
|
164
|
|
165 @item -fgo-pkgpath=@var{string}
|
|
166 @cindex @option{-fgo-pkgpath}
|
|
167 Set the package path to use. This sets the value returned by the
|
|
168 PkgPath method of reflect.Type objects. It is also used for the names
|
|
169 of globally visible symbols. The argument to this option should
|
|
170 normally be the string that will be used to import this package after
|
|
171 it has been installed; in other words, a pathname within the
|
|
172 directories specified by the @option{-I} option.
|
|
173
|
|
174 @item -fgo-prefix=@var{string}
|
|
175 @cindex @option{-fgo-prefix}
|
|
176 An alternative to @option{-fgo-pkgpath}. The argument will be
|
|
177 combined with the package name from the source file to produce the
|
|
178 package path. If @option{-fgo-pkgpath} is used, @option{-fgo-prefix}
|
|
179 will be ignored.
|
|
180
|
|
181 Go permits a single program to include more than one package with the
|
|
182 same name in the @code{package} clause in the source file, though
|
|
183 obviously the two packages must be imported using different pathnames.
|
|
184 In order for this to work with @command{gccgo}, either
|
|
185 @option{-fgo-pkgpath} or @option{-fgo-prefix} must be specified when
|
|
186 compiling a package.
|
|
187
|
|
188 Using either @option{-fgo-pkgpath} or @option{-fgo-prefix} disables
|
|
189 the special treatment of the @code{main} package and permits that
|
|
190 package to be imported like any other.
|
|
191
|
|
192 @item -fgo-relative-import-path=@var{dir}
|
|
193 @cindex @option{-fgo-relative-import-path}
|
|
194 A relative import is an import that starts with @file{./} or
|
|
195 @file{../}. If this option is used, @command{gccgo} will use
|
|
196 @var{dir} as a prefix for the relative import when searching for it.
|
|
197
|
|
198 @item -frequire-return-statement
|
|
199 @itemx -fno-require-return-statement
|
|
200 @cindex @option{-frequire-return-statement}
|
|
201 @cindex @option{-fno-require-return-statement}
|
|
202 By default @command{gccgo} will warn about functions which have one or
|
|
203 more return parameters but lack an explicit @code{return} statement.
|
|
204 This warning may be disabled using
|
|
205 @option{-fno-require-return-statement}.
|
|
206
|
|
207 @item -fgo-check-divide-zero
|
|
208 @cindex @option{-fgo-check-divide-zero}
|
|
209 @cindex @option{-fno-go-check-divide-zero}
|
|
210 Add explicit checks for division by zero. In Go a division (or
|
|
211 modulos) by zero causes a panic. On Unix systems this is detected in
|
|
212 the runtime by catching the @code{SIGFPE} signal. Some processors,
|
|
213 such as PowerPC, do not generate a SIGFPE on division by zero. Some
|
|
214 runtimes do not generate a signal that can be caught. On those
|
|
215 systems, this option may be used. Or the checks may be removed via
|
|
216 @option{-fno-go-check-divide-zero}. This option is currently on by
|
|
217 default, but in the future may be off by default on systems that do
|
|
218 not require it.
|
|
219
|
|
220 @item -fgo-check-divide-overflow
|
|
221 @cindex @option{-fgo-check-divide-overflow}
|
|
222 @cindex @option{-fno-go-check-divide-overflow}
|
|
223 Add explicit checks for division overflow. For example, division
|
|
224 overflow occurs when computing @code{INT_MIN / -1}. In Go this should
|
|
225 be wrapped, to produce @code{INT_MIN}. Some processors, such as x86,
|
|
226 generate a trap on division overflow. On those systems, this option
|
|
227 may be used. Or the checks may be removed via
|
|
228 @option{-fno-go-check-divide-overflow}. This option is currently on
|
|
229 by default, but in the future may be off by default on systems that do
|
|
230 not require it.
|
|
231
|
131
|
232 @item -fno-go-optimize-allocs
|
|
233 @cindex @option{-fno-go-optimize-allocs}
|
|
234 Disable escape analysis, which tries to allocate objects on the stack
|
|
235 rather than the heap.
|
111
|
236
|
|
237 @item -fgo-debug-escape@var{n}
|
|
238 @cindex @option{-fgo-debug-escape}
|
|
239 Output escape analysis debugging information. Larger values of
|
|
240 @var{n} generate more information.
|
|
241
|
131
|
242 @item -fgo-debug-escape-hash=@var{n}
|
|
243 @cindex @option{-fgo-debug-escape-hash}
|
|
244 A hash value to debug escape analysis. @var{n} is a binary string.
|
|
245 This runs escape analysis only on functions whose names hash to values
|
|
246 that match the given suffix @var{n}. This can be used to binary
|
|
247 search across functions to uncover escape analysis bugs.
|
|
248
|
111
|
249 @item -fgo-c-header=@var{file}
|
|
250 @cindex @option{-fgo-c-header}
|
|
251 Write top-level named Go struct definitions to @var{file} as C code.
|
|
252 This is used when compiling the runtime package.
|
|
253
|
|
254 @item -fgo-compiling-runtime
|
|
255 @cindex @option{-fgo-compiling-runtime}
|
|
256 Apply special rules for compiling the runtime package. Implicit
|
|
257 memory allocation is forbidden. Some additional compiler directives
|
|
258 are supported.
|
|
259
|
|
260 @item -g
|
|
261 @cindex @option{-g for gccgo}
|
|
262 This is the standard @command{gcc} option (@pxref{Debugging Options, ,
|
|
263 Debugging Options, gcc, Using the GNU Compiler Collection (GCC)}). It
|
|
264 is mentioned here because by default @command{gccgo} turns on
|
|
265 debugging information generation with the equivalent of the standard
|
|
266 option @option{-g1}. This is because Go programs require debugging
|
|
267 information to be available in order to get backtrace information. An
|
|
268 explicit @option{-g0} may be used to disable the generation of
|
|
269 debugging information, in which case certain standard library
|
|
270 functions, such as @code{runtime.Callers}, will not operate correctly.
|
|
271 @end table
|
|
272
|
|
273 @c man end
|
|
274
|
|
275 @node Import and Export
|
|
276 @chapter Import and Export
|
|
277
|
|
278 When @command{gccgo} compiles a package which exports anything, the
|
|
279 export information will be stored directly in the object file. When a
|
|
280 package is imported, @command{gccgo} must be able to find the file.
|
|
281
|
|
282 @cindex @file{.gox}
|
|
283 When Go code imports the package @file{@var{gopackage}}, @command{gccgo}
|
|
284 will look for the import data using the following filenames, using the
|
|
285 first one that it finds.
|
|
286
|
|
287 @table @file
|
|
288 @item @var{gopackage}.gox
|
|
289 @item lib@var{gopackage}.so
|
|
290 @item lib@var{gopackage}.a
|
|
291 @item @var{gopackage}.o
|
|
292 @end table
|
|
293
|
|
294 The compiler will search for these files in the directories named by
|
|
295 any @option{-I} options, in order in which the directories appear on
|
|
296 the command line. The compiler will then search several standard
|
|
297 system directories. Finally the compiler will search the current
|
|
298 directory (to search the current directory earlier, use @samp{-I.}).
|
|
299
|
|
300 The compiler will extract the export information directly from the
|
|
301 compiled object file. The file @file{@var{gopackage}.gox} will
|
|
302 typically contain nothing but export data. This can be generated from
|
|
303 @file{@var{gopackage}.o} via
|
|
304
|
|
305 @smallexample
|
|
306 objcopy -j .go_export @var{gopackage}.o @var{gopackage}.gox
|
|
307 @end smallexample
|
|
308
|
|
309 For example, it may be desirable to extract the export information
|
|
310 from several different packages into their independent
|
|
311 @file{@var{gopackage}.gox} files, and then to combine the different
|
|
312 package object files together into a single shared library or archive.
|
|
313
|
|
314 At link time you must explicitly tell @command{gccgo} which files to
|
|
315 link together into the executable, as is usual with @command{gcc}.
|
|
316 This is different from the behavior of other Go compilers.
|
|
317
|
|
318 @node Compiler Directives
|
|
319 @chapter Compiler Directives
|
|
320
|
|
321 The Go compiler supports a few compiler directives. A compiler
|
|
322 directive uses a @code{//} comment at the start of a line. There must
|
|
323 be no space between the @code{//} and the name of the directive.
|
|
324
|
|
325 @table @code
|
|
326 @item //line @var{file}:@var{line}
|
|
327 The @code{//line} directive specifies that the source line that
|
|
328 follows should be recorded as having come from the given file path and
|
|
329 line number. Successive lines are recorded using increasing line
|
|
330 numbers, until the next directive. This directive typically appears
|
|
331 in machine-generated code, so that compilers and debuggers will show
|
|
332 lines in the original input to the generator.
|
|
333
|
|
334 @item //extern @var{extern_name}
|
|
335 The @code{extern} directive sets the externally visible name of the
|
|
336 next function declaration. See @ref{Function Names}.
|
|
337
|
|
338 @item //go:compile @var{go_name} @var{extern_name}
|
|
339 The @code{go:compile} directives sets the externally visible name of a
|
|
340 function definition or declaration. See @ref{Function Names}.
|
|
341
|
|
342 @item //go:noescape
|
|
343 The @code{//go:noescape} directive specifies that the next declaration
|
|
344 in the file, which must be a func without a body (meaning that it has
|
|
345 an implementation not written in Go) does not allow any of the
|
|
346 pointers passed as arguments to escape into the heap or into the
|
|
347 values returned from the function. This information can be used during
|
|
348 the compiler's escape analysis of Go code calling the function.
|
|
349
|
|
350 @item //go:nosplit
|
|
351 The @code{//go:nosplit} directive specifies that the next function
|
|
352 declared in the file must not include a stack overflow check. This is
|
|
353 most commonly used by low-level runtime sources invoked at times when
|
|
354 it is unsafe for the calling goroutine to be preempted.
|
|
355
|
|
356 @item //go:noinline
|
|
357 The @code{//go:noinline} directive specifies that the next function
|
|
358 defined in the file may not be inlined.
|
|
359
|
|
360 @end table
|
|
361
|
|
362 @node C Interoperability
|
|
363 @chapter C Interoperability
|
|
364
|
|
365 When using @command{gccgo} there is limited interoperability with C,
|
|
366 or with C++ code compiled using @code{extern "C"}.
|
|
367
|
|
368 This information is provided largely for documentation purposes. For
|
|
369 ordinary use it is best to build programs with the go tool and then
|
|
370 use @code{import "C"}, as described at
|
|
371 @url{http://golang.org/cmd/cgo}.
|
|
372
|
|
373 @menu
|
|
374 * C Type Interoperability:: How C and Go types match up.
|
|
375 * Function Names:: How Go functions are named.
|
|
376 @end menu
|
|
377
|
|
378 @node C Type Interoperability
|
|
379 @section C Type Interoperability
|
|
380
|
|
381 Basic types map directly: an @code{int} in Go is an @code{int} in C,
|
|
382 etc. Go @code{byte} is equivalent to C @code{unsigned char}.
|
|
383 Pointers in Go are pointers in C. A Go @code{struct} is the same as C
|
|
384 @code{struct} with the same field names and types.
|
|
385
|
|
386 @cindex @code{string} in C
|
|
387 The Go @code{string} type is currently defined as a two-element
|
|
388 structure:
|
|
389
|
|
390 @smallexample
|
|
391 struct __go_string @{
|
|
392 const unsigned char *__data;
|
|
393 int __length;
|
|
394 @};
|
|
395 @end smallexample
|
|
396
|
|
397 You can't pass arrays between C and Go. However, a pointer to an
|
|
398 array in Go is equivalent to a C pointer to the equivalent of the
|
|
399 element type. For example, Go @code{*[10]int} is equivalent to C
|
|
400 @code{int*}, assuming that the C pointer does point to 10 elements.
|
|
401
|
|
402 @cindex @code{slice} in C
|
|
403 A slice in Go is a structure. The current definition is:
|
|
404
|
|
405 @smallexample
|
|
406 struct __go_slice @{
|
|
407 void *__values;
|
|
408 int __count;
|
|
409 int __capacity;
|
|
410 @};
|
|
411 @end smallexample
|
|
412
|
|
413 The type of a Go function with no receiver is equivalent to a C
|
|
414 function whose parameter types are equivalent. When a Go function
|
|
415 returns more than one value, the C function returns a struct. For
|
|
416 example, these functions have equivalent types:
|
|
417
|
|
418 @smallexample
|
|
419 func GoFunction(int) (int, float)
|
|
420 struct @{ int i; float f; @} CFunction(int)
|
|
421 @end smallexample
|
|
422
|
|
423 A pointer to a Go function is equivalent to a pointer to a C function
|
|
424 when the functions have equivalent types.
|
|
425
|
|
426 Go @code{interface}, @code{channel}, and @code{map} types have no
|
|
427 corresponding C type (@code{interface} is a two-element struct and
|
|
428 @code{channel} and @code{map} are pointers to structs in C, but the
|
|
429 structs are deliberately undocumented). C @code{enum} types
|
|
430 correspond to some integer type, but precisely which one is difficult
|
|
431 to predict in general; use a cast. C @code{union} types have no
|
|
432 corresponding Go type. C @code{struct} types containing bitfields
|
|
433 have no corresponding Go type. C++ @code{class} types have no
|
|
434 corresponding Go type.
|
|
435
|
|
436 Memory allocation is completely different between C and Go, as Go uses
|
|
437 garbage collection. The exact guidelines in this area are
|
|
438 undetermined, but it is likely that it will be permitted to pass a
|
|
439 pointer to allocated memory from C to Go. The responsibility of
|
|
440 eventually freeing the pointer will remain with C side, and of course
|
|
441 if the C side frees the pointer while the Go side still has a copy the
|
|
442 program will fail. When passing a pointer from Go to C, the Go
|
|
443 function must retain a visible copy of it in some Go variable.
|
|
444 Otherwise the Go garbage collector may delete the pointer while the C
|
|
445 function is still using it.
|
|
446
|
|
447 @node Function Names
|
|
448 @section Function Names
|
|
449
|
|
450 @cindex @code{extern}
|
|
451 @cindex external names
|
|
452 Go code can call C functions directly using the @code{//extern} or
|
|
453 @code{//go:linkname} compiler directives. An @code{//extern}
|
|
454 directive must be at the beginning of the line and must start with
|
|
455 @code{//extern}. This must be followed by a space and then the
|
|
456 external name of the function. The function declaration must be on
|
|
457 the line immediately after the comment. For example, here is how the
|
|
458 C function @code{open} can be declared in Go:
|
|
459
|
|
460 @smallexample
|
|
461 //extern open
|
|
462 func c_open(name *byte, mode int, perm int) int
|
|
463 @end smallexample
|
|
464
|
|
465 You can do the same thing using the @code{//go:linkname} compiler
|
|
466 directive. The @code{//go:linkname} directive must be at the start of
|
|
467 the line. It is followed by whitespace, the name of the Go function,
|
|
468 more whitespace, and the external name of the function. Unlike
|
|
469 @code{//extern}, @code{//go:linkname} does not need to appear
|
|
470 immediately adjacent to the function definition or declaration.
|
|
471
|
|
472 @smallexample
|
|
473 //go:linkname c_open open
|
|
474 func c_open(name *byte, mode int, perm int) int
|
|
475 @end smallexample
|
|
476
|
|
477 The C function naturally expects a nul terminated string, which in Go
|
|
478 is equivalent to a pointer to an array (not a slice!) of @code{byte}
|
|
479 with a terminating zero byte. So a sample call from Go would look
|
|
480 like (after importing the @code{os} package):
|
|
481
|
|
482 @smallexample
|
|
483 var name = [4]byte@{'f', 'o', 'o', 0@};
|
|
484 i := c_open(&name[0], os.O_RDONLY, 0);
|
|
485 @end smallexample
|
|
486
|
|
487 Note that this serves as an example only. To open a file in Go please
|
|
488 use Go's @code{os.Open} function instead.
|
|
489
|
|
490 The name of Go functions accessed from C is subject to change. At
|
|
491 present the name of a Go function that does not have a receiver is
|
|
492 @code{pkgpath.Functionname}. The @var{pkgpath} is set by the
|
|
493 @option{-fgo-pkgpath} option used when the package is compiled; if the
|
|
494 option is not used, the default is @code{go.@var{packagename}}. To
|
|
495 call the function from C you must set the name using the @command{gcc}
|
|
496 @code{__asm__} extension.
|
|
497
|
|
498 @smallexample
|
|
499 extern int go_function(int) __asm__ ("mypkgpath.Function");
|
|
500 @end smallexample
|
|
501
|
|
502 @node Index
|
|
503 @unnumbered Index
|
|
504
|
|
505 @printindex cp
|
|
506
|
|
507 @bye
|