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  */