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
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{http://golang.org/}.
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 * C Interoperability:: Calling C from Go and vice-versa.
102 @chapter Invoking gccgo
104 @c man title gccgo A GCC-based compiler for the Go language
107 @c man begin SYNOPSIS gccgo
108 gccgo [@option{-c}|@option{-S}]
109 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
110 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
111 [@option{-o} @var{outfile}] @var{infile}@dots{}
113 Only the most useful options are listed here; see below for the
117 gpl(7), gfdl(7), fsf-funding(7), gcc(1)
118 and the Info entries for @file{gccgo} and @file{gcc}.
122 @c man begin DESCRIPTION gccgo
124 The @command{gccgo} command is a frontend to @command{gcc} and
125 supports many of the same options. @xref{Option Summary, , Option
126 Summary, gcc, Using the GNU Compiler Collection (GCC)}. This manual
127 only documents the options specific to @command{gccgo}.
129 The @command{gccgo} command may be used to compile Go source code into
130 an object file, link a collection of object files together, or do both
133 Go source code is compiled as packages. A package consists of one or
134 more Go source files. All the files in a single package must be
135 compiled together, by passing all the files as arguments to
136 @command{gccgo}. A single invocation of @command{gccgo} may only
137 compile a single package.
139 One Go package may @code{import} a different Go package. The imported
140 package must have already been compiled; @command{gccgo} will read
141 the import data directly from the compiled package. When this package
142 is later linked, the compiled form of the package must be included in
147 @c man begin OPTIONS gccgo
152 Specify a directory to use when searching for an import package at
157 When linking, specify a library search directory, as with
160 @item -fgo-prefix=@var{string}
161 @cindex @option{-fgo-prefix}
162 Go permits a single program to include more than one package with the
163 same name. This option is required to make this work with
164 @command{gccgo}. The argument to this option may be any string. Each
165 package with the same name must use a distinct @option{-fgo-prefix}
166 option. The argument is typically the full path under which the
167 package will be installed, as that must obviously be unique.
169 @item -frequire-return-statement
170 @itemx -fno-require-return-statement
171 @cindex @option{-frequire-return-statement}
172 @cindex @option{-fno-require-return-statement}
173 By default @command{gccgo} will warn about functions which have one or
174 more return parameters but lack an explicit @code{return} statement.
175 This warning may be disabled using
176 @option{-fno-require-return-statement}.
178 @item -fgo-check-divide-zero
179 @cindex @option{-fgo-check-divide-zero}
180 @cindex @option{-fno-go-check-divide-zero}
181 Add explicit checks for division by zero. In Go a division (or
182 modulos) by zero causes a panic. On Unix systems this is detected in
183 the runtime by catching the @code{SIGFPE} signal. Some processors,
184 such as PowerPC, do not generate a SIGFPE on division by zero. Some
185 runtimes do not generate a signal that can be caught. On those
186 systems, this option may be used. Or the checks may be removed via
187 @option{-fno-go-check-divide-zero}. This option is currently on by
188 default, but in the future may be off by default on systems that do
191 @item -fgo-check-divide-overflow
192 @cindex @option{-fgo-check-divide-overflow}
193 @cindex @option{-fno-go-check-divide-overflow}
194 Add explicit checks for division overflow. For example, division
195 overflow occurs when computing @code{INT_MIN / -1}. In Go this should
196 be wrapped, to produce @code{INT_MIN}. Some processors, such as x86,
197 generate a trap on division overflow. On those systems, this option
198 may be used. Or the checks may be removed via
199 @option{-fno-go-check-divide-overflow}. This option is currently on
200 by default, but in the future may be off by default on systems that do
206 @node Import and Export
207 @chapter Import and Export
209 When @command{gccgo} compiles a package which exports anything, the
210 export information will be stored directly in the object file. When a
211 package is imported, @command{gccgo} must be able to find the file.
214 When Go code imports the package @file{@var{gopackage}}, @command{gccgo}
215 will look for the import data using the following filenames, using the
216 first one that it finds.
219 @item @var{gopackage}.gox
220 @item lib@var{gopackage}.so
221 @item lib@var{gopackage}.a
222 @item @var{gopackage}.o
225 The compiler will search for these files in the directories named by
226 any @option{-I} options, in order in which the directories appear on
227 the command line. The compiler will then search several standard
228 system directories. Finally the compiler will search the current
229 directory (to search the current directory earlier, use @samp{-I.}).
231 The compiler will extract the export information directly from the
232 compiled object file. The file @file{@var{gopackage}.gox} will
233 typically contain nothing but export data. This can be generated from
234 @file{@var{gopackage}.o} via
237 objcopy -j .go_export @var{gopackage}.o @var{gopackage}.gox
240 For example, it may be desirable to extract the export information
241 from several different packages into their independent
242 @file{@var{gopackage}.gox} files, and then to combine the different
243 package object files together into a single shared library or archive.
245 At link time you must explicitly tell @command{gccgo} which files to
246 link together into the executable, as is usual with @command{gcc}.
247 This is different from the behaviour of other Go compilers.
249 @node C Interoperability
250 @chapter C Interoperability
252 When using @command{gccgo} there is limited interoperability with C,
253 or with C++ code compiled using @code{extern "C"}.
256 * C Type Interoperability:: How C and Go types match up.
257 * Function Names:: How Go functions are named.
260 @node C Type Interoperability
261 @section C Type Interoperability
263 Basic types map directly: an @code{int} in Go is an @code{int} in C,
264 etc. Go @code{byte} is equivalent to C @code{unsigned char}.
265 Pointers in Go are pointers in C. A Go @code{struct} is the same as C
266 @code{struct} with the same field names and types.
268 @cindex @code{string} in C
269 The Go @code{string} type is currently defined as a two-element
273 struct __go_string @{
274 const unsigned char *__data;
279 You can't pass arrays between C and Go. However, a pointer to an
280 array in Go is equivalent to a C pointer to the equivalent of the
281 element type. For example, Go @code{*[10]int} is equivalent to C
282 @code{int*}, assuming that the C pointer does point to 10 elements.
284 @cindex @code{slice} in C
285 A slice in Go is a structure. The current definition is:
295 The type of a Go function with no receiver is equivalent to a C
296 function whose parameter types are equivalent. When a Go function
297 returns more than one value, the C function returns a struct. For
298 example, these functions have equivalent types:
301 func GoFunction(int) (int, float)
302 struct @{ int i; float f; @} CFunction(int)
305 A pointer to a Go function is equivalent to a pointer to a C function
306 when the functions have equivalent types.
308 Go @code{interface}, @code{channel}, and @code{map} types have no
309 corresponding C type (@code{interface} is a two-element struct and
310 @code{channel} and @code{map} are pointers to structs in C, but the
311 structs are deliberately undocumented). C @code{enum} types
312 correspond to some integer type, but precisely which one is difficult
313 to predict in general; use a cast. C @code{union} types have no
314 corresponding Go type. C @code{struct} types containing bitfields
315 have no corresponding Go type. C++ @code{class} types have no
316 corresponding Go type.
318 Memory allocation is completely different between C and Go, as Go uses
319 garbage collection. The exact guidelines in this area are
320 undetermined, but it is likely that it will be permitted to pass a
321 pointer to allocated memory from C to Go. The responsibility of
322 eventually freeing the pointer will remain with C side, and of course
323 if the C side frees the pointer while the Go side still has a copy the
324 program will fail. When passing a pointer from Go to C, the Go
325 function must retain a visible copy of it in some Go variable.
326 Otherwise the Go garbage collector may delete the pointer while the C
327 function is still using it.
330 @section Function Names
332 @cindex @code{extern}
333 @cindex external names
334 Go code can call C functions directly using a Go extension implemented
335 in @command{gccgo}: a function declaration may be preceded by a
336 comment giving the external name. The comment must be at the
337 beginning of the line and must start with @code{//extern}. This must
338 be followed by a space and then the external name of the function.
339 The function declaration must be on the line immediately after the
340 comment. For example, here is how the C function @code{open} can be
345 func c_open(name *byte, mode int, perm int) int
348 The C function naturally expects a nul terminated string, which in Go
349 is equivalent to a pointer to an array (not a slice!) of @code{byte}
350 with a terminating zero byte. So a sample call from Go would look
351 like (after importing the @code{os} package):
354 var name = [4]byte@{'f', 'o', 'o', 0@};
355 i := c_open(&name[0], os.O_RDONLY, 0);
358 Note that this serves as an example only. To open a file in Go please
359 use Go's @code{os.Open} function instead.
361 The name of Go functions accessed from C is subject to change. At
362 present the name of a Go function that does not have a receiver is
363 @code{prefix.package.Functionname}. The prefix is set by the
364 @option{-fgo-prefix} option used when the package is compiled; if the
365 option is not used, the default is simply @code{go}. To call the
366 function from C you must set the name using the @command{gcc}
367 @code{__asm__} extension.
370 extern int go_function(int) __asm__ ("myprefix.mypackage.Function");