From 5ae12e9c718b2f64289bd260c6d77f601f6254c3 Mon Sep 17 00:00:00 2001 From: Shenghou Ma Date: Mon, 14 Sep 2015 00:48:02 -0400 Subject: [PATCH] cmd/cgo: update docs refering to 6g and 6l Change-Id: Id6cb5e3d40e8a2ded6359aa7fcdc012861cc3994 Reviewed-on: https://go-review.googlesource.com/14545 Reviewed-by: Andrew Gerrand Reviewed-by: Ian Lance Taylor --- src/cmd/cgo/doc.go | 84 ++++++++++++++++++++++------------------------ 1 file changed, 40 insertions(+), 44 deletions(-) diff --git a/src/cmd/cgo/doc.go b/src/cmd/cgo/doc.go index b2a5428f3f..f82d782055 100644 --- a/src/cmd/cgo/doc.go +++ b/src/cmd/cgo/doc.go @@ -391,17 +391,13 @@ the translation process. Translating Go -[The rest of this comment refers to 6g, the Go compiler that is part -of the amd64 port of the gc Go toolchain. Everything here applies to -another architecture's compilers as well.] - Given the input Go files x.go and y.go, cgo generates these source files: - x.cgo1.go # for 6g - y.cgo1.go # for 6g - _cgo_gotypes.go # for 6g - _cgo_import.go # for 6g (if -dynout _cgo_import.go) + 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) x.cgo2.c # for gcc y.cgo2.c # for gcc _cgo_defun.c # for gcc (if -gccgo) @@ -464,7 +460,7 @@ 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 -they might depend on (in the case of puts, stdio). 6l has been +they might depend on (in the case of puts, stdio). cmd/link has been 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. @@ -495,23 +491,23 @@ _cgo_import.go, which looks like: //go:cgo_import_dynamic _ _ "libc.so.6" In the end, the compiled Go package, which will eventually be -presented to 6l as part of a larger program, contains: +presented to cmd/link as part of a larger program, contains: - _go_.6 # 6g-compiled object for _cgo_gotypes.go, _cgo_import.go, *.cgo1.go + _go_.o # gc-compiled object for _cgo_gotypes.go, _cgo_import.go, *.cgo1.go _all.o # gcc-compiled object for _cgo_export.c, *.cgo2.c -The final program will be a dynamic executable, so that 6l can avoid +The final program will be a dynamic executable, so that cmd/link can avoid 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. -In essence, the _cgo_import.6 file includes the extra linking -directives that 6l is not sophisticated enough to derive from _all.o +In essence, the _cgo_import.o file includes the extra linking +directives that cmd/link is not sophisticated enough to derive from _all.o on its own. Similarly, the _all.o uses dynamic references to real -system object code because 6l is not sophisticated enough to process +system object code because cmd/link is not sophisticated enough to process the real code. -The main benefits of this system are that 6l remains relatively simple +The main benefits of this system are that cmd/link remains relatively simple (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 @@ -540,17 +536,17 @@ system calls. Internal and External Linking -The text above describes "internal" linking, in which 6l parses and +The text above describes "internal" linking, in which cmd/link parses and links host object files (ELF, Mach-O, PE, and so on) into the final -executable itself. Keeping 6l simple means we cannot possibly +executable itself. Keeping cmd/link simple means we cannot possibly 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 -using internal linking, 6l can generate Go binaries by itself. +using internal linking, cmd/link can generate Go binaries by itself. In order to allow linking arbitrary object files without requiring dynamic libraries, cgo supports an "external" linking mode too. In -external linking mode, 6l does not process any host object files. +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 @@ -582,8 +578,8 @@ to be made when linking the final binary. Linking Directives In either linking mode, package-specific directives must be passed -through to 6l. These are communicated by writing //go: directives in a -Go source file compiled by 6g. The directives are copied into the .6 +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. The directives are: @@ -672,7 +668,7 @@ Example As a simple example, consider a package that uses cgo to call C.sin. The following code will be generated by cgo: - // compiled by 6g + // compiled by gc //go:cgo_ldflag "-lm" @@ -708,7 +704,7 @@ Otherwise the link will be an internal one. The linking directives are used according to the kind of final link used. -In internal mode, 6l itself processes all the host object files, in +In internal mode, cmd/link itself processes all the host object files, in 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 @@ -716,56 +712,56 @@ 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. -In external mode, 6l does not process any host object files, in -particular foo.cgo2.o. It links together the 6g-generated object +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, 6l will discover that there is no definition for -_cgo_gcc_Cfunc_sin, referred to by the 6g-compiled source file. This -is okay, because 6l also processes the cgo_import_static directive and +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 knows that _cgo_gcc_Cfunc_sin is expected to be supplied by a host -object file, so 6l does not treat the missing symbol as an error when +object file, so cmd/link does not treat the missing symbol as an error when 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 -symbol 'sin'. 6l also processes the cgo_ldflag directives, so that it +symbol 'sin'. cmd/link also processes the cgo_ldflag directives, so that it 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. -6l Command Line Interface +cmd/link Command Line Interface -The go command and any other Go-aware build systems invoke 6l -to link a collection of packages into a single binary. By default, 6l will +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 present the same interface it does today: - 6l main.a + cmd/link main.a -produces a file named 6.out, even if 6l does so by invoking the host +produces a file named a.out, even if cmd/link does so by invoking the host linker in external linking mode. -By default, 6l will decide the linking mode as follows: if the only +By default, cmd/link will decide the linking mode as follows: if the only packages using cgo are those on a whitelist of standard library -packages (net, os/user, runtime/cgo), 6l will use internal linking -mode. Otherwise, there are non-standard cgo packages involved, and 6l +packages (net, os/user, runtime/cgo), cmd/link will use internal linking +mode. Otherwise, there are non-standard cgo packages involved, and cmd/link 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 -can be overridden using a command line flag: 6l -linkmode=internal or -6l -linkmode=external. +can be overridden using a command line flag: cmd/link -linkmode=internal or +cmd/link -linkmode=external. -In an external link, 6l will create a temporary directory, write any +In an external link, cmd/link 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 command line flags: 6l -extld=clang +be overridden using command line flags: cmd/link -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 +changes and keep running plain 'cmd/link' and get reasonable results, but they can also control the linking details if desired. */ -- 2.48.1