Retro68/gcc/libgo/go/cmd/cgo/doc.go

847 lines
33 KiB
Go
Raw Normal View History

// Copyright 2009 The Go Authors. All rights reserved.
2015-08-28 15:33:40 +00:00
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
/*
Cgo enables the creation of Go packages that call C code.
Using cgo with the go command
To use cgo write normal Go code that imports a pseudo-package "C".
The Go code can then refer to types such as C.size_t, variables such
as C.stdout, or functions such as C.putchar.
If the import of "C" is immediately preceded by a comment, that
comment, called the preamble, is used as a header when compiling
the C parts of the package. For example:
// #include <stdio.h>
// #include <errno.h>
import "C"
2017-04-10 11:32:00 +00:00
The preamble may contain any C code, including function and variable
declarations and definitions. These may then be referred to from Go
code as though they were defined in the package "C". All names
declared in the preamble may be used, even if they start with a
lower-case letter. Exception: static variables in the preamble may
not be referenced from Go code; static functions are permitted.
2015-08-28 15:33:40 +00:00
See $GOROOT/misc/cgo/stdio and $GOROOT/misc/cgo/gmp for examples. See
"C? Go? Cgo!" for an introduction to using cgo:
2017-04-10 11:32:00 +00:00
https://golang.org/doc/articles/c_go_cgo.html.
2015-08-28 15:33:40 +00:00
CFLAGS, CPPFLAGS, CXXFLAGS, FFLAGS and LDFLAGS may be defined with pseudo
#cgo directives within these comments to tweak the behavior of the C, C++
or Fortran compiler. Values defined in multiple directives are concatenated
2015-08-28 15:33:40 +00:00
together. The directive can include a list of build constraints limiting its
effect to systems satisfying one of the constraints
2017-04-10 11:32:00 +00:00
(see https://golang.org/pkg/go/build/#hdr-Build_Constraints for details about the constraint syntax).
2015-08-28 15:33:40 +00:00
For example:
// #cgo CFLAGS: -DPNG_DEBUG=1
// #cgo amd64 386 CFLAGS: -DX86=1
// #cgo LDFLAGS: -lpng
// #include <png.h>
import "C"
Alternatively, CPPFLAGS and LDFLAGS may be obtained via the pkg-config
tool using a '#cgo pkg-config:' directive followed by the package names.
For example:
// #cgo pkg-config: png cairo
// #include <png.h>
import "C"
The default pkg-config tool may be changed by setting the PKG_CONFIG environment variable.
When building, the CGO_CFLAGS, CGO_CPPFLAGS, CGO_CXXFLAGS, CGO_FFLAGS and
2015-08-28 15:33:40 +00:00
CGO_LDFLAGS environment variables are added to the flags derived from
these directives. Package-specific flags should be set using the
directives, not the environment variables, so that builds work in
unmodified environments.
All the cgo CPPFLAGS and CFLAGS directives in a package are concatenated and
used to compile C files in that package. All the CPPFLAGS and CXXFLAGS
directives in a package are concatenated and used to compile C++ files in that
package. All the CPPFLAGS and FFLAGS directives in a package are concatenated
and used to compile Fortran files in that package. All the LDFLAGS directives
in any package in the program are concatenated and used at link time. All the
pkg-config directives are concatenated and sent to pkg-config simultaneously
to add to each appropriate set of command-line flags.
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
When the cgo directives are parsed, any occurrence of the string ${SRCDIR}
will be replaced by the absolute path to the directory containing the source
file. This allows pre-compiled static libraries to be included in the package
directory and linked properly.
For example if package foo is in the directory /go/src/foo:
// #cgo LDFLAGS: -L${SRCDIR}/libs -lfoo
Will be expanded to:
// #cgo LDFLAGS: -L/go/src/foo/libs -lfoo
2015-08-28 15:33:40 +00:00
When the Go tool sees that one or more Go files use the special import
"C", it will look for other non-Go files in the directory and compile
them as part of the Go package. Any .c, .s, or .S files will be
compiled with the C compiler. Any .cc, .cpp, or .cxx files will be
compiled with the C++ compiler. Any .f, .F, .for or .f90 files will be
compiled with the fortran compiler. Any .h, .hh, .hpp, or .hxx files will
2015-08-28 15:33:40 +00:00
not be compiled separately, but, if these header files are changed,
the C and C++ files will be recompiled. The default C and C++
compilers may be changed by the CC and CXX environment variables,
respectively; those environment variables may include command line
options.
2017-04-10 11:32:00 +00:00
The cgo tool is enabled by default for native builds on systems where
it is expected to work. It is disabled by default when
cross-compiling. You can control this by setting the CGO_ENABLED
environment variable when running the go tool: set it to 1 to enable
the use of cgo, and to 0 to disable it. The go tool will set the
build constraint "cgo" if cgo is enabled.
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
When cross-compiling, you must specify a C cross-compiler for cgo to
use. You can do this by setting the CC_FOR_TARGET environment
variable when building the toolchain using make.bash, or by setting
the CC environment variable any time you run the go tool. The
CXX_FOR_TARGET and CXX environment variables work in a similar way for
C++ code.
2015-08-28 15:33:40 +00:00
Go references to C
Within the Go file, C's struct field names that are keywords in Go
can be accessed by prefixing them with an underscore: if x points at a C
struct with a field named "type", x._type accesses the field.
C struct fields that cannot be expressed in Go, such as bit fields
or misaligned data, are omitted in the Go struct, replaced by
appropriate padding to reach the next field or the end of the struct.
The standard C numeric types are available under the names
C.char, C.schar (signed char), C.uchar (unsigned char),
C.short, C.ushort (unsigned short), C.int, C.uint (unsigned int),
C.long, C.ulong (unsigned long), C.longlong (long long),
2017-04-10 11:32:00 +00:00
C.ulonglong (unsigned long long), C.float, C.double,
C.complexfloat (complex float), and C.complexdouble (complex double).
2015-08-28 15:33:40 +00:00
The C type void* is represented by Go's unsafe.Pointer.
2017-04-10 11:32:00 +00:00
The C types __int128_t and __uint128_t are represented by [16]byte.
2015-08-28 15:33:40 +00:00
To access a struct, union, or enum type directly, prefix it with
struct_, union_, or enum_, as in C.struct_stat.
2017-04-10 11:32:00 +00:00
The size of any C type T is available as C.sizeof_T, as in
C.sizeof_struct_stat.
2015-08-28 15:33:40 +00:00
As Go doesn't have support for C's union type in the general case,
C's union types are represented as a Go byte array with the same length.
Go structs cannot embed fields with C types.
Go code cannot refer to zero-sized fields that occur at the end of
2017-04-10 11:32:00 +00:00
non-empty C structs. To get the address of such a field (which is the
only operation you can do with a zero-sized field) you must take the
address of the struct and add the size of the struct.
2015-08-28 15:33:40 +00:00
Cgo translates C types into equivalent unexported Go types.
Because the translations are unexported, a Go package should not
expose C types in its exported API: a C type used in one Go package
is different from the same C type used in another.
Any C function (even void functions) may be called in a multiple
assignment context to retrieve both the return value (if any) and the
C errno variable as an error (use _ to skip the result value if the
function returns void). For example:
n, err = C.sqrt(-1)
2015-08-28 15:33:40 +00:00
_, err := C.voidFunc()
var n, err = C.sqrt(1)
2015-08-28 15:33:40 +00:00
Calling C function pointers is currently not supported, however you can
declare Go variables which hold C function pointers and pass them
back and forth between Go and C. C code may call function pointers
received from Go. For example:
package main
// typedef int (*intFunc) ();
//
// int
// bridge_int_func(intFunc f)
// {
// return f();
// }
//
// int fortytwo()
// {
// return 42;
// }
import "C"
import "fmt"
func main() {
f := C.intFunc(C.fortytwo)
fmt.Println(int(C.bridge_int_func(f)))
// Output: 42
}
In C, a function argument written as a fixed size array
actually requires a pointer to the first element of the array.
C compilers are aware of this calling convention and adjust
the call accordingly, but Go cannot. In Go, you must pass
the pointer to the first element explicitly: C.f(&C.x[0]).
A few special functions convert between Go and C types
by making copies of the data. In pseudo-Go definitions:
// Go string to C string
// The C string is allocated in the C heap using malloc.
// It is the caller's responsibility to arrange for it to be
// freed, such as by calling C.free (be sure to include stdlib.h
// if C.free is needed).
func C.CString(string) *C.char
// Go []byte slice to C array
// The C array is allocated in the C heap using malloc.
// It is the caller's responsibility to arrange for it to be
// freed, such as by calling C.free (be sure to include stdlib.h
// if C.free is needed).
func C.CBytes([]byte) unsafe.Pointer
2015-08-28 15:33:40 +00:00
// C string to Go string
func C.GoString(*C.char) string
2017-04-10 11:32:00 +00:00
// C data with explicit length to Go string
2015-08-28 15:33:40 +00:00
func C.GoStringN(*C.char, C.int) string
2017-04-10 11:32:00 +00:00
// C data with explicit length to Go []byte
2015-08-28 15:33:40 +00:00
func C.GoBytes(unsafe.Pointer, C.int) []byte
As a special case, C.malloc does not call the C library malloc directly
but instead calls a Go helper function that wraps the C library malloc
but guarantees never to return nil. If C's malloc indicates out of memory,
the helper function crashes the program, like when Go itself runs out
of memory. Because C.malloc cannot fail, it has no two-result form
that returns errno.
2015-08-28 15:33:40 +00:00
C references to Go
Go functions can be exported for use by C code in the following way:
//export MyFunction
func MyFunction(arg1, arg2 int, arg3 string) int64 {...}
//export MyFunction2
func MyFunction2(arg1, arg2 int, arg3 string) (int64, *C.char) {...}
They will be available in the C code as:
extern int64 MyFunction(int arg1, int arg2, GoString arg3);
extern struct MyFunction2_return MyFunction2(int arg1, int arg2, GoString arg3);
found in the _cgo_export.h generated header, after any preambles
copied from the cgo input files. Functions with multiple
return values are mapped to functions returning a struct.
Not all Go types can be mapped to C types in a useful way.
Using //export in a file places a restriction on the preamble:
since it is copied into two different C output files, it must not
2017-04-10 11:32:00 +00:00
contain any definitions, only declarations. If a file contains both
definitions and declarations, then the two output files will produce
duplicate symbols and the linker will fail. To avoid this, definitions
must be placed in preambles in other files, or in C source files.
Passing pointers
Go is a garbage collected language, and the garbage collector needs to
know the location of every pointer to Go memory. Because of this,
there are restrictions on passing pointers between Go and C.
In this section the term Go pointer means a pointer to memory
allocated by Go (such as by using the & operator or calling the
predefined new function) and the term C pointer means a pointer to
memory allocated by C (such as by a call to C.malloc). Whether a
pointer is a Go pointer or a C pointer is a dynamic property
determined by how the memory was allocated; it has nothing to do with
the type of the pointer.
Go code may pass a Go pointer to C provided the Go memory to which it
points does not contain any Go pointers. The C code must preserve
this property: it must not store any Go pointers in Go memory, even
temporarily. When passing a pointer to a field in a struct, the Go
memory in question is the memory occupied by the field, not the entire
struct. When passing a pointer to an element in an array or slice,
the Go memory in question is the entire array or the entire backing
array of the slice.
C code may not keep a copy of a Go pointer after the call returns.
A Go function called by C code may not return a Go pointer. A Go
function called by C code may take C pointers as arguments, and it may
store non-pointer or C pointer data through those pointers, but it may
not store a Go pointer in memory pointed to by a C pointer. A Go
function called by C code may take a Go pointer as an argument, but it
must preserve the property that the Go memory to which it points does
not contain any Go pointers.
Go code may not store a Go pointer in C memory. C code may store Go
pointers in C memory, subject to the rule above: it must stop storing
the Go pointer when the C function returns.
These rules are checked dynamically at runtime. The checking is
controlled by the cgocheck setting of the GODEBUG environment
variable. The default setting is GODEBUG=cgocheck=1, which implements
reasonably cheap dynamic checks. These checks may be disabled
entirely using GODEBUG=cgocheck=0. Complete checking of pointer
handling, at some cost in run time, is available via GODEBUG=cgocheck=2.
It is possible to defeat this enforcement by using the unsafe package,
and of course there is nothing stopping the C code from doing anything
it likes. However, programs that break these rules are likely to fail
in unexpected and unpredictable ways.
2015-08-28 15:33:40 +00:00
Using cgo directly
Usage:
2017-04-10 11:32:00 +00:00
go tool cgo [cgo options] [-- compiler options] gofiles...
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
Cgo transforms the specified input Go source files into several output
Go and C source files.
2015-08-28 15:33:40 +00:00
The compiler options are passed through uninterpreted when
invoking the C compiler to compile the C parts of the package.
The following options are available when running cgo directly:
-dynimport file
Write list of symbols imported by file. Write to
-dynout argument or to standard output. Used by go
build when building a cgo package.
-dynout file
Write -dynimport output to file.
2017-04-10 11:32:00 +00:00
-dynpackage package
Set Go package for -dynimport output.
2015-08-28 15:33:40 +00:00
-dynlinker
Write dynamic linker as part of -dynimport output.
-godefs
Write out input file in Go syntax replacing C package
names with real values. Used to generate files in the
syscall package when bootstrapping a new target.
-srcdir directory
Find the Go input files, listed on the command line,
in directory.
2015-08-28 15:33:40 +00:00
-objdir directory
Put all generated files in directory.
2017-04-10 11:32:00 +00:00
-importpath string
The import path for the Go package. Optional; used for
nicer comments in the generated files.
-exportheader file
If there are any exported functions, write the
generated export declarations to file.
C code can #include this to see the declarations.
2015-08-28 15:33:40 +00:00
-gccgo
Generate output for the gccgo compiler rather than the
gc compiler.
-gccgoprefix prefix
The -fgo-prefix option to be used with gccgo.
-gccgopkgpath path
The -fgo-pkgpath option to be used with gccgo.
-import_runtime_cgo
If set (which it is by default) import runtime/cgo in
generated output.
-import_syscall
If set (which it is by default) import syscall in
generated output.
-debug-define
Debugging option. Print #defines.
-debug-gcc
Debugging option. Trace C compiler execution and output.
*/
package main
/*
Implementation details.
Cgo provides a way for Go programs to call C code linked into the same
address space. This comment explains the operation of cgo.
Cgo reads a set of Go source files and looks for statements saying
import "C". If the import has a doc comment, that comment is
taken as literal C code to be used as a preamble to any C code
generated by cgo. A typical preamble #includes necessary definitions:
// #include <stdio.h>
import "C"
For more details about the usage of cgo, see the documentation
comment at the top of this file.
Understanding C
Cgo scans the Go source files that import "C" for uses of that
package, such as C.puts. It collects all such identifiers. The next
step is to determine each kind of name. In C.xxx the xxx might refer
to a type, a function, a constant, or a global variable. Cgo must
decide which.
The obvious thing for cgo to do is to process the preamble, expanding
#includes and processing the corresponding C code. That would require
a full C parser and type checker that was also aware of any extensions
known to the system compiler (for example, all the GNU C extensions) as
well as the system-specific header locations and system-specific
pre-#defined macros. This is certainly possible to do, but it is an
enormous amount of work.
Cgo takes a different approach. It determines the meaning of C
identifiers not by parsing C code but by feeding carefully constructed
programs into the system C compiler and interpreting the generated
error messages, debug information, and object files. In practice,
parsing these is significantly less work and more robust than parsing
C source.
Cgo first invokes gcc -E -dM on the preamble, in order to find out
about simple #defines for constants and the like. These are recorded
for later use.
Next, cgo needs to identify the kinds for each identifier. For the
identifiers C.foo and C.bar, cgo generates this C program:
<preamble>
#line 1 "not-declared"
void __cgo_f_xxx_1(void) { __typeof__(foo) *__cgo_undefined__; }
#line 1 "not-type"
void __cgo_f_xxx_2(void) { foo *__cgo_undefined__; }
#line 1 "not-const"
void __cgo_f_xxx_3(void) { enum { __cgo_undefined__ = (foo)*1 }; }
#line 2 "not-declared"
void __cgo_f_xxx_1(void) { __typeof__(bar) *__cgo_undefined__; }
#line 2 "not-type"
void __cgo_f_xxx_2(void) { bar *__cgo_undefined__; }
#line 2 "not-const"
void __cgo_f_xxx_3(void) { enum { __cgo_undefined__ = (bar)*1 }; }
This program will not compile, but cgo can use the presence or absence
of an error message on a given line to deduce the information it
needs. The program is syntactically valid regardless of whether each
name is a type or an ordinary identifier, so there will be no syntax
errors that might stop parsing early.
An error on not-declared:1 indicates that foo is undeclared.
An error on not-type:1 indicates that foo is not a type (if declared at all, it is an identifier).
An error on not-const:1 indicates that foo is not an integer constant.
The line number specifies the name involved. In the example, 1 is foo and 2 is bar.
Next, cgo must learn the details of each type, variable, function, or
constant. It can do this by reading object files. If cgo has decided
that t1 is a type, v2 and v3 are variables or functions, and c4, c5,
and c6 are constants, it generates:
<preamble>
__typeof__(t1) *__cgo__1;
__typeof__(v2) *__cgo__2;
__typeof__(v3) *__cgo__3;
__typeof__(c4) *__cgo__4;
enum { __cgo_enum__4 = c4 };
__typeof__(c5) *__cgo__5;
enum { __cgo_enum__5 = c5 };
__typeof__(c6) *__cgo__6;
enum { __cgo_enum__6 = c6 };
long long __cgo_debug_data[] = {
0, // t1
0, // v2
0, // v3
c4,
c5,
c6,
1
};
and again invokes the system C compiler, to produce an object file
containing debug information. Cgo parses the DWARF debug information
for __cgo__N to learn the type of each identifier. (The types also
distinguish functions from global variables.) If using a standard gcc,
cgo can parse the DWARF debug information for the __cgo_enum__N to
learn the identifier's value. The LLVM-based gcc on OS X emits
incomplete DWARF information for enums; in that case cgo reads the
constant values from the __cgo_debug_data from the object file's data
segment.
At this point cgo knows the meaning of each C.xxx well enough to start
the translation process.
Translating Go
Given the input Go files x.go and y.go, cgo generates these source
files:
2017-04-10 11:32:00 +00:00
x.cgo1.go # for gc (cmd/compile)
y.cgo1.go # for gc
_cgo_gotypes.go # for gc
_cgo_import.go # for gc (if -dynout _cgo_import.go)
2015-08-28 15:33:40 +00:00
x.cgo2.c # for gcc
y.cgo2.c # for gcc
2017-04-10 11:32:00 +00:00
_cgo_defun.c # for gcc (if -gccgo)
2015-08-28 15:33:40 +00:00
_cgo_export.c # for gcc
2017-04-10 11:32:00 +00:00
_cgo_export.h # for gcc
2015-08-28 15:33:40 +00:00
_cgo_main.c # for gcc
2017-04-10 11:32:00 +00:00
_cgo_flags # for alternative build tools
2015-08-28 15:33:40 +00:00
The file x.cgo1.go is a copy of x.go with the import "C" removed and
references to C.xxx replaced with names like _Cfunc_xxx or _Ctype_xxx.
The definitions of those identifiers, written as Go functions, types,
or variables, are provided in _cgo_gotypes.go.
2017-04-10 11:32:00 +00:00
Here is a _cgo_gotypes.go containing definitions for needed C types:
2015-08-28 15:33:40 +00:00
type _Ctype_char int8
type _Ctype_int int32
type _Ctype_void [0]byte
2017-04-10 11:32:00 +00:00
The _cgo_gotypes.go file also contains the definitions of the
functions. They all have similar bodies that invoke runtime·cgocall
to make a switch from the Go runtime world to the system C (GCC-based)
world.
2015-08-28 15:33:40 +00:00
For example, here is the definition of _Cfunc_puts:
2017-04-10 11:32:00 +00:00
//go:cgo_import_static _cgo_be59f0f25121_Cfunc_puts
//go:linkname __cgofn__cgo_be59f0f25121_Cfunc_puts _cgo_be59f0f25121_Cfunc_puts
var __cgofn__cgo_be59f0f25121_Cfunc_puts byte
var _cgo_be59f0f25121_Cfunc_puts = unsafe.Pointer(&__cgofn__cgo_be59f0f25121_Cfunc_puts)
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
func _Cfunc_puts(p0 *_Ctype_char) (r1 _Ctype_int) {
_cgo_runtime_cgocall(_cgo_be59f0f25121_Cfunc_puts, uintptr(unsafe.Pointer(&p0)))
return
2015-08-28 15:33:40 +00:00
}
The hexadecimal number is a hash of cgo's input, chosen to be
deterministic yet unlikely to collide with other uses. The actual
function _cgo_be59f0f25121_Cfunc_puts is implemented in a C source
file compiled by gcc, the file x.cgo2.c:
void
_cgo_be59f0f25121_Cfunc_puts(void *v)
{
struct {
char* p0;
int r;
char __pad12[4];
} __attribute__((__packed__, __gcc_struct__)) *a = v;
a->r = puts((void*)a->p0);
}
It extracts the arguments from the pointer to _Cfunc_puts's argument
2015-08-28 15:33:40 +00:00
frame, invokes the system C function (in this case, puts), stores the
result in the frame, and returns.
Linking
Once the _cgo_export.c and *.cgo2.c files have been compiled with gcc,
they need to be linked into the final binary, along with the libraries
2017-04-10 11:32:00 +00:00
they might depend on (in the case of puts, stdio). cmd/link has been
2015-08-28 15:33:40 +00:00
extended to understand basic ELF files, but it does not understand ELF
in the full complexity that modern C libraries embrace, so it cannot
in general generate direct references to the system libraries.
Instead, the build process generates an object file using dynamic
linkage to the desired libraries. The main function is provided by
_cgo_main.c:
int main() { return 0; }
void crosscall2(void(*fn)(void*, int, uintptr_t), void *a, int c, uintptr_t ctxt) { }
uintptr_t _cgo_wait_runtime_init_done() { }
2015-08-28 15:33:40 +00:00
void _cgo_allocate(void *a, int c) { }
void _cgo_panic(void *a, int c) { }
The extra functions here are stubs to satisfy the references in the C
code generated for gcc. The build process links this stub, along with
_cgo_export.c and *.cgo2.c, into a dynamic executable and then lets
cgo examine the executable. Cgo records the list of shared library
references and resolved names and writes them into a new file
2017-04-10 11:32:00 +00:00
_cgo_import.go, which looks like:
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
//go:cgo_dynamic_linker "/lib64/ld-linux-x86-64.so.2"
//go:cgo_import_dynamic puts puts#GLIBC_2.2.5 "libc.so.6"
//go:cgo_import_dynamic __libc_start_main __libc_start_main#GLIBC_2.2.5 "libc.so.6"
//go:cgo_import_dynamic stdout stdout#GLIBC_2.2.5 "libc.so.6"
//go:cgo_import_dynamic fflush fflush#GLIBC_2.2.5 "libc.so.6"
//go:cgo_import_dynamic _ _ "libpthread.so.0"
//go:cgo_import_dynamic _ _ "libc.so.6"
2015-08-28 15:33:40 +00:00
In the end, the compiled Go package, which will eventually be
2017-04-10 11:32:00 +00:00
presented to cmd/link as part of a larger program, contains:
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
_go_.o # gc-compiled object for _cgo_gotypes.go, _cgo_import.go, *.cgo1.go
2015-08-28 15:33:40 +00:00
_all.o # gcc-compiled object for _cgo_export.c, *.cgo2.c
2017-04-10 11:32:00 +00:00
The final program will be a dynamic executable, so that cmd/link can avoid
2015-08-28 15:33:40 +00:00
needing to process arbitrary .o files. It only needs to process the .o
files generated from C files that cgo writes, and those are much more
limited in the ELF or other features that they use.
2017-04-10 11:32:00 +00:00
In essence, the _cgo_import.o file includes the extra linking
directives that cmd/link is not sophisticated enough to derive from _all.o
2015-08-28 15:33:40 +00:00
on its own. Similarly, the _all.o uses dynamic references to real
2017-04-10 11:32:00 +00:00
system object code because cmd/link is not sophisticated enough to process
2015-08-28 15:33:40 +00:00
the real code.
2017-04-10 11:32:00 +00:00
The main benefits of this system are that cmd/link remains relatively simple
2015-08-28 15:33:40 +00:00
(it does not need to implement a complete ELF and Mach-O linker) and
that gcc is not needed after the package is compiled. For example,
package net uses cgo for access to name resolution functions provided
by libc. Although gcc is needed to compile package net, gcc is not
needed to link programs that import package net.
Runtime
When using cgo, Go must not assume that it owns all details of the
process. In particular it needs to coordinate with C in the use of
2017-04-10 11:32:00 +00:00
threads and thread-local storage. The runtime package declares a few
2015-08-28 15:33:40 +00:00
variables:
2017-04-10 11:32:00 +00:00
var (
iscgo bool
_cgo_init unsafe.Pointer
_cgo_thread_start unsafe.Pointer
)
2015-08-28 15:33:40 +00:00
Any package using cgo imports "runtime/cgo", which provides
2017-04-10 11:32:00 +00:00
initializations for these variables. It sets iscgo to true, _cgo_init
to a gcc-compiled function that can be called early during program
startup, and _cgo_thread_start to a gcc-compiled function that can be
used to create a new thread, in place of the runtime's usual direct
system calls.
2015-08-28 15:33:40 +00:00
Internal and External Linking
2017-04-10 11:32:00 +00:00
The text above describes "internal" linking, in which cmd/link parses and
2015-08-28 15:33:40 +00:00
links host object files (ELF, Mach-O, PE, and so on) into the final
2017-04-10 11:32:00 +00:00
executable itself. Keeping cmd/link simple means we cannot possibly
2015-08-28 15:33:40 +00:00
implement the full semantics of the host linker, so the kinds of
objects that can be linked directly into the binary is limited (other
code can only be used as a dynamic library). On the other hand, when
2017-04-10 11:32:00 +00:00
using internal linking, cmd/link can generate Go binaries by itself.
2015-08-28 15:33:40 +00:00
In order to allow linking arbitrary object files without requiring
2017-04-10 11:32:00 +00:00
dynamic libraries, cgo supports an "external" linking mode too. In
external linking mode, cmd/link does not process any host object files.
Instead, it collects all the Go code and writes a single go.o object
file containing it. Then it invokes the host linker (usually gcc) to
combine the go.o object file and any supporting non-Go code into a
final executable. External linking avoids the dynamic library
2015-08-28 15:33:40 +00:00
requirement but introduces a requirement that the host linker be
present to create such a binary.
Most builds both compile source code and invoke the linker to create a
binary. When cgo is involved, the compile step already requires gcc, so
it is not problematic for the link step to require gcc too.
An important exception is builds using a pre-compiled copy of the
standard library. In particular, package net uses cgo on most systems,
and we want to preserve the ability to compile pure Go code that
imports net without requiring gcc to be present at link time. (In this
case, the dynamic library requirement is less significant, because the
only library involved is libc.so, which can usually be assumed
present.)
This conflict between functionality and the gcc requirement means we
must support both internal and external linking, depending on the
circumstances: if net is the only cgo-using package, then internal
linking is probably fine, but if other packages are involved, so that there
are dependencies on libraries beyond libc, external linking is likely
to work better. The compilation of a package records the relevant
information to support both linking modes, leaving the decision
to be made when linking the final binary.
Linking Directives
In either linking mode, package-specific directives must be passed
2017-04-10 11:32:00 +00:00
through to cmd/link. These are communicated by writing //go: directives in a
Go source file compiled by gc. The directives are copied into the .o
object file and then processed by the linker.
2015-08-28 15:33:40 +00:00
The directives are:
2017-04-10 11:32:00 +00:00
//go:cgo_import_dynamic <local> [<remote> ["<library>"]]
2015-08-28 15:33:40 +00:00
In internal linking mode, allow an unresolved reference to
<local>, assuming it will be resolved by a dynamic library
symbol. The optional <remote> specifies the symbol's name and
possibly version in the dynamic library, and the optional "<library>"
names the specific library where the symbol should be found.
In the <remote>, # or @ can be used to introduce a symbol version.
Examples:
2017-04-10 11:32:00 +00:00
//go:cgo_import_dynamic puts
//go:cgo_import_dynamic puts puts#GLIBC_2.2.5
//go:cgo_import_dynamic puts puts#GLIBC_2.2.5 "libc.so.6"
2015-08-28 15:33:40 +00:00
A side effect of the cgo_import_dynamic directive with a
library is to make the final binary depend on that dynamic
library. To get the dependency without importing any specific
symbols, use _ for local and remote.
Example:
2017-04-10 11:32:00 +00:00
//go:cgo_import_dynamic _ _ "libc.so.6"
2015-08-28 15:33:40 +00:00
For compatibility with current versions of SWIG,
2017-04-10 11:32:00 +00:00
#pragma dynimport is an alias for //go:cgo_import_dynamic.
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
//go:cgo_dynamic_linker "<path>"
2015-08-28 15:33:40 +00:00
In internal linking mode, use "<path>" as the dynamic linker
in the final binary. This directive is only needed from one
package when constructing a binary; by convention it is
supplied by runtime/cgo.
Example:
2017-04-10 11:32:00 +00:00
//go:cgo_dynamic_linker "/lib/ld-linux.so.2"
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
//go:cgo_export_dynamic <local> <remote>
2015-08-28 15:33:40 +00:00
In internal linking mode, put the Go symbol
named <local> into the program's exported symbol table as
<remote>, so that C code can refer to it by that name. This
mechanism makes it possible for C code to call back into Go or
to share Go's data.
For compatibility with current versions of SWIG,
2017-04-10 11:32:00 +00:00
#pragma dynexport is an alias for //go:cgo_export_dynamic.
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
//go:cgo_import_static <local>
2015-08-28 15:33:40 +00:00
In external linking mode, allow unresolved references to
<local> in the go.o object file prepared for the host linker,
under the assumption that <local> will be supplied by the
other object files that will be linked with go.o.
Example:
2017-04-10 11:32:00 +00:00
//go:cgo_import_static puts_wrapper
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
//go:cgo_export_static <local> <remote>
2015-08-28 15:33:40 +00:00
In external linking mode, put the Go symbol
named <local> into the program's exported symbol table as
<remote>, so that C code can refer to it by that name. This
mechanism makes it possible for C code to call back into Go or
to share Go's data.
2017-04-10 11:32:00 +00:00
//go:cgo_ldflag "<arg>"
2015-08-28 15:33:40 +00:00
In external linking mode, invoke the host linker (usually gcc)
with "<arg>" as a command-line argument following the .o files.
Note that the arguments are for "gcc", not "ld".
Example:
2017-04-10 11:32:00 +00:00
//go:cgo_ldflag "-lpthread"
//go:cgo_ldflag "-L/usr/local/sqlite3/lib"
2015-08-28 15:33:40 +00:00
A package compiled with cgo will include directives for both
internal and external linking; the linker will select the appropriate
subset for the chosen linking mode.
Example
As a simple example, consider a package that uses cgo to call C.sin.
The following code will be generated by cgo:
2017-04-10 11:32:00 +00:00
// compiled by gc
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
//go:cgo_ldflag "-lm"
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
type _Ctype_double float64
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
//go:cgo_import_static _cgo_gcc_Cfunc_sin
//go:linkname __cgo_gcc_Cfunc_sin _cgo_gcc_Cfunc_sin
var __cgo_gcc_Cfunc_sin byte
var _cgo_gcc_Cfunc_sin = unsafe.Pointer(&__cgo_gcc_Cfunc_sin)
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
func _Cfunc_sin(p0 _Ctype_double) (r1 _Ctype_double) {
_cgo_runtime_cgocall(_cgo_gcc_Cfunc_sin, uintptr(unsafe.Pointer(&p0)))
return
2015-08-28 15:33:40 +00:00
}
// compiled by gcc, into foo.cgo2.o
void
_cgo_gcc_Cfunc_sin(void *v)
{
struct {
double p0;
double r;
} __attribute__((__packed__)) *a = v;
a->r = sin(a->p0);
}
What happens at link time depends on whether the final binary is linked
using the internal or external mode. If other packages are compiled in
"external only" mode, then the final link will be an external one.
Otherwise the link will be an internal one.
2017-04-10 11:32:00 +00:00
The linking directives are used according to the kind of final link
used.
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
In internal mode, cmd/link itself processes all the host object files, in
2015-08-28 15:33:40 +00:00
particular foo.cgo2.o. To do so, it uses the cgo_import_dynamic and
cgo_dynamic_linker directives to learn that the otherwise undefined
reference to sin in foo.cgo2.o should be rewritten to refer to the
symbol sin with version GLIBC_2.2.5 from the dynamic library
"libm.so.6", and the binary should request "/lib/ld-linux.so.2" as its
runtime dynamic linker.
2017-04-10 11:32:00 +00:00
In external mode, cmd/link does not process any host object files, in
particular foo.cgo2.o. It links together the gc-generated object
files, along with any other Go code, into a go.o file. While doing
that, cmd/link will discover that there is no definition for
_cgo_gcc_Cfunc_sin, referred to by the gc-compiled source file. This
is okay, because cmd/link also processes the cgo_import_static directive and
2015-08-28 15:33:40 +00:00
knows that _cgo_gcc_Cfunc_sin is expected to be supplied by a host
2017-04-10 11:32:00 +00:00
object file, so cmd/link does not treat the missing symbol as an error when
2015-08-28 15:33:40 +00:00
creating go.o. Indeed, the definition for _cgo_gcc_Cfunc_sin will be
provided to the host linker by foo2.cgo.o, which in turn will need the
2017-04-10 11:32:00 +00:00
symbol 'sin'. cmd/link also processes the cgo_ldflag directives, so that it
2015-08-28 15:33:40 +00:00
knows that the eventual host link command must include the -lm
argument, so that the host linker will be able to find 'sin' in the
math library.
2017-04-10 11:32:00 +00:00
cmd/link Command Line Interface
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
The go command and any other Go-aware build systems invoke cmd/link
to link a collection of packages into a single binary. By default, cmd/link will
2015-08-28 15:33:40 +00:00
present the same interface it does today:
2017-04-10 11:32:00 +00:00
cmd/link main.a
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
produces a file named a.out, even if cmd/link does so by invoking the host
2015-08-28 15:33:40 +00:00
linker in external linking mode.
2017-04-10 11:32:00 +00:00
By default, cmd/link will decide the linking mode as follows: if the only
2015-08-28 15:33:40 +00:00
packages using cgo are those on a whitelist of standard library
2017-04-10 11:32:00 +00:00
packages (net, os/user, runtime/cgo), cmd/link will use internal linking
mode. Otherwise, there are non-standard cgo packages involved, and cmd/link
2015-08-28 15:33:40 +00:00
will use external linking mode. The first rule means that a build of
the godoc binary, which uses net but no other cgo, can run without
needing gcc available. The second rule means that a build of a
cgo-wrapped library like sqlite3 can generate a standalone executable
instead of needing to refer to a dynamic library. The specific choice
2017-04-10 11:32:00 +00:00
can be overridden using a command line flag: cmd/link -linkmode=internal or
cmd/link -linkmode=external.
2015-08-28 15:33:40 +00:00
2017-04-10 11:32:00 +00:00
In an external link, cmd/link will create a temporary directory, write any
2015-08-28 15:33:40 +00:00
host object files found in package archives to that directory (renamed
to avoid conflicts), write the go.o file to that directory, and invoke
the host linker. The default value for the host linker is $CC, split
into fields, or else "gcc". The specific host linker command line can
2017-04-10 11:32:00 +00:00
be overridden using command line flags: cmd/link -extld=clang
2015-08-28 15:33:40 +00:00
-extldflags='-ggdb -O3'. If any package in a build includes a .cc or
other file compiled by the C++ compiler, the go tool will use the
-extld option to set the host linker to the C++ compiler.
These defaults mean that Go-aware build systems can ignore the linking
2017-04-10 11:32:00 +00:00
changes and keep running plain 'cmd/link' and get reasonable results, but
2015-08-28 15:33:40 +00:00
they can also control the linking details if desired.
*/