Black Lives Matter. Support the Equal Justice Initiative.

Source file src/cmd/cgo/doc.go

Documentation: cmd/cgo

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

View as plain text