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