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