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.
|
145
|
15 @set copyrights-go 2010-2020
|
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
|
145
|
249 @item -fgo-debug-optimization
|
|
250 @cindex @option{-fgo-debug-optimization}
|
|
251 @cindex @option{-fno-go-debug-optimization}
|
|
252 Output optimization diagnostics.
|
|
253
|
111
|
254 @item -fgo-c-header=@var{file}
|
|
255 @cindex @option{-fgo-c-header}
|
|
256 Write top-level named Go struct definitions to @var{file} as C code.
|
|
257 This is used when compiling the runtime package.
|
|
258
|
|
259 @item -fgo-compiling-runtime
|
|
260 @cindex @option{-fgo-compiling-runtime}
|
|
261 Apply special rules for compiling the runtime package. Implicit
|
|
262 memory allocation is forbidden. Some additional compiler directives
|
|
263 are supported.
|
|
264
|
|
265 @item -g
|
|
266 @cindex @option{-g for gccgo}
|
|
267 This is the standard @command{gcc} option (@pxref{Debugging Options, ,
|
|
268 Debugging Options, gcc, Using the GNU Compiler Collection (GCC)}). It
|
|
269 is mentioned here because by default @command{gccgo} turns on
|
|
270 debugging information generation with the equivalent of the standard
|
|
271 option @option{-g1}. This is because Go programs require debugging
|
|
272 information to be available in order to get backtrace information. An
|
|
273 explicit @option{-g0} may be used to disable the generation of
|
|
274 debugging information, in which case certain standard library
|
|
275 functions, such as @code{runtime.Callers}, will not operate correctly.
|
|
276 @end table
|
|
277
|
|
278 @c man end
|
|
279
|
|
280 @node Import and Export
|
|
281 @chapter Import and Export
|
|
282
|
|
283 When @command{gccgo} compiles a package which exports anything, the
|
|
284 export information will be stored directly in the object file. When a
|
|
285 package is imported, @command{gccgo} must be able to find the file.
|
|
286
|
|
287 @cindex @file{.gox}
|
|
288 When Go code imports the package @file{@var{gopackage}}, @command{gccgo}
|
|
289 will look for the import data using the following filenames, using the
|
|
290 first one that it finds.
|
|
291
|
|
292 @table @file
|
|
293 @item @var{gopackage}.gox
|
|
294 @item lib@var{gopackage}.so
|
|
295 @item lib@var{gopackage}.a
|
|
296 @item @var{gopackage}.o
|
|
297 @end table
|
|
298
|
|
299 The compiler will search for these files in the directories named by
|
|
300 any @option{-I} options, in order in which the directories appear on
|
|
301 the command line. The compiler will then search several standard
|
|
302 system directories. Finally the compiler will search the current
|
|
303 directory (to search the current directory earlier, use @samp{-I.}).
|
|
304
|
|
305 The compiler will extract the export information directly from the
|
|
306 compiled object file. The file @file{@var{gopackage}.gox} will
|
|
307 typically contain nothing but export data. This can be generated from
|
|
308 @file{@var{gopackage}.o} via
|
|
309
|
|
310 @smallexample
|
|
311 objcopy -j .go_export @var{gopackage}.o @var{gopackage}.gox
|
|
312 @end smallexample
|
|
313
|
|
314 For example, it may be desirable to extract the export information
|
|
315 from several different packages into their independent
|
|
316 @file{@var{gopackage}.gox} files, and then to combine the different
|
|
317 package object files together into a single shared library or archive.
|
|
318
|
|
319 At link time you must explicitly tell @command{gccgo} which files to
|
|
320 link together into the executable, as is usual with @command{gcc}.
|
|
321 This is different from the behavior of other Go compilers.
|
|
322
|
|
323 @node Compiler Directives
|
|
324 @chapter Compiler Directives
|
|
325
|
|
326 The Go compiler supports a few compiler directives. A compiler
|
|
327 directive uses a @code{//} comment at the start of a line. There must
|
|
328 be no space between the @code{//} and the name of the directive.
|
|
329
|
|
330 @table @code
|
|
331 @item //line @var{file}:@var{line}
|
|
332 The @code{//line} directive specifies that the source line that
|
|
333 follows should be recorded as having come from the given file path and
|
|
334 line number. Successive lines are recorded using increasing line
|
|
335 numbers, until the next directive. This directive typically appears
|
|
336 in machine-generated code, so that compilers and debuggers will show
|
|
337 lines in the original input to the generator.
|
|
338
|
|
339 @item //extern @var{extern_name}
|
|
340 The @code{extern} directive sets the externally visible name of the
|
|
341 next function declaration. See @ref{Function Names}.
|
|
342
|
|
343 @item //go:compile @var{go_name} @var{extern_name}
|
|
344 The @code{go:compile} directives sets the externally visible name of a
|
|
345 function definition or declaration. See @ref{Function Names}.
|
|
346
|
|
347 @item //go:noescape
|
|
348 The @code{//go:noescape} directive specifies that the next declaration
|
|
349 in the file, which must be a func without a body (meaning that it has
|
|
350 an implementation not written in Go) does not allow any of the
|
|
351 pointers passed as arguments to escape into the heap or into the
|
|
352 values returned from the function. This information can be used during
|
|
353 the compiler's escape analysis of Go code calling the function.
|
|
354
|
|
355 @item //go:nosplit
|
|
356 The @code{//go:nosplit} directive specifies that the next function
|
|
357 declared in the file must not include a stack overflow check. This is
|
|
358 most commonly used by low-level runtime sources invoked at times when
|
|
359 it is unsafe for the calling goroutine to be preempted.
|
|
360
|
|
361 @item //go:noinline
|
|
362 The @code{//go:noinline} directive specifies that the next function
|
|
363 defined in the file may not be inlined.
|
|
364
|
|
365 @end table
|
|
366
|
|
367 @node C Interoperability
|
|
368 @chapter C Interoperability
|
|
369
|
|
370 When using @command{gccgo} there is limited interoperability with C,
|
|
371 or with C++ code compiled using @code{extern "C"}.
|
|
372
|
|
373 This information is provided largely for documentation purposes. For
|
|
374 ordinary use it is best to build programs with the go tool and then
|
|
375 use @code{import "C"}, as described at
|
|
376 @url{http://golang.org/cmd/cgo}.
|
|
377
|
|
378 @menu
|
|
379 * C Type Interoperability:: How C and Go types match up.
|
|
380 * Function Names:: How Go functions are named.
|
|
381 @end menu
|
|
382
|
|
383 @node C Type Interoperability
|
|
384 @section C Type Interoperability
|
|
385
|
|
386 Basic types map directly: an @code{int} in Go is an @code{int} in C,
|
|
387 etc. Go @code{byte} is equivalent to C @code{unsigned char}.
|
|
388 Pointers in Go are pointers in C. A Go @code{struct} is the same as C
|
|
389 @code{struct} with the same field names and types.
|
|
390
|
|
391 @cindex @code{string} in C
|
|
392 The Go @code{string} type is currently defined as a two-element
|
|
393 structure:
|
|
394
|
|
395 @smallexample
|
|
396 struct __go_string @{
|
|
397 const unsigned char *__data;
|
|
398 int __length;
|
|
399 @};
|
|
400 @end smallexample
|
|
401
|
|
402 You can't pass arrays between C and Go. However, a pointer to an
|
|
403 array in Go is equivalent to a C pointer to the equivalent of the
|
|
404 element type. For example, Go @code{*[10]int} is equivalent to C
|
|
405 @code{int*}, assuming that the C pointer does point to 10 elements.
|
|
406
|
|
407 @cindex @code{slice} in C
|
|
408 A slice in Go is a structure. The current definition is:
|
|
409
|
|
410 @smallexample
|
|
411 struct __go_slice @{
|
|
412 void *__values;
|
|
413 int __count;
|
|
414 int __capacity;
|
|
415 @};
|
|
416 @end smallexample
|
|
417
|
|
418 The type of a Go function with no receiver is equivalent to a C
|
|
419 function whose parameter types are equivalent. When a Go function
|
|
420 returns more than one value, the C function returns a struct. For
|
|
421 example, these functions have equivalent types:
|
|
422
|
|
423 @smallexample
|
|
424 func GoFunction(int) (int, float)
|
|
425 struct @{ int i; float f; @} CFunction(int)
|
|
426 @end smallexample
|
|
427
|
|
428 A pointer to a Go function is equivalent to a pointer to a C function
|
|
429 when the functions have equivalent types.
|
|
430
|
|
431 Go @code{interface}, @code{channel}, and @code{map} types have no
|
|
432 corresponding C type (@code{interface} is a two-element struct and
|
|
433 @code{channel} and @code{map} are pointers to structs in C, but the
|
|
434 structs are deliberately undocumented). C @code{enum} types
|
|
435 correspond to some integer type, but precisely which one is difficult
|
|
436 to predict in general; use a cast. C @code{union} types have no
|
|
437 corresponding Go type. C @code{struct} types containing bitfields
|
|
438 have no corresponding Go type. C++ @code{class} types have no
|
|
439 corresponding Go type.
|
|
440
|
|
441 Memory allocation is completely different between C and Go, as Go uses
|
|
442 garbage collection. The exact guidelines in this area are
|
|
443 undetermined, but it is likely that it will be permitted to pass a
|
|
444 pointer to allocated memory from C to Go. The responsibility of
|
|
445 eventually freeing the pointer will remain with C side, and of course
|
|
446 if the C side frees the pointer while the Go side still has a copy the
|
|
447 program will fail. When passing a pointer from Go to C, the Go
|
|
448 function must retain a visible copy of it in some Go variable.
|
|
449 Otherwise the Go garbage collector may delete the pointer while the C
|
|
450 function is still using it.
|
|
451
|
|
452 @node Function Names
|
|
453 @section Function Names
|
|
454
|
|
455 @cindex @code{extern}
|
|
456 @cindex external names
|
|
457 Go code can call C functions directly using the @code{//extern} or
|
|
458 @code{//go:linkname} compiler directives. An @code{//extern}
|
|
459 directive must be at the beginning of the line and must start with
|
|
460 @code{//extern}. This must be followed by a space and then the
|
|
461 external name of the function. The function declaration must be on
|
|
462 the line immediately after the comment. For example, here is how the
|
|
463 C function @code{open} can be declared in Go:
|
|
464
|
|
465 @smallexample
|
|
466 //extern open
|
|
467 func c_open(name *byte, mode int, perm int) int
|
|
468 @end smallexample
|
|
469
|
|
470 You can do the same thing using the @code{//go:linkname} compiler
|
|
471 directive. The @code{//go:linkname} directive must be at the start of
|
|
472 the line. It is followed by whitespace, the name of the Go function,
|
|
473 more whitespace, and the external name of the function. Unlike
|
|
474 @code{//extern}, @code{//go:linkname} does not need to appear
|
|
475 immediately adjacent to the function definition or declaration.
|
|
476
|
|
477 @smallexample
|
|
478 //go:linkname c_open open
|
|
479 func c_open(name *byte, mode int, perm int) int
|
|
480 @end smallexample
|
|
481
|
|
482 The C function naturally expects a nul terminated string, which in Go
|
|
483 is equivalent to a pointer to an array (not a slice!) of @code{byte}
|
|
484 with a terminating zero byte. So a sample call from Go would look
|
|
485 like (after importing the @code{os} package):
|
|
486
|
|
487 @smallexample
|
|
488 var name = [4]byte@{'f', 'o', 'o', 0@};
|
|
489 i := c_open(&name[0], os.O_RDONLY, 0);
|
|
490 @end smallexample
|
|
491
|
|
492 Note that this serves as an example only. To open a file in Go please
|
|
493 use Go's @code{os.Open} function instead.
|
|
494
|
|
495 The name of Go functions accessed from C is subject to change. At
|
|
496 present the name of a Go function that does not have a receiver is
|
|
497 @code{pkgpath.Functionname}. The @var{pkgpath} is set by the
|
|
498 @option{-fgo-pkgpath} option used when the package is compiled; if the
|
|
499 option is not used, the default is @code{go.@var{packagename}}. To
|
|
500 call the function from C you must set the name using the @command{gcc}
|
|
501 @code{__asm__} extension.
|
|
502
|
|
503 @smallexample
|
|
504 extern int go_function(int) __asm__ ("mypkgpath.Function");
|
|
505 @end smallexample
|
|
506
|
|
507 @node Index
|
|
508 @unnumbered Index
|
|
509
|
|
510 @printindex cp
|
|
511
|
|
512 @bye
|