Source file src/cmd/cgo/doc.go

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

View as plain text