mirror of
https://github.com/golang/go
synced 2024-09-30 16:28:32 -06:00
cmd/cgo: update docs refering to 6g and 6l
Change-Id: Id6cb5e3d40e8a2ded6359aa7fcdc012861cc3994 Reviewed-on: https://go-review.googlesource.com/14545 Reviewed-by: Andrew Gerrand <adg@golang.org> Reviewed-by: Ian Lance Taylor <iant@golang.org>
This commit is contained in:
parent
48b1e6bc97
commit
5ae12e9c71
@ -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.
|
||||
|
||||
*/
|
||||
|
Loading…
Reference in New Issue
Block a user