From 630930c35ef7b5e22e28a6424425b887bb12c9b6 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Thu, 21 May 2015 14:11:33 -0400 Subject: [PATCH] cmd/compile, cmd/link: add docs These are the Go 1.4 docs but refreshed for Go 1.5. The most sigificant change is that all references to the Plan 9 toolchain are gone. The tools no longer bear any meaningful resemblance. Change-Id: I44f5cadb832a982323d7fee0b77673e55d761b35 Reviewed-on: https://go-review.googlesource.com/10298 Reviewed-by: Rob Pike --- src/cmd/compile/doc.go | 124 +++++++++++++++++++++++++++++ src/cmd/compile/internal/gc/lex.go | 6 +- src/cmd/link/doc.go | 93 ++++++++++++++++++++++ 3 files changed, 222 insertions(+), 1 deletion(-) create mode 100644 src/cmd/compile/doc.go create mode 100644 src/cmd/link/doc.go diff --git a/src/cmd/compile/doc.go b/src/cmd/compile/doc.go new file mode 100644 index 00000000000..ca7c03bb79b --- /dev/null +++ b/src/cmd/compile/doc.go @@ -0,0 +1,124 @@ +// 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. + +/* +Compile, typically invoked as ``go tool compile,'' compiles a single Go package +comprising the files named on the command line. It then writes a single +object file named for the basename of the first source file with a .o suffix. +The object file can then be combined with other objects into a package archive +or passed directly to the linker (``go tool link''). If invoked with -pack, the compiler +writes an archive directly, bypassing the intermediate object file. + +The generated files contain type information about the symbols exported by +the package and about types used by symbols imported by the package from +other packages. It is therefore not necessary when compiling client C of +package P to read the files of P's dependencies, only the compiled output of P. + +Command Line + +Usage: + + go tool compile [flags] file... + +The specified files must be Go source files and all part of the same package. +The same compiler is used for all target operating systems and architectures. +The GOOS and GOARCH environment variables set the desired target. + +Flags: + + -D path + Set relative path for local imports. + -I dir1 -I dir2 + Search for imported packages in dir1, dir2, etc, + after consulting $GOROOT/pkg/$GOOS_$GOARCH. + -L + Show complete file path in error messages. + -N + Disable optimizations. + -S + Print assembly listing to standard output (code only). + -S -S + Print assembly listing to standard output (code and data). + -V + Print compiler version and exit. + -asmhdr file + Write assembly header to file. + -complete + Assume package has no non-Go components. + -cpuprofile file + Write a CPU profile for the compilation to file. + -dynlink + Allow references to Go symbols in shared libraries (experimental). + -e + Remove the limit on the number of errors reported (default limit is 10). + -h + Halt with a stack trace at the first error detected. + -installsuffix suffix + Look for packages in $GOROOT/pkg/$GOOS_$GOARCH_suffix + instead of $GOROOT/pkg/$GOOS_$GOARCH. + -largemodel + Generated code that assumes a large memory model. + -memprofile file + Write memory profile for the compilation to file. + -memprofilerate rate + Set runtime.MemProfileRate for the compilation to rate. + -nolocalimports + Disallow local (relative) imports. + -o file + Write object to file (default file.o or, with -pack, file.a). + -p path + Set expected package import path for the code being compiled, + and diagnose imports that would cause a circular dependency. + -pack + Write a package (archive) file rather than an object file + -race + Compile with race detector enabled. + -u + Disallow importing packages not marked as safe; implies -nolocalimports. + +There are also a number of debugging flags; run the command with no arguments +for a usage message. + +Compiler Directives + +The compiler accepts compiler directives in the form of // comments at the +beginning of a line. To distinguish them from non-directive comments, the directives +require no space between the slashes and the name of the directive. However, since +they are comments, tools unaware of the directive convention or of a particular +directive can skip over a directive like any other comment. + + //line path/to/file:linenumber + +The //line directive specifies that the source line that follows should be recorded +as having come from the given file path and line number. Successive lines are +recorded using increasing line numbers, until the next directive. This directive +typically appears in machine-generated code, so that compilers and debuggers +will show lines in the original input to the generator. + +The //line directive is an historical special case; all other directives are of the form +//go:name, indicating that the directive is defined by the Go toolchain. + + //go:noescape + +The //go:noescape directive specifies that the next declaration in the file, which +must be a func without a body (meaning that it has an implementation not written +in Go) does not allow any of the pointers passed as arguments to escape into the +heap or into the values returned from the function. This information can be used as +during the compiler's escape analysis of Go code calling the function. + + //go:nosplit + +The //go:nosplit directive specifies that the next function declared in the file must +not include a stack overflow check. This is most commonly used by low-level +runtime sources invoked at times when it is unsafe for the calling goroutine to be +preempted. + + //go:linkname localname importpath.name + +The //go:linkname directive instructs the compiler to use ``importpath.name' as the +object file symbol name for the variable or function declared as ``localname'' in the +source code. Because this directive can subvert the type system and package +modularity, it is only enabled in files that have imported "unsafe". +*/ +package main diff --git a/src/cmd/compile/internal/gc/lex.go b/src/cmd/compile/internal/gc/lex.go index f79c199258d..46b7d5da169 100644 --- a/src/cmd/compile/internal/gc/lex.go +++ b/src/cmd/compile/internal/gc/lex.go @@ -2612,6 +2612,10 @@ func mkpackage(pkgname string) { if i := strings.LastIndex(p, "."); i >= 0 { p = p[:i] } - outfile = fmt.Sprintf("%s.o", p) + suffix := ".o" + if writearchive > 0 { + suffix = ".a" + } + outfile = p + suffix } } diff --git a/src/cmd/link/doc.go b/src/cmd/link/doc.go new file mode 100644 index 00000000000..479988e8b1a --- /dev/null +++ b/src/cmd/link/doc.go @@ -0,0 +1,93 @@ +// 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. + +/* +Link, typically invoked as ``go tool link,'' reads the Go archive or object +for a package main, along with its dependencies, and combines them +into an executable binary. + +Command Line + +Usage: + + go tool link [flags] main.a + +Flags: + + -B note + Add an ELF_NT_GNU_BUILD_ID note when using ELF. + The value should start with 0x and be an even number of hex digits. + -D address + Set data segment address. + -E entry + Set entry symbol name. + -H type + Set executable format type. + The default format is inferred from GOOS and GOARCH. + On Windows, -H windowsgui writes a "GUI binary" instead of a "console binary." + -I interpreter + Set the ELF dynamic linker to use. + -L dir1 -L dir2 + Search for imported packages in dir1, dir2, etc, + after consulting $GOROOT/pkg/$GOOS_$GOARCH. + -R quantum + Set address rounding quantum. + -T address + Set text segment address. + -V + Print the linker version and exit. + -X importpath.name=value + Set the value of the string variable in importpath named name to value. + Note that before Go 1.5 this option took two separate arguments. + Now it takes one argument split on the first = sign. + -buildmode mode + Set build mode (default exe). + -cpuprofile file + Write CPU profile to file. + -d + Disable generation of dynamic executables. + The emitted code is the same in either case; the option + controls only whether a dynamic header is included. + The dynamic header is on by default, even without any + references to dynamic libraries, because many common + system tools now assume the presence of the header. + -extld linker + Set the external linker (default "clang" or "gcc"). + -extldflags flags + Set space-separated flags to pass to the external linker. + -f + Ignore version mismatch in the linked archives. + -g + Disable Go package data checks. + -installsuffix suffix + Look for packages in $GOROOT/pkg/$GOOS_$GOARCH_suffix + instead of $GOROOT/pkg/$GOOS_$GOARCH. + -linkmode mode + Set link mode (internal, external, auto). + This sets the linking mode as described in cmd/cgo/doc.go. + -linkshared + Link against installed Go shared libraries (experimental). + -memprofile file + Write memory profile to file. + -memprofilerate rate + Set runtime.MemProfileRate to rate. + -o file + Write output to file (default a.out, or a.out.exe on Windows). + -r dir1:dir2:... + Set the ELF dynamic linker search path. + -race + Link with race detection libraries. + -s + Omit the symbol table and debug information. + -shared + Generated shared object (implies -linkmode external; experimental). + -tmpdir dir + Write temporary files to dir. + Temporary files are only used in external linking mode. + -v + Print trace of linker operations. + -w + Omit the DWARF symbol table. +*/ +package main