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