OSDN Git Service

PR other/46789
[pf3gnuchains/gcc-fork.git] / gcc / go / gccgo.texi
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.
15 @set copyrights-go 2010
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 * C Interoperability::          Calling C from Go and vice-vera.
92 * Index::                       Index.
93 @end menu
94
95
96 @include gpl_v3.texi
97
98 @include fdl.texi
99
100
101 @node Invoking gccgo
102 @chapter Invoking gccgo
103
104 @c man title gccgo A GCC-based compiler for the Go language
105
106 @ignore
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{}
112
113 Only the most useful options are listed here; see below for the
114 remainder.
115 @c man end
116 @c man begin SEEALSO
117 gpl(7), gfdl(7), fsf-funding(7), gcc(1)
118 and the Info entries for @file{gccgo} and @file{gcc}.
119 @c man end
120 @end ignore
121
122 @c man begin DESCRIPTION gccgo
123
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}.
128
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
131 in sequence.
132
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.
138
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
143 the link command.
144
145 @c man end
146
147 @c man begin OPTIONS gccgo
148
149 @table @gcctabopt
150 @item -I@var{dir}
151 @cindex @option{-I}
152 Specify a directory to use when searching for an import package at
153 compile time.
154
155 @item -L@var{dir}
156 @cindex @option{-L}
157 When linking, specify a library search directory, as with
158 @command{gcc}.
159
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.
168
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}.
177 @end table
178
179 @c man end
180
181 @node Import and Export
182 @chapter Import and Export
183
184 When @command{gccgo} compiles a package which exports anything, the
185 export information will be stored directly in the object file.  When a
186 package is imported, @command{gccgo} must be able to find the file.
187
188 @cindex @file{.gox}
189 When Go code imports the package @file{gopackage}, @command{gccgo}
190 will look for the import data using the following filenames, using the
191 first one that it finds.
192
193 @table @file
194 @item @var{gopackage}.gox
195 @item lib@var{gopackage}.so
196 @item lib@var{gopackage}.a
197 @item @var{gopackage}.o
198 @end table
199
200 The compiler will search for these files in the directories named by
201 any @option{-I} options, in order in which the directories appear on
202 the command line.  The compiler will then search several standard
203 system directories.  Finally the compiler will search the current
204 directory (to search the current directory earlier, use @samp{-I.}).
205
206 The compiler will extract the export information directly from the
207 compiled object file.  The file @file{@var{gopackage}.gox} will
208 typically contain nothing but export data.  This can be generated from
209 @file{@var{gopackage}.o} via
210
211 @smallexample
212 objcopy -j .go_export @var{gopackage}.o @var{gopackage}.gox
213 @end smallexample
214
215 For example, it may be desirable to extract the export information
216 from several different packages into their independent
217 @file{@var{gopackage}.gox} files, and then to combine the different
218 package object files together into a single shared library or archive.
219
220 At link time you must explicitly tell @command{gccgo} which files to
221 link together into the executable, as is usual with @command{gcc}.
222 This is different from the behaviour of other Go compilers.
223
224 @node C Interoperability
225 @chapter C Interoperability
226
227 When using @command{gccgo} there is limited interoperability with C,
228 or with C++ code compiled using @code{extern "C"}.
229
230 @menu
231 * C Type Interoperability::     How C and Go types match up.
232 * Function Names::              How Go functions are named.
233 @end menu
234
235 @node C Type Interoperability
236 @section C Type Interoperability
237
238 Basic types map directly: an @code{int} in Go is an @code{int} in C,
239 etc.  Go @code{byte} is equivalent to C @code{unsigned char}.
240 Pointers in Go are pointers in C.  A Go @code{struct} is the same as C
241 @code{struct} with the same field names and types.
242
243 @cindex @code{string} in C
244 The Go @code{string} type is currently defined as a two-element
245 structure:
246
247 @smallexample
248 struct __go_string @{
249   const unsigned char *__data;
250   int __length;
251 @};
252 @end smallexample
253
254 You can't pass arrays between C and Go.  However, a pointer to an
255 array in Go is equivalent to a C pointer to the equivalent of the
256 element type.  For example, Go @code{*[10]int} is equivalent to C
257 @code{int*}, assuming that the C pointer does point to 10 elements.
258
259 @cindex @code{slice} in C
260 A slice in Go is a structure.  The current definition is:
261
262 @smallexample
263 struct __go_slice @{
264   void *__values;
265   int __count;
266   int __capacity;
267 @};
268 @end smallexample
269
270 The type of a Go function with no receiver is equivalent to a C
271 function whose parameter types are equivalent.  When a Go function
272 returns more than one value, the C function returns a struct.  For
273 example, these functions have equivalent types:
274
275 @smallexample
276 func GoFunction(int) (int, float)
277 struct @{ int i; float f; @} CFunction(int)
278 @end smallexample
279
280 A pointer to a Go function is equivalent to a pointer to a C function
281 when the functions have equivalent types.
282
283 Go @code{interface}, @code{channel}, and @code{map} types have no
284 corresponding C type (@code{interface} is a two-element struct and
285 @code{channel} and @code{map} are pointers to structs in C, but the
286 structs are deliberately undocumented).  C @code{enum} types
287 correspond to some integer type, but precisely which one is difficult
288 to predict in general; use a cast.  C @code{union} types have no
289 corresponding Go type.  C @code{struct} types containing bitfields
290 have no corresponding Go type.  C++ @code{class} types have no
291 corresponding Go type.
292
293 Memory allocation is completely different between C and Go, as Go uses
294 garbage collection.  The exact guidelines in this area are
295 undetermined, but it is likely that it will be permitted to pass a
296 pointer to allocated memory from C to Go.  The responsibility of
297 eventually freeing the pointer will remain with C side, and of course
298 if the C side frees the pointer while the Go side still has a copy the
299 program will fail.  When passing a pointer from Go to C, the Go
300 function must retain a visible copy of it in some Go variable.
301 Otherwise the Go garbage collector may delete the pointer while the C
302 function is still using it.
303
304 @node Function Names
305 @section Function Names
306
307 @cindex @code{__asm__}
308 Go code can call C functions directly using a Go extension implemented
309 in @command{gccgo}: a function declaration may be followed by
310 @code{__asm__ ("@var{name}")}. For example, here is how the C function
311 @code{open} can be declared in Go:
312
313 @smallexample
314 func c_open(name *byte, mode int, perm int) int __asm__ ("open");
315 @end smallexample
316
317 The C function naturally expects a nul terminated string, which in Go
318 is equivalent to a pointer to an array (not a slice!) of @code{byte}
319 with a terminating zero byte.  So a sample call from Go would look
320 like (after importing the @code{os} package):
321
322 @smallexample
323 var name = [4]byte@{'f', 'o', 'o', 0@};
324 i := c_open(&name[0], os.O_RDONLY, 0);
325 @end smallexample
326
327 Note that this serves as an example only.  To open a file in Go please
328 use Go's @code{os.Open} function instead.
329
330 The name of Go functions accessed from C is subject to change.  At
331 present the name of a Go function that does not have a receiver is
332 @code{prefix.package.Functionname}.  The prefix is set by the
333 @option{-fgo-prefix} option used when the package is compiled; if the
334 option is not used, the default is simply @code{go}.  To call the
335 function from C you must set the name using the @command{gcc}
336 extension similar to the @command{gccgo} extension.
337
338 @smallexample
339 extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
340 @end smallexample
341
342 @node Index
343 @unnumbered Index
344
345 @printindex cp
346
347 @bye