1 \input texinfo @c -*-texinfo-*-
2 @setfilename gccgo.info
3 @settitle The GNU Go Compiler
5 @c Merge the standard indexes into a single one.
12 @include gcc-common.texi
14 @c Copyright years for this manual.
15 @set copyrights-go 2010-2024
18 @c man begin COPYRIGHT
19 Copyright @copyright{} @value{copyrights-go} Free Software Foundation, Inc.
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
28 section entitled ``GNU Free Documentation License''.
30 @c man begin COPYRIGHT
35 @c man begin COPYRIGHT
37 (a) The FSF's Front-Cover Text is:
41 (b) The FSF's Back-Cover Text is:
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.
51 @dircategory Software development
53 * Gccgo: (gccgo). A GCC-based compiler for the Go language
61 @title The GNU Go Compiler
63 @author Ian Lance Taylor
66 @vskip 0pt plus 1filll
67 Published by the Free Software Foundation @*
68 51 Franklin Street, Fifth Floor@*
69 Boston, MA 02110-1301, USA@*
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{https://go.dev}.
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.
103 @chapter Invoking gccgo
105 @c man title gccgo A GCC-based compiler for the Go language
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{}
114 Only the most useful options are listed here; see below for the
118 gpl(7), gfdl(7), fsf-funding(7), gcc(1)
119 and the Info entries for @file{gccgo} and @file{gcc}.
123 @c man begin DESCRIPTION gccgo
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}.
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
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.
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
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.
152 @c man begin OPTIONS gccgo
157 Specify a directory to use when searching for an import package at
162 When linking, specify a library search directory, as with
165 @cindex @option{-fgo-pkgpath}
166 @item -fgo-pkgpath=@var{string}
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.
174 @cindex @option{-fgo-prefix}
175 @item -fgo-prefix=@var{string}
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}
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
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.
192 @cindex @option{-fgo-relative-import-path}
193 @item -fgo-relative-import-path=@var{dir}
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.
198 @cindex @option{-frequire-return-statement}
199 @cindex @option{-fno-require-return-statement}
200 @item -frequire-return-statement
201 @itemx -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}.
207 @cindex @option{-fgo-check-divide-zero}
208 @cindex @option{-fno-go-check-divide-zero}
209 @item -fgo-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
220 @cindex @option{-fgo-check-divide-overflow}
221 @cindex @option{-fno-go-check-divide-overflow}
222 @item -fgo-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
232 @cindex @option{-fno-go-optimize-allocs}
233 @item -fno-go-optimize-allocs
234 Disable escape analysis, which tries to allocate objects on the stack
235 rather than the heap.
237 @cindex @option{-fgo-debug-escape}
238 @item -fgo-debug-escape@var{n}
239 Output escape analysis debugging information. Larger values of
240 @var{n} generate more information.
242 @cindex @option{-fgo-debug-escape-hash}
243 @item -fgo-debug-escape-hash=@var{n}
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.
249 @cindex @option{-fgo-debug-optimization}
250 @cindex @option{-fno-go-debug-optimization}
251 @item -fgo-debug-optimization
252 Output optimization diagnostics.
254 @cindex @option{-fgo-c-header}
255 @item -fgo-c-header=@var{file}
256 Write top-level named Go struct definitions to @var{file} as C code.
257 This is used when compiling the runtime package.
259 @cindex @option{-fgo-compiling-runtime}
260 @item -fgo-compiling-runtime
261 Apply special rules for compiling the runtime package. Implicit
262 memory allocation is forbidden. Some additional compiler directives
265 @cindex @option{-fgo-embedcfg}
266 @item -fgo-embedcfg=@var{file}
267 Identify a JSON file used to map patterns used with special
268 @code{//go:embed} comments to the files named by the patterns. The
269 JSON file should have two components: @code{Patterns} maps each
270 pattern to a list of file names, and @code{Files} maps each file name
271 to a full path to the file. This option is intended for use by the
272 @command{go} command to implement @code{//go:embed}.
274 @cindex @option{-fgo-importcfg}
275 @item -fgo-importcfg=@var{file}
276 Identify a file that provides mappings for import package paths found
277 in the Go source files. The file can contain two commands:
278 @code{importpath} to rename import paths for vendoring and
279 @code{packagefile} to map from package path to files containing export
280 data. This option is intended for use by the @command{go} command.
282 @cindex @option{-g for gccgo}
284 This is the standard @command{gcc} option (@pxref{Debugging Options, ,
285 Debugging Options, gcc, Using the GNU Compiler Collection (GCC)}). It
286 is mentioned here because by default @command{gccgo} turns on
287 debugging information generation with the equivalent of the standard
288 option @option{-g1}. This is because Go programs require debugging
289 information to be available in order to get backtrace information. An
290 explicit @option{-g0} may be used to disable the generation of
291 debugging information, in which case certain standard library
292 functions, such as @code{runtime.Callers}, will not operate correctly.
297 @node Import and Export
298 @chapter Import and Export
300 When @command{gccgo} compiles a package which exports anything, the
301 export information will be stored directly in the object file. When a
302 package is imported, @command{gccgo} must be able to find the file.
305 When Go code imports the package @file{@var{gopackage}}, @command{gccgo}
306 will look for the import data using the following filenames, using the
307 first one that it finds.
310 @item @var{gopackage}.gox
311 @item lib@var{gopackage}.so
312 @item lib@var{gopackage}.a
313 @item @var{gopackage}.o
316 The compiler will search for these files in the directories named by
317 any @option{-I} options, in order in which the directories appear on
318 the command line. The compiler will then search several standard
319 system directories. Finally the compiler will search the current
320 directory (to search the current directory earlier, use @samp{-I.}).
322 The compiler will extract the export information directly from the
323 compiled object file. The file @file{@var{gopackage}.gox} will
324 typically contain nothing but export data. This can be generated from
325 @file{@var{gopackage}.o} via
328 objcopy -j .go_export @var{gopackage}.o @var{gopackage}.gox
331 For example, it may be desirable to extract the export information
332 from several different packages into their independent
333 @file{@var{gopackage}.gox} files, and then to combine the different
334 package object files together into a single shared library or archive.
336 At link time you must explicitly tell @command{gccgo} which files to
337 link together into the executable, as is usual with @command{gcc}.
338 This is different from the behavior of other Go compilers.
340 @node Compiler Directives
341 @chapter Compiler Directives
343 The Go compiler supports a few compiler directives. A compiler
344 directive uses a @code{//} comment at the start of a line. There must
345 be no space between the @code{//} and the name of the directive.
348 @item //line @var{file}:@var{line}
349 The @code{//line} directive specifies that the source line that
350 follows should be recorded as having come from the given file path and
351 line number. Successive lines are recorded using increasing line
352 numbers, until the next directive. This directive typically appears
353 in machine-generated code, so that compilers and debuggers will show
354 lines in the original input to the generator.
356 @item //extern @var{extern_name}
357 The @code{extern} directive sets the externally visible name of the
358 next function declaration. See @ref{Function Names}.
360 @item //go:compile @var{go_name} @var{extern_name}
361 The @code{go:compile} directives sets the externally visible name of a
362 function definition or declaration. See @ref{Function Names}.
365 The @code{//go:noescape} directive specifies that the next declaration
366 in the file, which must be a func without a body (meaning that it has
367 an implementation not written in Go) does not allow any of the
368 pointers passed as arguments to escape into the heap or into the
369 values returned from the function. This information can be used during
370 the compiler's escape analysis of Go code calling the function.
373 The @code{//go:nosplit} directive specifies that the next function
374 declared in the file must not include a stack overflow check. This is
375 most commonly used by low-level runtime sources invoked at times when
376 it is unsafe for the calling goroutine to be preempted.
379 The @code{//go:noinline} directive specifies that the next function
380 defined in the file may not be inlined.
384 @node C Interoperability
385 @chapter C Interoperability
387 When using @command{gccgo} there is limited interoperability with C,
388 or with C++ code compiled using @code{extern "C"}.
390 This information is provided largely for documentation purposes. For
391 ordinary use it is best to build programs with the go tool and then
392 use @code{import "C"}, as described at @url{https://pkg.go.dev/cmd/cgo}.
395 * C Type Interoperability:: How C and Go types match up.
396 * Function Names:: How Go functions are named.
399 @node C Type Interoperability
400 @section C Type Interoperability
402 Basic types map directly: an @code{int} in Go is an @code{int} in C,
403 etc. Go @code{byte} is equivalent to C @code{unsigned char}.
404 Pointers in Go are pointers in C. A Go @code{struct} is the same as C
405 @code{struct} with the same field names and types.
407 @cindex @code{string} in C
408 The Go @code{string} type is currently defined as a two-element
412 struct __go_string @{
413 const unsigned char *__data;
418 You can't pass arrays between C and Go. However, a pointer to an
419 array in Go is equivalent to a C pointer to the equivalent of the
420 element type. For example, Go @code{*[10]int} is equivalent to C
421 @code{int*}, assuming that the C pointer does point to 10 elements.
423 @cindex @code{slice} in C
424 A slice in Go is a structure. The current definition is:
434 The type of a Go function with no receiver is equivalent to a C
435 function whose parameter types are equivalent. When a Go function
436 returns more than one value, the C function returns a struct. For
437 example, these functions have equivalent types:
440 func GoFunction(int) (int, float)
441 struct @{ int i; float f; @} CFunction(int)
444 A pointer to a Go function is equivalent to a pointer to a C function
445 when the functions have equivalent types.
447 Go @code{interface}, @code{channel}, and @code{map} types have no
448 corresponding C type (@code{interface} is a two-element struct and
449 @code{channel} and @code{map} are pointers to structs in C, but the
450 structs are deliberately undocumented). C @code{enum} types
451 correspond to some integer type, but precisely which one is difficult
452 to predict in general; use a cast. C @code{union} types have no
453 corresponding Go type. C @code{struct} types containing bitfields
454 have no corresponding Go type. C++ @code{class} types have no
455 corresponding Go type.
457 Memory allocation is completely different between C and Go, as Go uses
458 garbage collection. The exact guidelines in this area are
459 undetermined, but it is likely that it will be permitted to pass a
460 pointer to allocated memory from C to Go. The responsibility of
461 eventually freeing the pointer will remain with C side, and of course
462 if the C side frees the pointer while the Go side still has a copy the
463 program will fail. When passing a pointer from Go to C, the Go
464 function must retain a visible copy of it in some Go variable.
465 Otherwise the Go garbage collector may delete the pointer while the C
466 function is still using it.
469 @section Function Names
471 @cindex @code{extern}
472 @cindex external names
473 Go code can call C functions directly using the @code{//extern} or
474 @code{//go:linkname} compiler directives. An @code{//extern}
475 directive must be at the beginning of the line and must start with
476 @code{//extern}. This must be followed by a space and then the
477 external name of the function. The function declaration must be on
478 the line immediately after the comment. For example, here is how the
479 C function @code{open} can be declared in Go:
483 func c_open(name *byte, mode int, perm int) int
486 You can do the same thing using the @code{//go:linkname} compiler
487 directive. The @code{//go:linkname} directive must be at the start of
488 the line. It is followed by whitespace, the name of the Go function,
489 more whitespace, and the external name of the function. Unlike
490 @code{//extern}, @code{//go:linkname} does not need to appear
491 immediately adjacent to the function definition or declaration.
494 //go:linkname c_open open
495 func c_open(name *byte, mode int, perm int) int
498 The C function naturally expects a nul terminated string, which in Go
499 is equivalent to a pointer to an array (not a slice!) of @code{byte}
500 with a terminating zero byte. So a sample call from Go would look
501 like (after importing the @code{os} package):
504 var name = [4]byte@{'f', 'o', 'o', 0@};
505 i := c_open(&name[0], os.O_RDONLY, 0);
508 Note that this serves as an example only. To open a file in Go please
509 use Go's @code{os.Open} function instead.
511 The name of Go functions accessed from C is subject to change. At
512 present the name of a Go function that does not have a receiver is
513 @code{pkgpath.Functionname}. The @var{pkgpath} is set by the
514 @option{-fgo-pkgpath} option used when the package is compiled; if the
515 option is not used, the default is @code{go.@var{packagename}}. To
516 call the function from C you must set the name using the @command{gcc}
517 @code{__asm__} extension.
520 extern int go_function(int) __asm__ ("mypkgpath.Function");