cmd/go: check for another GCC error message
[official-gcc.git] / libgo / go / cmd / cgo / doc.go
blobc1bdf0659fa0d809ddf1965d8b8d0251486395a4
1 // Copyright 2009 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
5 /*
7 Cgo enables the creation of Go packages that call C code.
9 Using cgo with the go command
11 To use cgo write normal Go code that imports a pseudo-package "C".
12 The Go code can then refer to types such as C.size_t, variables such
13 as C.stdout, or functions such as C.putchar.
15 If the import of "C" is immediately preceded by a comment, that
16 comment, called the preamble, is used as a header when compiling
17 the C parts of the package. For example:
19 // #include <stdio.h>
20 // #include <errno.h>
21 import "C"
23 The preamble may contain any C code, including function and variable
24 declarations and definitions. These may then be referred to from Go
25 code as though they were defined in the package "C". All names
26 declared in the preamble may be used, even if they start with a
27 lower-case letter. Exception: static variables in the preamble may
28 not be referenced from Go code; static functions are permitted.
30 See $GOROOT/misc/cgo/stdio and $GOROOT/misc/cgo/gmp for examples. See
31 "C? Go? Cgo!" for an introduction to using cgo:
32 https://golang.org/doc/articles/c_go_cgo.html.
34 CFLAGS, CPPFLAGS, CXXFLAGS, FFLAGS and LDFLAGS may be defined with pseudo
35 #cgo directives within these comments to tweak the behavior of the C, C++
36 or Fortran compiler. Values defined in multiple directives are concatenated
37 together. The directive can include a list of build constraints limiting its
38 effect to systems satisfying one of the constraints
39 (see https://golang.org/pkg/go/build/#hdr-Build_Constraints for details about the constraint syntax).
40 For example:
42 // #cgo CFLAGS: -DPNG_DEBUG=1
43 // #cgo amd64 386 CFLAGS: -DX86=1
44 // #cgo LDFLAGS: -lpng
45 // #include <png.h>
46 import "C"
48 Alternatively, CPPFLAGS and LDFLAGS may be obtained via the pkg-config
49 tool using a '#cgo pkg-config:' directive followed by the package names.
50 For example:
52 // #cgo pkg-config: png cairo
53 // #include <png.h>
54 import "C"
56 The default pkg-config tool may be changed by setting the PKG_CONFIG environment variable.
58 When building, the CGO_CFLAGS, CGO_CPPFLAGS, CGO_CXXFLAGS, CGO_FFLAGS and
59 CGO_LDFLAGS environment variables are added to the flags derived from
60 these directives. Package-specific flags should be set using the
61 directives, not the environment variables, so that builds work in
62 unmodified environments.
64 All the cgo CPPFLAGS and CFLAGS directives in a package are concatenated and
65 used to compile C files in that package. All the CPPFLAGS and CXXFLAGS
66 directives in a package are concatenated and used to compile C++ files in that
67 package. All the CPPFLAGS and FFLAGS directives in a package are concatenated
68 and used to compile Fortran files in that package. All the LDFLAGS directives
69 in any package in the program are concatenated and used at link time. All the
70 pkg-config directives are concatenated and sent to pkg-config simultaneously
71 to add to each appropriate set of command-line flags.
73 When the cgo directives are parsed, any occurrence of the string ${SRCDIR}
74 will be replaced by the absolute path to the directory containing the source
75 file. This allows pre-compiled static libraries to be included in the package
76 directory and linked properly.
77 For example if package foo is in the directory /go/src/foo:
79 // #cgo LDFLAGS: -L${SRCDIR}/libs -lfoo
81 Will be expanded to:
83 // #cgo LDFLAGS: -L/go/src/foo/libs -lfoo
85 When the Go tool sees that one or more Go files use the special import
86 "C", it will look for other non-Go files in the directory and compile
87 them as part of the Go package. Any .c, .s, or .S files will be
88 compiled with the C compiler. Any .cc, .cpp, or .cxx files will be
89 compiled with the C++ compiler. Any .f, .F, .for or .f90 files will be
90 compiled with the fortran compiler. Any .h, .hh, .hpp, or .hxx files will
91 not be compiled separately, but, if these header files are changed,
92 the C and C++ files will be recompiled. The default C and C++
93 compilers may be changed by the CC and CXX environment variables,
94 respectively; those environment variables may include command line
95 options.
97 The cgo tool is enabled by default for native builds on systems where
98 it is expected to work. It is disabled by default when
99 cross-compiling. You can control this by setting the CGO_ENABLED
100 environment variable when running the go tool: set it to 1 to enable
101 the use of cgo, and to 0 to disable it. The go tool will set the
102 build constraint "cgo" if cgo is enabled.
104 When cross-compiling, you must specify a C cross-compiler for cgo to
105 use. You can do this by setting the generic CC_FOR_TARGET or the
106 more specific CC_FOR_${GOOS}_${GOARCH} (for example, CC_FOR_linux_arm)
107 environment variable when building the toolchain using make.bash,
108 or you can set the CC environment variable any time you run the go tool.
110 The CXX_FOR_TARGET, CXX_FOR_${GOOS}_${GOARCH}, and CXX
111 environment variables work in a similar way for C++ code.
113 Go references to C
115 Within the Go file, C's struct field names that are keywords in Go
116 can be accessed by prefixing them with an underscore: if x points at a C
117 struct with a field named "type", x._type accesses the field.
118 C struct fields that cannot be expressed in Go, such as bit fields
119 or misaligned data, are omitted in the Go struct, replaced by
120 appropriate padding to reach the next field or the end of the struct.
122 The standard C numeric types are available under the names
123 C.char, C.schar (signed char), C.uchar (unsigned char),
124 C.short, C.ushort (unsigned short), C.int, C.uint (unsigned int),
125 C.long, C.ulong (unsigned long), C.longlong (long long),
126 C.ulonglong (unsigned long long), C.float, C.double,
127 C.complexfloat (complex float), and C.complexdouble (complex double).
128 The C type void* is represented by Go's unsafe.Pointer.
129 The C types __int128_t and __uint128_t are represented by [16]byte.
131 A few special C types which would normally be represented by a pointer
132 type in Go are instead represented by a uintptr. See the Special
133 cases section below.
135 To access a struct, union, or enum type directly, prefix it with
136 struct_, union_, or enum_, as in C.struct_stat.
138 The size of any C type T is available as C.sizeof_T, as in
139 C.sizeof_struct_stat.
141 A C function may be declared in the Go file with a parameter type of
142 the special name _GoString_. This function may be called with an
143 ordinary Go string value. The string length, and a pointer to the
144 string contents, may be accessed by calling the C functions
146 size_t _GoStringLen(_GoString_ s);
147 const char *_GoStringPtr(_GoString_ s);
149 These functions are only available in the preamble, not in other C
150 files. The C code must not modify the contents of the pointer returned
151 by _GoStringPtr. Note that the string contents may not have a trailing
152 NUL byte.
154 As Go doesn't have support for C's union type in the general case,
155 C's union types are represented as a Go byte array with the same length.
157 Go structs cannot embed fields with C types.
159 Go code cannot refer to zero-sized fields that occur at the end of
160 non-empty C structs. To get the address of such a field (which is the
161 only operation you can do with a zero-sized field) you must take the
162 address of the struct and add the size of the struct.
164 Cgo translates C types into equivalent unexported Go types.
165 Because the translations are unexported, a Go package should not
166 expose C types in its exported API: a C type used in one Go package
167 is different from the same C type used in another.
169 Any C function (even void functions) may be called in a multiple
170 assignment context to retrieve both the return value (if any) and the
171 C errno variable as an error (use _ to skip the result value if the
172 function returns void). For example:
174 n, err = C.sqrt(-1)
175 _, err := C.voidFunc()
176 var n, err = C.sqrt(1)
178 Calling C function pointers is currently not supported, however you can
179 declare Go variables which hold C function pointers and pass them
180 back and forth between Go and C. C code may call function pointers
181 received from Go. For example:
183 package main
185 // typedef int (*intFunc) ();
187 // int
188 // bridge_int_func(intFunc f)
189 // {
190 // return f();
191 // }
193 // int fortytwo()
194 // {
195 // return 42;
196 // }
197 import "C"
198 import "fmt"
200 func main() {
201 f := C.intFunc(C.fortytwo)
202 fmt.Println(int(C.bridge_int_func(f)))
203 // Output: 42
206 In C, a function argument written as a fixed size array
207 actually requires a pointer to the first element of the array.
208 C compilers are aware of this calling convention and adjust
209 the call accordingly, but Go cannot. In Go, you must pass
210 the pointer to the first element explicitly: C.f(&C.x[0]).
212 A few special functions convert between Go and C types
213 by making copies of the data. In pseudo-Go definitions:
215 // Go string to C string
216 // The C string is allocated in the C heap using malloc.
217 // It is the caller's responsibility to arrange for it to be
218 // freed, such as by calling C.free (be sure to include stdlib.h
219 // if C.free is needed).
220 func C.CString(string) *C.char
222 // Go []byte slice to C array
223 // The C array is allocated in the C heap using malloc.
224 // It is the caller's responsibility to arrange for it to be
225 // freed, such as by calling C.free (be sure to include stdlib.h
226 // if C.free is needed).
227 func C.CBytes([]byte) unsafe.Pointer
229 // C string to Go string
230 func C.GoString(*C.char) string
232 // C data with explicit length to Go string
233 func C.GoStringN(*C.char, C.int) string
235 // C data with explicit length to Go []byte
236 func C.GoBytes(unsafe.Pointer, C.int) []byte
238 As a special case, C.malloc does not call the C library malloc directly
239 but instead calls a Go helper function that wraps the C library malloc
240 but guarantees never to return nil. If C's malloc indicates out of memory,
241 the helper function crashes the program, like when Go itself runs out
242 of memory. Because C.malloc cannot fail, it has no two-result form
243 that returns errno.
245 C references to Go
247 Go functions can be exported for use by C code in the following way:
249 //export MyFunction
250 func MyFunction(arg1, arg2 int, arg3 string) int64 {...}
252 //export MyFunction2
253 func MyFunction2(arg1, arg2 int, arg3 string) (int64, *C.char) {...}
255 They will be available in the C code as:
257 extern int64 MyFunction(int arg1, int arg2, GoString arg3);
258 extern struct MyFunction2_return MyFunction2(int arg1, int arg2, GoString arg3);
260 found in the _cgo_export.h generated header, after any preambles
261 copied from the cgo input files. Functions with multiple
262 return values are mapped to functions returning a struct.
264 Not all Go types can be mapped to C types in a useful way.
265 Go struct types are not supported; use a C struct type.
266 Go array types are not supported; use a C pointer.
268 Go functions that take arguments of type string may be called with the
269 C type _GoString_, described above. The _GoString_ type will be
270 automatically defined in the preamble. Note that there is no way for C
271 code to create a value of this type; this is only useful for passing
272 string values from Go to C and back to Go.
274 Using //export in a file places a restriction on the preamble:
275 since it is copied into two different C output files, it must not
276 contain any definitions, only declarations. If a file contains both
277 definitions and declarations, then the two output files will produce
278 duplicate symbols and the linker will fail. To avoid this, definitions
279 must be placed in preambles in other files, or in C source files.
281 Passing pointers
283 Go is a garbage collected language, and the garbage collector needs to
284 know the location of every pointer to Go memory. Because of this,
285 there are restrictions on passing pointers between Go and C.
287 In this section the term Go pointer means a pointer to memory
288 allocated by Go (such as by using the & operator or calling the
289 predefined new function) and the term C pointer means a pointer to
290 memory allocated by C (such as by a call to C.malloc). Whether a
291 pointer is a Go pointer or a C pointer is a dynamic property
292 determined by how the memory was allocated; it has nothing to do with
293 the type of the pointer.
295 Note that values of some Go types, other than the type's zero value,
296 always include Go pointers. This is true of string, slice, interface,
297 channel, map, and function types. A pointer type may hold a Go pointer
298 or a C pointer. Array and struct types may or may not include Go
299 pointers, depending on the element types. All the discussion below
300 about Go pointers applies not just to pointer types, but also to other
301 types that include Go pointers.
303 Go code may pass a Go pointer to C provided the Go memory to which it
304 points does not contain any Go pointers. The C code must preserve
305 this property: it must not store any Go pointers in Go memory, even
306 temporarily. When passing a pointer to a field in a struct, the Go
307 memory in question is the memory occupied by the field, not the entire
308 struct. When passing a pointer to an element in an array or slice,
309 the Go memory in question is the entire array or the entire backing
310 array of the slice.
312 C code may not keep a copy of a Go pointer after the call returns.
313 This includes the _GoString_ type, which, as noted above, includes a
314 Go pointer; _GoString_ values may not be retained by C code.
316 A Go function called by C code may not return a Go pointer (which
317 implies that it may not return a string, slice, channel, and so
318 forth). A Go function called by C code may take C pointers as
319 arguments, and it may store non-pointer or C pointer data through
320 those pointers, but it may not store a Go pointer in memory pointed to
321 by a C pointer. A Go function called by C code may take a Go pointer
322 as an argument, but it must preserve the property that the Go memory
323 to which it points does not contain any Go pointers.
325 Go code may not store a Go pointer in C memory. C code may store Go
326 pointers in C memory, subject to the rule above: it must stop storing
327 the Go pointer when the C function returns.
329 These rules are checked dynamically at runtime. The checking is
330 controlled by the cgocheck setting of the GODEBUG environment
331 variable. The default setting is GODEBUG=cgocheck=1, which implements
332 reasonably cheap dynamic checks. These checks may be disabled
333 entirely using GODEBUG=cgocheck=0. Complete checking of pointer
334 handling, at some cost in run time, is available via GODEBUG=cgocheck=2.
336 It is possible to defeat this enforcement by using the unsafe package,
337 and of course there is nothing stopping the C code from doing anything
338 it likes. However, programs that break these rules are likely to fail
339 in unexpected and unpredictable ways.
341 Special cases
343 A few special C types which would normally be represented by a pointer
344 type in Go are instead represented by a uintptr. Those types are
345 the CF*Ref types from the CoreFoundation library on Darwin, including:
347 CFAllocatorRef
348 CFArrayRef
349 CFAttributedStringRef
350 CFBagRef
351 CFBinaryHeapRef
352 CFBitVectorRef
353 CFBooleanRef
354 CFBundleRef
355 CFCalendarRef
356 CFCharacterSetRef
357 CFDataRef
358 CFDateFormatterRef
359 CFDateRef
360 CFDictionaryRef
361 CFErrorRef
362 CFFileDescriptorRef
363 CFFileSecurityRef
364 CFLocaleRef
365 CFMachPortRef
366 CFMessagePortRef
367 CFMutableArrayRef
368 CFMutableAttributedStringRef
369 CFMutableBagRef
370 CFMutableBitVectorRef
371 CFMutableCharacterSetRef
372 CFMutableDataRef
373 CFMutableDictionaryRef
374 CFMutableSetRef
375 CFMutableStringRef
376 CFNotificationCenterRef
377 CFNullRef
378 CFNumberFormatterRef
379 CFNumberRef
380 CFPlugInInstanceRef
381 CFPlugInRef
382 CFPropertyListRef
383 CFReadStreamRef
384 CFRunLoopObserverRef
385 CFRunLoopRef
386 CFRunLoopSourceRef
387 CFRunLoopTimerRef
388 CFSetRef
389 CFSocketRef
390 CFStringRef
391 CFStringTokenizerRef
392 CFTimeZoneRef
393 CFTreeRef
394 CFTypeRef
395 CFURLCreateFromFSRef
396 CFURLEnumeratorRef
397 CFURLGetFSRef
398 CFURLRef
399 CFUUIDRef
400 CFUserNotificationRef
401 CFWriteStreamRef
402 CFXMLNodeRef
403 CFXMLParserRef
404 CFXMLTreeRef
406 These types are uintptr on the Go side because they would otherwise
407 confuse the Go garbage collector; they are sometimes not really
408 pointers but data structures encoded in a pointer type. All operations
409 on these types must happen in C. The proper constant to initialize an
410 empty such reference is 0, not nil.
412 This special case was introduced in Go 1.10. For auto-updating code
413 from Go 1.9 and earlier, use the cftype rewrite in the Go fix tool:
415 go tool fix -r cftype <pkg>
417 It will replace nil with 0 in the appropriate places.
419 Using cgo directly
421 Usage:
422 go tool cgo [cgo options] [-- compiler options] gofiles...
424 Cgo transforms the specified input Go source files into several output
425 Go and C source files.
427 The compiler options are passed through uninterpreted when
428 invoking the C compiler to compile the C parts of the package.
430 The following options are available when running cgo directly:
433 Print cgo version and exit.
434 -debug-define
435 Debugging option. Print #defines.
436 -debug-gcc
437 Debugging option. Trace C compiler execution and output.
438 -dynimport file
439 Write list of symbols imported by file. Write to
440 -dynout argument or to standard output. Used by go
441 build when building a cgo package.
442 -dynlinker
443 Write dynamic linker as part of -dynimport output.
444 -dynout file
445 Write -dynimport output to file.
446 -dynpackage package
447 Set Go package for -dynimport output.
448 -exportheader file
449 If there are any exported functions, write the
450 generated export declarations to file.
451 C code can #include this to see the declarations.
452 -importpath string
453 The import path for the Go package. Optional; used for
454 nicer comments in the generated files.
455 -import_runtime_cgo
456 If set (which it is by default) import runtime/cgo in
457 generated output.
458 -import_syscall
459 If set (which it is by default) import syscall in
460 generated output.
461 -gccgo
462 Generate output for the gccgo compiler rather than the
463 gc compiler.
464 -gccgoprefix prefix
465 The -fgo-prefix option to be used with gccgo.
466 -gccgopkgpath path
467 The -fgo-pkgpath option to be used with gccgo.
468 -godefs
469 Write out input file in Go syntax replacing C package
470 names with real values. Used to generate files in the
471 syscall package when bootstrapping a new target.
472 -objdir directory
473 Put all generated files in directory.
474 -srcdir directory
476 package main
479 Implementation details.
481 Cgo provides a way for Go programs to call C code linked into the same
482 address space. This comment explains the operation of cgo.
484 Cgo reads a set of Go source files and looks for statements saying
485 import "C". If the import has a doc comment, that comment is
486 taken as literal C code to be used as a preamble to any C code
487 generated by cgo. A typical preamble #includes necessary definitions:
489 // #include <stdio.h>
490 import "C"
492 For more details about the usage of cgo, see the documentation
493 comment at the top of this file.
495 Understanding C
497 Cgo scans the Go source files that import "C" for uses of that
498 package, such as C.puts. It collects all such identifiers. The next
499 step is to determine each kind of name. In C.xxx the xxx might refer
500 to a type, a function, a constant, or a global variable. Cgo must
501 decide which.
503 The obvious thing for cgo to do is to process the preamble, expanding
504 #includes and processing the corresponding C code. That would require
505 a full C parser and type checker that was also aware of any extensions
506 known to the system compiler (for example, all the GNU C extensions) as
507 well as the system-specific header locations and system-specific
508 pre-#defined macros. This is certainly possible to do, but it is an
509 enormous amount of work.
511 Cgo takes a different approach. It determines the meaning of C
512 identifiers not by parsing C code but by feeding carefully constructed
513 programs into the system C compiler and interpreting the generated
514 error messages, debug information, and object files. In practice,
515 parsing these is significantly less work and more robust than parsing
516 C source.
518 Cgo first invokes gcc -E -dM on the preamble, in order to find out
519 about simple #defines for constants and the like. These are recorded
520 for later use.
522 Next, cgo needs to identify the kinds for each identifier. For the
523 identifiers C.foo, cgo generates this C program:
525 <preamble>
526 #line 1 "not-declared"
527 void __cgo_f_1_1(void) { __typeof__(foo) *__cgo_undefined__1; }
528 #line 1 "not-type"
529 void __cgo_f_1_2(void) { foo *__cgo_undefined__2; }
530 #line 1 "not-int-const"
531 void __cgo_f_1_3(void) { enum { __cgo_undefined__3 = (foo)*1 }; }
532 #line 1 "not-num-const"
533 void __cgo_f_1_4(void) { static const double __cgo_undefined__4 = (foo); }
534 #line 1 "not-str-lit"
535 void __cgo_f_1_5(void) { static const char __cgo_undefined__5[] = (foo); }
537 This program will not compile, but cgo can use the presence or absence
538 of an error message on a given line to deduce the information it
539 needs. The program is syntactically valid regardless of whether each
540 name is a type or an ordinary identifier, so there will be no syntax
541 errors that might stop parsing early.
543 An error on not-declared:1 indicates that foo is undeclared.
544 An error on not-type:1 indicates that foo is not a type (if declared at all, it is an identifier).
545 An error on not-int-const:1 indicates that foo is not an integer constant.
546 An error on not-num-const:1 indicates that foo is not a number constant.
547 An error on not-str-lit:1 indicates that foo is not a string literal.
548 An error on not-signed-int-const:1 indicates that foo is not a signed integer constant.
550 The line number specifies the name involved. In the example, 1 is foo.
552 Next, cgo must learn the details of each type, variable, function, or
553 constant. It can do this by reading object files. If cgo has decided
554 that t1 is a type, v2 and v3 are variables or functions, and i4, i5
555 are integer constants, u6 is an unsigned integer constant, and f7 and f8
556 are float constants, and s9 and s10 are string constants, it generates:
558 <preamble>
559 __typeof__(t1) *__cgo__1;
560 __typeof__(v2) *__cgo__2;
561 __typeof__(v3) *__cgo__3;
562 __typeof__(i4) *__cgo__4;
563 enum { __cgo_enum__4 = i4 };
564 __typeof__(i5) *__cgo__5;
565 enum { __cgo_enum__5 = i5 };
566 __typeof__(u6) *__cgo__6;
567 enum { __cgo_enum__6 = u6 };
568 __typeof__(f7) *__cgo__7;
569 __typeof__(f8) *__cgo__8;
570 __typeof__(s9) *__cgo__9;
571 __typeof__(s10) *__cgo__10;
573 long long __cgodebug_ints[] = {
574 0, // t1
575 0, // v2
576 0, // v3
580 0, // f7
581 0, // f8
582 0, // s9
583 0, // s10
587 double __cgodebug_floats[] = {
588 0, // t1
589 0, // v2
590 0, // v3
591 0, // i4
592 0, // i5
593 0, // u6
596 0, // s9
597 0, // s10
601 const char __cgodebug_str__9[] = s9;
602 const unsigned long long __cgodebug_strlen__9 = sizeof(s9)-1;
603 const char __cgodebug_str__10[] = s10;
604 const unsigned long long __cgodebug_strlen__10 = sizeof(s10)-1;
606 and again invokes the system C compiler, to produce an object file
607 containing debug information. Cgo parses the DWARF debug information
608 for __cgo__N to learn the type of each identifier. (The types also
609 distinguish functions from global variables.) Cgo reads the constant
610 values from the __cgodebug_* from the object file's data segment.
612 At this point cgo knows the meaning of each C.xxx well enough to start
613 the translation process.
615 Translating Go
617 Given the input Go files x.go and y.go, cgo generates these source
618 files:
620 x.cgo1.go # for gc (cmd/compile)
621 y.cgo1.go # for gc
622 _cgo_gotypes.go # for gc
623 _cgo_import.go # for gc (if -dynout _cgo_import.go)
624 x.cgo2.c # for gcc
625 y.cgo2.c # for gcc
626 _cgo_defun.c # for gcc (if -gccgo)
627 _cgo_export.c # for gcc
628 _cgo_export.h # for gcc
629 _cgo_main.c # for gcc
630 _cgo_flags # for alternative build tools
632 The file x.cgo1.go is a copy of x.go with the import "C" removed and
633 references to C.xxx replaced with names like _Cfunc_xxx or _Ctype_xxx.
634 The definitions of those identifiers, written as Go functions, types,
635 or variables, are provided in _cgo_gotypes.go.
637 Here is a _cgo_gotypes.go containing definitions for needed C types:
639 type _Ctype_char int8
640 type _Ctype_int int32
641 type _Ctype_void [0]byte
643 The _cgo_gotypes.go file also contains the definitions of the
644 functions. They all have similar bodies that invoke runtime·cgocall
645 to make a switch from the Go runtime world to the system C (GCC-based)
646 world.
648 For example, here is the definition of _Cfunc_puts:
650 //go:cgo_import_static _cgo_be59f0f25121_Cfunc_puts
651 //go:linkname __cgofn__cgo_be59f0f25121_Cfunc_puts _cgo_be59f0f25121_Cfunc_puts
652 var __cgofn__cgo_be59f0f25121_Cfunc_puts byte
653 var _cgo_be59f0f25121_Cfunc_puts = unsafe.Pointer(&__cgofn__cgo_be59f0f25121_Cfunc_puts)
655 func _Cfunc_puts(p0 *_Ctype_char) (r1 _Ctype_int) {
656 _cgo_runtime_cgocall(_cgo_be59f0f25121_Cfunc_puts, uintptr(unsafe.Pointer(&p0)))
657 return
660 The hexadecimal number is a hash of cgo's input, chosen to be
661 deterministic yet unlikely to collide with other uses. The actual
662 function _cgo_be59f0f25121_Cfunc_puts is implemented in a C source
663 file compiled by gcc, the file x.cgo2.c:
665 void
666 _cgo_be59f0f25121_Cfunc_puts(void *v)
668 struct {
669 char* p0;
670 int r;
671 char __pad12[4];
672 } __attribute__((__packed__, __gcc_struct__)) *a = v;
673 a->r = puts((void*)a->p0);
676 It extracts the arguments from the pointer to _Cfunc_puts's argument
677 frame, invokes the system C function (in this case, puts), stores the
678 result in the frame, and returns.
680 Linking
682 Once the _cgo_export.c and *.cgo2.c files have been compiled with gcc,
683 they need to be linked into the final binary, along with the libraries
684 they might depend on (in the case of puts, stdio). cmd/link has been
685 extended to understand basic ELF files, but it does not understand ELF
686 in the full complexity that modern C libraries embrace, so it cannot
687 in general generate direct references to the system libraries.
689 Instead, the build process generates an object file using dynamic
690 linkage to the desired libraries. The main function is provided by
691 _cgo_main.c:
693 int main() { return 0; }
694 void crosscall2(void(*fn)(void*, int, uintptr_t), void *a, int c, uintptr_t ctxt) { }
695 uintptr_t _cgo_wait_runtime_init_done() { return 0; }
696 void _cgo_release_context(uintptr_t ctxt) { }
697 char* _cgo_topofstack(void) { return (char*)0; }
698 void _cgo_allocate(void *a, int c) { }
699 void _cgo_panic(void *a, int c) { }
700 void _cgo_reginit(void) { }
702 The extra functions here are stubs to satisfy the references in the C
703 code generated for gcc. The build process links this stub, along with
704 _cgo_export.c and *.cgo2.c, into a dynamic executable and then lets
705 cgo examine the executable. Cgo records the list of shared library
706 references and resolved names and writes them into a new file
707 _cgo_import.go, which looks like:
709 //go:cgo_dynamic_linker "/lib64/ld-linux-x86-64.so.2"
710 //go:cgo_import_dynamic puts puts#GLIBC_2.2.5 "libc.so.6"
711 //go:cgo_import_dynamic __libc_start_main __libc_start_main#GLIBC_2.2.5 "libc.so.6"
712 //go:cgo_import_dynamic stdout stdout#GLIBC_2.2.5 "libc.so.6"
713 //go:cgo_import_dynamic fflush fflush#GLIBC_2.2.5 "libc.so.6"
714 //go:cgo_import_dynamic _ _ "libpthread.so.0"
715 //go:cgo_import_dynamic _ _ "libc.so.6"
717 In the end, the compiled Go package, which will eventually be
718 presented to cmd/link as part of a larger program, contains:
720 _go_.o # gc-compiled object for _cgo_gotypes.go, _cgo_import.go, *.cgo1.go
721 _all.o # gcc-compiled object for _cgo_export.c, *.cgo2.c
723 The final program will be a dynamic executable, so that cmd/link can avoid
724 needing to process arbitrary .o files. It only needs to process the .o
725 files generated from C files that cgo writes, and those are much more
726 limited in the ELF or other features that they use.
728 In essence, the _cgo_import.o file includes the extra linking
729 directives that cmd/link is not sophisticated enough to derive from _all.o
730 on its own. Similarly, the _all.o uses dynamic references to real
731 system object code because cmd/link is not sophisticated enough to process
732 the real code.
734 The main benefits of this system are that cmd/link remains relatively simple
735 (it does not need to implement a complete ELF and Mach-O linker) and
736 that gcc is not needed after the package is compiled. For example,
737 package net uses cgo for access to name resolution functions provided
738 by libc. Although gcc is needed to compile package net, gcc is not
739 needed to link programs that import package net.
741 Runtime
743 When using cgo, Go must not assume that it owns all details of the
744 process. In particular it needs to coordinate with C in the use of
745 threads and thread-local storage. The runtime package declares a few
746 variables:
748 var (
749 iscgo bool
750 _cgo_init unsafe.Pointer
751 _cgo_thread_start unsafe.Pointer
754 Any package using cgo imports "runtime/cgo", which provides
755 initializations for these variables. It sets iscgo to true, _cgo_init
756 to a gcc-compiled function that can be called early during program
757 startup, and _cgo_thread_start to a gcc-compiled function that can be
758 used to create a new thread, in place of the runtime's usual direct
759 system calls.
761 Internal and External Linking
763 The text above describes "internal" linking, in which cmd/link parses and
764 links host object files (ELF, Mach-O, PE, and so on) into the final
765 executable itself. Keeping cmd/link simple means we cannot possibly
766 implement the full semantics of the host linker, so the kinds of
767 objects that can be linked directly into the binary is limited (other
768 code can only be used as a dynamic library). On the other hand, when
769 using internal linking, cmd/link can generate Go binaries by itself.
771 In order to allow linking arbitrary object files without requiring
772 dynamic libraries, cgo supports an "external" linking mode too. In
773 external linking mode, cmd/link does not process any host object files.
774 Instead, it collects all the Go code and writes a single go.o object
775 file containing it. Then it invokes the host linker (usually gcc) to
776 combine the go.o object file and any supporting non-Go code into a
777 final executable. External linking avoids the dynamic library
778 requirement but introduces a requirement that the host linker be
779 present to create such a binary.
781 Most builds both compile source code and invoke the linker to create a
782 binary. When cgo is involved, the compile step already requires gcc, so
783 it is not problematic for the link step to require gcc too.
785 An important exception is builds using a pre-compiled copy of the
786 standard library. In particular, package net uses cgo on most systems,
787 and we want to preserve the ability to compile pure Go code that
788 imports net without requiring gcc to be present at link time. (In this
789 case, the dynamic library requirement is less significant, because the
790 only library involved is libc.so, which can usually be assumed
791 present.)
793 This conflict between functionality and the gcc requirement means we
794 must support both internal and external linking, depending on the
795 circumstances: if net is the only cgo-using package, then internal
796 linking is probably fine, but if other packages are involved, so that there
797 are dependencies on libraries beyond libc, external linking is likely
798 to work better. The compilation of a package records the relevant
799 information to support both linking modes, leaving the decision
800 to be made when linking the final binary.
802 Linking Directives
804 In either linking mode, package-specific directives must be passed
805 through to cmd/link. These are communicated by writing //go: directives in a
806 Go source file compiled by gc. The directives are copied into the .o
807 object file and then processed by the linker.
809 The directives are:
811 //go:cgo_import_dynamic <local> [<remote> ["<library>"]]
813 In internal linking mode, allow an unresolved reference to
814 <local>, assuming it will be resolved by a dynamic library
815 symbol. The optional <remote> specifies the symbol's name and
816 possibly version in the dynamic library, and the optional "<library>"
817 names the specific library where the symbol should be found.
819 In the <remote>, # or @ can be used to introduce a symbol version.
821 Examples:
822 //go:cgo_import_dynamic puts
823 //go:cgo_import_dynamic puts puts#GLIBC_2.2.5
824 //go:cgo_import_dynamic puts puts#GLIBC_2.2.5 "libc.so.6"
826 A side effect of the cgo_import_dynamic directive with a
827 library is to make the final binary depend on that dynamic
828 library. To get the dependency without importing any specific
829 symbols, use _ for local and remote.
831 Example:
832 //go:cgo_import_dynamic _ _ "libc.so.6"
834 For compatibility with current versions of SWIG,
835 #pragma dynimport is an alias for //go:cgo_import_dynamic.
837 //go:cgo_dynamic_linker "<path>"
839 In internal linking mode, use "<path>" as the dynamic linker
840 in the final binary. This directive is only needed from one
841 package when constructing a binary; by convention it is
842 supplied by runtime/cgo.
844 Example:
845 //go:cgo_dynamic_linker "/lib/ld-linux.so.2"
847 //go:cgo_export_dynamic <local> <remote>
849 In internal linking mode, put the Go symbol
850 named <local> into the program's exported symbol table as
851 <remote>, so that C code can refer to it by that name. This
852 mechanism makes it possible for C code to call back into Go or
853 to share Go's data.
855 For compatibility with current versions of SWIG,
856 #pragma dynexport is an alias for //go:cgo_export_dynamic.
858 //go:cgo_import_static <local>
860 In external linking mode, allow unresolved references to
861 <local> in the go.o object file prepared for the host linker,
862 under the assumption that <local> will be supplied by the
863 other object files that will be linked with go.o.
865 Example:
866 //go:cgo_import_static puts_wrapper
868 //go:cgo_export_static <local> <remote>
870 In external linking mode, put the Go symbol
871 named <local> into the program's exported symbol table as
872 <remote>, so that C code can refer to it by that name. This
873 mechanism makes it possible for C code to call back into Go or
874 to share Go's data.
876 //go:cgo_ldflag "<arg>"
878 In external linking mode, invoke the host linker (usually gcc)
879 with "<arg>" as a command-line argument following the .o files.
880 Note that the arguments are for "gcc", not "ld".
882 Example:
883 //go:cgo_ldflag "-lpthread"
884 //go:cgo_ldflag "-L/usr/local/sqlite3/lib"
886 A package compiled with cgo will include directives for both
887 internal and external linking; the linker will select the appropriate
888 subset for the chosen linking mode.
890 Example
892 As a simple example, consider a package that uses cgo to call C.sin.
893 The following code will be generated by cgo:
895 // compiled by gc
897 //go:cgo_ldflag "-lm"
899 type _Ctype_double float64
901 //go:cgo_import_static _cgo_gcc_Cfunc_sin
902 //go:linkname __cgo_gcc_Cfunc_sin _cgo_gcc_Cfunc_sin
903 var __cgo_gcc_Cfunc_sin byte
904 var _cgo_gcc_Cfunc_sin = unsafe.Pointer(&__cgo_gcc_Cfunc_sin)
906 func _Cfunc_sin(p0 _Ctype_double) (r1 _Ctype_double) {
907 _cgo_runtime_cgocall(_cgo_gcc_Cfunc_sin, uintptr(unsafe.Pointer(&p0)))
908 return
911 // compiled by gcc, into foo.cgo2.o
913 void
914 _cgo_gcc_Cfunc_sin(void *v)
916 struct {
917 double p0;
918 double r;
919 } __attribute__((__packed__)) *a = v;
920 a->r = sin(a->p0);
923 What happens at link time depends on whether the final binary is linked
924 using the internal or external mode. If other packages are compiled in
925 "external only" mode, then the final link will be an external one.
926 Otherwise the link will be an internal one.
928 The linking directives are used according to the kind of final link
929 used.
931 In internal mode, cmd/link itself processes all the host object files, in
932 particular foo.cgo2.o. To do so, it uses the cgo_import_dynamic and
933 cgo_dynamic_linker directives to learn that the otherwise undefined
934 reference to sin in foo.cgo2.o should be rewritten to refer to the
935 symbol sin with version GLIBC_2.2.5 from the dynamic library
936 "libm.so.6", and the binary should request "/lib/ld-linux.so.2" as its
937 runtime dynamic linker.
939 In external mode, cmd/link does not process any host object files, in
940 particular foo.cgo2.o. It links together the gc-generated object
941 files, along with any other Go code, into a go.o file. While doing
942 that, cmd/link will discover that there is no definition for
943 _cgo_gcc_Cfunc_sin, referred to by the gc-compiled source file. This
944 is okay, because cmd/link also processes the cgo_import_static directive and
945 knows that _cgo_gcc_Cfunc_sin is expected to be supplied by a host
946 object file, so cmd/link does not treat the missing symbol as an error when
947 creating go.o. Indeed, the definition for _cgo_gcc_Cfunc_sin will be
948 provided to the host linker by foo2.cgo.o, which in turn will need the
949 symbol 'sin'. cmd/link also processes the cgo_ldflag directives, so that it
950 knows that the eventual host link command must include the -lm
951 argument, so that the host linker will be able to find 'sin' in the
952 math library.
954 cmd/link Command Line Interface
956 The go command and any other Go-aware build systems invoke cmd/link
957 to link a collection of packages into a single binary. By default, cmd/link will
958 present the same interface it does today:
960 cmd/link main.a
962 produces a file named a.out, even if cmd/link does so by invoking the host
963 linker in external linking mode.
965 By default, cmd/link will decide the linking mode as follows: if the only
966 packages using cgo are those on a whitelist of standard library
967 packages (net, os/user, runtime/cgo), cmd/link will use internal linking
968 mode. Otherwise, there are non-standard cgo packages involved, and cmd/link
969 will use external linking mode. The first rule means that a build of
970 the godoc binary, which uses net but no other cgo, can run without
971 needing gcc available. The second rule means that a build of a
972 cgo-wrapped library like sqlite3 can generate a standalone executable
973 instead of needing to refer to a dynamic library. The specific choice
974 can be overridden using a command line flag: cmd/link -linkmode=internal or
975 cmd/link -linkmode=external.
977 In an external link, cmd/link will create a temporary directory, write any
978 host object files found in package archives to that directory (renamed
979 to avoid conflicts), write the go.o file to that directory, and invoke
980 the host linker. The default value for the host linker is $CC, split
981 into fields, or else "gcc". The specific host linker command line can
982 be overridden using command line flags: cmd/link -extld=clang
983 -extldflags='-ggdb -O3'. If any package in a build includes a .cc or
984 other file compiled by the C++ compiler, the go tool will use the
985 -extld option to set the host linker to the C++ compiler.
987 These defaults mean that Go-aware build systems can ignore the linking
988 changes and keep running plain 'cmd/link' and get reasonable results, but
989 they can also control the linking details if desired.