diff options
Diffstat (limited to 'libgo/go/cmd/cgo/doc.go')
| -rw-r--r-- | libgo/go/cmd/cgo/doc.go | 54 |
1 files changed, 37 insertions, 17 deletions
diff --git a/libgo/go/cmd/cgo/doc.go b/libgo/go/cmd/cgo/doc.go index bd38a5c153..85441e61c0 100644 --- a/libgo/go/cmd/cgo/doc.go +++ b/libgo/go/cmd/cgo/doc.go @@ -1,4 +1,4 @@ -// Copyright 2009 The Go Authors. All rights reserved. +// Copyright 2009 The Go Authors. All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. @@ -31,9 +31,9 @@ See $GOROOT/misc/cgo/stdio and $GOROOT/misc/cgo/gmp for examples. See "C? Go? Cgo!" for an introduction to using cgo: https://golang.org/doc/articles/c_go_cgo.html. -CFLAGS, CPPFLAGS, CXXFLAGS and LDFLAGS may be defined with pseudo #cgo -directives within these comments to tweak the behavior of the C or C++ -compiler. Values defined in multiple directives are concatenated +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 together. The directive can include a list of build constraints limiting its effect to systems satisfying one of the constraints (see https://golang.org/pkg/go/build/#hdr-Build_Constraints for details about the constraint syntax). @@ -53,7 +53,9 @@ For example: // #include <png.h> import "C" -When building, the CGO_CFLAGS, CGO_CPPFLAGS, CGO_CXXFLAGS and +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 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 @@ -62,10 +64,11 @@ 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 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. +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. 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 @@ -83,7 +86,8 @@ 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 .h, .hh, .hpp, or .hxx files will +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 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, @@ -133,7 +137,7 @@ 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 can not refer to zero-sized fields that occur at the end of +Go code cannot refer to zero-sized fields that occur at the end of 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. @@ -148,8 +152,9 @@ 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) + n, err = C.sqrt(-1) _, err := C.voidFunc() + var n, err = C.sqrt(1) Calling C function pointers is currently not supported, however you can declare Go variables which hold C function pointers and pass them @@ -195,6 +200,13 @@ by making copies of the data. In pseudo-Go definitions: // 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 + // C string to Go string func C.GoString(*C.char) string @@ -204,6 +216,13 @@ by making copies of the data. In pseudo-Go definitions: // C data with explicit length to Go []byte 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. + C references to Go Go functions can be exported for use by C code in the following way: @@ -307,6 +326,9 @@ The following options are available when running cgo directly: 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. -objdir directory Put all generated files in directory. -importpath string @@ -501,7 +523,6 @@ file compiled by gcc, the file x.cgo2.c: void _cgo_be59f0f25121_Cfunc_puts(void *v) { - _cgo_wait_runtime_init_done(); struct { char* p0; int r; @@ -510,8 +531,7 @@ file compiled by gcc, the file x.cgo2.c: a->r = puts((void*)a->p0); } -It waits for Go runtime to be initialized (required for shared libraries), -extracts the arguments from the pointer to _Cfunc_puts's argument +It extracts the arguments from the pointer to _Cfunc_puts's argument frame, invokes the system C function (in this case, puts), stores the result in the frame, and returns. @@ -529,8 +549,8 @@ linkage to the desired libraries. The main function is provided by _cgo_main.c: int main() { return 0; } - void crosscall2(void(*fn)(void*, int), void *a, int c) { } - void _cgo_wait_runtime_init_done() { } + void crosscall2(void(*fn)(void*, int, uintptr_t), void *a, int c, uintptr_t ctxt) { } + uintptr_t _cgo_wait_runtime_init_done() { } void _cgo_allocate(void *a, int c) { } void _cgo_panic(void *a, int c) { } |