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