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 <r@golang.org>

diff --git a/src/cmd/compile/doc.go b/src/cmd/compile/doc.go
new file mode 100644 (file)
index 0000000..ca7c03b
--- /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 f79c199258d6c21b1730fe1efba929a31a83456f..46b7d5da169ab5e9a1c9115b693f67ebcb413e3e 100644 (file)
--- 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 (file)
index 0000000..479988e
--- /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