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