From acae4d212c6af5f96677ea7d2ed827389bd7b819 Mon Sep 17 00:00:00 2001 From: Ian Lance Taylor Date: Tue, 17 Sep 2013 07:11:40 -0700 Subject: [PATCH] cmd/cgo: rearrange and update documentation In particular document that the Go tool will look for certain file extensions and compile with them with either the C or the C++ compiler. Fixes #6393. R=golang-dev, r CC=golang-dev https://golang.org/cl/13733043 --- src/cmd/cgo/doc.go | 78 +++++++++++++++++++++++++++++----------------- 1 file changed, 49 insertions(+), 29 deletions(-) diff --git a/src/cmd/cgo/doc.go b/src/cmd/cgo/doc.go index 6ceb3bd3d2..8ee6ddf95b 100644 --- a/src/cmd/cgo/doc.go +++ b/src/cmd/cgo/doc.go @@ -6,15 +6,11 @@ Cgo enables the creation of Go packages that call C code. -Usage: - go tool cgo [cgo options] [-- compiler options] file.go - -The compiler options are passed through uninterpreted when -invoking gcc to compile the C parts of the package. +Using cgo with the go command -The input file.go is a syntactically valid Go source file that imports -the pseudo-package "C" and then refers to types such as C.size_t, -variables such as C.stdout, or functions such as C.putchar. +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 @@ -24,11 +20,15 @@ the C parts of the package. For example: // #include import "C" -CFLAGS, CPPFLAGS, CXXFLAGS and LDFLAGS may be defined with pseudo #cgo directives -within these comments to tweak the behavior of gcc. Values defined -in multiple directives are concatenated together. Options prefixed -by $GOOS, $GOARCH, or $GOOS/$GOARCH are only defined in matching -systems. For example: +See $GOROOT/misc/cgo/stdio and $GOROOT/misc/cgo/gmp for examples. See +"C? Go? Cgo!" for an introduction to using cgo: +http://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 +together. Options prefixed by $GOOS, $GOARCH, or $GOOS/$GOARCH are +only defined in matching systems. For example: // #cgo CFLAGS: -DPNG_DEBUG=1 // #cgo linux CFLAGS: -DLINUX=1 @@ -44,10 +44,24 @@ For example: // #include import "C" -The CGO_CFLAGS, CGO_CPPFLAGS, CGO_CXXFLAGS 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 unmodified environments. +When building, the CGO_CFLAGS, CGO_CPPFLAGS, CGO_CXXFLAGS 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 +unmodified environments. + +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 +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. + +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 @@ -82,6 +96,7 @@ back and forth between Go and C. C code may call function pointers received from Go. For example: package main + // typedef int (*intFunc) (); // // int @@ -128,6 +143,8 @@ by making copies of the data. In pseudo-Go definitions: // C pointer, length to Go []byte func C.GoBytes(unsafe.Pointer, C.int) []byte +C references to Go + Go functions can be exported for use by C code in the following way: //export MyFunction @@ -141,7 +158,7 @@ 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 _cgo_export.h generated header, after any preambles +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. @@ -151,14 +168,17 @@ since it is copied into two different C output files, it must not contain any definitions, only declarations. Definitions must be placed in preambles in other files, or in C source files. -Cgo transforms the input file into four output files: two Go source +Using cgo directly + +Usage: + go tool cgo [cgo options] [-- compiler options] file.go + +Cgo transforms the input file.go into four output files: two Go source files, a C file for 6c (or 8c or 5c), and a C file for gcc. -The standard package construction rules of the go command -automate the process of using cgo. See $GOROOT/misc/cgo/stdio -and $GOROOT/misc/cgo/gmp for examples. +The compiler options are passed through uninterpreted when +invoking the C compiler to compile the C parts of the package. -Cgo options are passed automatically by go build. The following options are available when running cgo directly: -dynimport file @@ -196,9 +216,6 @@ The following options are available when running cgo directly: Debugging option. Print #defines. -debug-gcc Debugging option. Trace C compiler execution and output. - -See "C? Go? Cgo!" for an introduction to using cgo: -http://golang.org/doc/articles/c_go_cgo.html */ package main @@ -680,15 +697,18 @@ 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 -can be overridden using a command line flag: 6l -cgolink=internal or -6l -cgolink=external. +can be overridden using a command line flag: 6l -linkmode=internal or +6l -linkmode=external. In an external link, 6l will create a temporary directory, write any 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 -be overridden using a command line flag: 6l -hostld='gcc -ggdb' +be overridden using command line flags: 6l -extld=clang +-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 changes and keep running plain '6l' and get reasonable results, but -- 2.50.0