LEFT | RIGHT |
1 // Copyright 2009 The Go Authors. All rights reserved. | 1 // Copyright 2009 The Go Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style | 2 // Use of this source code is governed by a BSD-style |
3 // license that can be found in the LICENSE file. | 3 // license that can be found in the LICENSE file. |
4 | 4 |
5 /* | 5 /* |
6 | 6 |
7 Cgo enables the creation of Go packages that call C code. | 7 Cgo enables the creation of Go packages that call C code. |
8 | 8 |
9 Using cgo with the go command | 9 Using cgo with the go command |
10 | 10 |
(...skipping 33 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
44 | 44 |
45 // #cgo pkg-config: png cairo | 45 // #cgo pkg-config: png cairo |
46 // #include <png.h> | 46 // #include <png.h> |
47 import "C" | 47 import "C" |
48 | 48 |
49 When building, the CGO_CFLAGS, CGO_CPPFLAGS, CGO_CXXFLAGS and | 49 When building, the CGO_CFLAGS, CGO_CPPFLAGS, CGO_CXXFLAGS and |
50 CGO_LDFLAGS environment variables are added to the flags derived from | 50 CGO_LDFLAGS environment variables are added to the flags derived from |
51 these directives. Package-specific flags should be set using the | 51 these directives. Package-specific flags should be set using the |
52 directives, not the environment variables, so that builds work in | 52 directives, not the environment variables, so that builds work in |
53 unmodified environments. | 53 unmodified environments. |
| 54 |
| 55 All the cgo CPPFLAGS and CFLAGS directives in a package are concatenated and |
| 56 used to compile C files in that package. All the CPPFLAGS and CXXFLAGS |
| 57 directives in a package are concatenated and used to compile C++ files in that |
| 58 package. All the LDFLAGS directives in any package in the program are |
| 59 concatenated and used at link time. All the pkg-config directives are |
| 60 concatenated and sent to pkg-config simultaneously to add to each appropriate |
| 61 set of command-line flags. |
54 | 62 |
55 When the Go tool sees that one or more Go files use the special import | 63 When the Go tool sees that one or more Go files use the special import |
56 "C", it will look for other non-Go files in the directory and compile | 64 "C", it will look for other non-Go files in the directory and compile |
57 them as part of the Go package. Any .c, .s, or .S files will be | 65 them as part of the Go package. Any .c, .s, or .S files will be |
58 compiled with the C compiler. Any .cc, .cpp, or .cxx files will be | 66 compiled with the C compiler. Any .cc, .cpp, or .cxx files will be |
59 compiled with the C++ compiler. Any .h, .hh, .hpp, or .hxx files will | 67 compiled with the C++ compiler. Any .h, .hh, .hpp, or .hxx files will |
60 not be compiled separately, but, if these header files are changed, | 68 not be compiled separately, but, if these header files are changed, |
61 the C and C++ files will be recompiled. The default C and C++ | 69 the C and C++ files will be recompiled. The default C and C++ |
62 compilers may be changed by the CC and CXX environment variables, | 70 compilers may be changed by the CC and CXX environment variables, |
63 respectively; those environment variables may include command line | 71 respectively; those environment variables may include command line |
64 options. | 72 options. |
65 | 73 |
| 74 To enable cgo during cross compiling builds, set the CGO_ENABLED |
| 75 environment variable to 1 when building the Go tools with make.bash. |
| 76 Also, set CC_FOR_TARGET to the C cross compiler for the target. CC will |
| 77 be used for compiling for the host. |
| 78 |
| 79 After the Go tools are built, when running the go command, CC_FOR_TARGET is |
| 80 ignored. The value of CC_FOR_TARGET when running make.bash is the default |
| 81 compiler. However, you can set the environment variable CC, not CC_FOR_TARGET, |
| 82 to control the compiler when running the go tool. |
| 83 |
| 84 CXX_FOR_TARGET works in a similar way for C++ code. |
| 85 |
66 Go references to C | 86 Go references to C |
67 | 87 |
68 Within the Go file, C's struct field names that are keywords in Go | 88 Within the Go file, C's struct field names that are keywords in Go |
69 can be accessed by prefixing them with an underscore: if x points at a C | 89 can be accessed by prefixing them with an underscore: if x points at a C |
70 struct with a field named "type", x._type accesses the field. | 90 struct with a field named "type", x._type accesses the field. |
71 C struct fields that cannot be expressed in Go, such as bit fields | 91 C struct fields that cannot be expressed in Go, such as bit fields |
72 or misaligned data, are omitted in the Go struct, replaced by | 92 or misaligned data, are omitted in the Go struct, replaced by |
73 appropriate padding to reach the next field or the end of the struct. | 93 appropriate padding to reach the next field or the end of the struct. |
74 | 94 |
75 The standard C numeric types are available under the names | 95 The standard C numeric types are available under the names |
76 C.char, C.schar (signed char), C.uchar (unsigned char), | 96 C.char, C.schar (signed char), C.uchar (unsigned char), |
77 C.short, C.ushort (unsigned short), C.int, C.uint (unsigned int), | 97 C.short, C.ushort (unsigned short), C.int, C.uint (unsigned int), |
78 C.long, C.ulong (unsigned long), C.longlong (long long), | 98 C.long, C.ulong (unsigned long), C.longlong (long long), |
79 C.ulonglong (unsigned long long), C.float, C.double. | 99 C.ulonglong (unsigned long long), C.float, C.double. |
80 The C type void* is represented by Go's unsafe.Pointer. | 100 The C type void* is represented by Go's unsafe.Pointer. |
81 | 101 |
82 To access a struct, union, or enum type directly, prefix it with | 102 To access a struct, union, or enum type directly, prefix it with |
83 struct_, union_, or enum_, as in C.struct_stat. | 103 struct_, union_, or enum_, as in C.struct_stat. |
84 | 104 |
85 As Go doesn't have support for C's union type in the general case, | 105 As Go doesn't have support for C's union type in the general case, |
86 C's union types are represented as a Go byte array with the same length. | 106 C's union types are represented as a Go byte array with the same length. |
87 | 107 |
88 Go structs cannot embed fields with C types. | 108 Go structs cannot embed fields with C types. |
89 | 109 |
90 Because cgo ultimately translate the C types into equivalent Go types | 110 Cgo translates C types into equivalent unexported Go types. |
91 (subject to restrictions noted above), the resulting type will follow | 111 Because the translations are unexported, a Go package should not |
92 the usual Go rules of namespacing. Especially, C.type used in one package | 112 expose C types in its exported API: a C type used in one Go package |
93 will not be compatible with the same C.type in another package, so it is | 113 is different from the same C type used in another. |
94 better to confine all cgo stuff to the same library in the same Go | |
95 package. | |
96 | |
97 Opaque types in C (such as void* or pointer to types without a definition) | |
98 will be translated to Go *[0]byte. However, cgo used to have a bug that | |
99 treats all such types as equivalent, Go 1.3 corrected the behavior so that | |
100 different C types are incompatible with each other. | |
101 | 114 |
102 Any C function (even void functions) may be called in a multiple | 115 Any C function (even void functions) may be called in a multiple |
103 assignment context to retrieve both the return value (if any) and the | 116 assignment context to retrieve both the return value (if any) and the |
104 C errno variable as an error (use _ to skip the result value if the | 117 C errno variable as an error (use _ to skip the result value if the |
105 function returns void). For example: | 118 function returns void). For example: |
106 | 119 |
107 n, err := C.sqrt(-1) | 120 n, err := C.sqrt(-1) |
108 _, err := C.voidFunc() | 121 _, err := C.voidFunc() |
109 | 122 |
110 Calling C function pointers is currently not supported, however you can | 123 Calling C function pointers is currently not supported, however you can |
(...skipping 615 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
726 be overridden using command line flags: 6l -extld=clang | 739 be overridden using command line flags: 6l -extld=clang |
727 -extldflags='-ggdb -O3'. If any package in a build includes a .cc or | 740 -extldflags='-ggdb -O3'. If any package in a build includes a .cc or |
728 other file compiled by the C++ compiler, the go tool will use the | 741 other file compiled by the C++ compiler, the go tool will use the |
729 -extld option to set the host linker to the C++ compiler. | 742 -extld option to set the host linker to the C++ compiler. |
730 | 743 |
731 These defaults mean that Go-aware build systems can ignore the linking | 744 These defaults mean that Go-aware build systems can ignore the linking |
732 changes and keep running plain '6l' and get reasonable results, but | 745 changes and keep running plain '6l' and get reasonable results, but |
733 they can also control the linking details if desired. | 746 they can also control the linking details if desired. |
734 | 747 |
735 */ | 748 */ |
LEFT | RIGHT |