From 3fa379e797bb5f9920295a34d22f9a7f18ec2eb0 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Tue, 3 Nov 2009 22:00:36 -0800 Subject: [PATCH] document the gc go compilers. fix the usage message. R=rsc CC=go-dev http://go/go-review/1016033 --- src/cmd/5g/doc.go | 15 +++++++++++++++ src/cmd/5l/doc.go | 2 ++ src/cmd/6g/doc.go | 13 +++++++++++++ src/cmd/6l/doc.go | 2 ++ src/cmd/8g/doc.go | 15 +++++++++++++++ src/cmd/8l/doc.go | 2 ++ src/cmd/gc/doc.go | 46 ++++++++++++++++++++++++++++++++++++++++++++++ src/cmd/gc/lex.c | 2 +- 8 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 src/cmd/5g/doc.go create mode 100644 src/cmd/6g/doc.go create mode 100644 src/cmd/8g/doc.go create mode 100644 src/cmd/gc/doc.go diff --git a/src/cmd/5g/doc.go b/src/cmd/5g/doc.go new file mode 100644 index 0000000000..e45e355689 --- /dev/null +++ b/src/cmd/5g/doc.go @@ -0,0 +1,15 @@ +// 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. + +/* + +5g is the version of the gc compiler for the ARM, +referred to by these tools as arm. + +It reads .go files and outputs .5 files. The flags are documented in ../gc/doc.go. + +There is no instruction optimizer, so the -N flag is a no-op. + +*/ +package documentation diff --git a/src/cmd/5l/doc.go b/src/cmd/5l/doc.go index 17200d57cd..495f6fa293 100644 --- a/src/cmd/5l/doc.go +++ b/src/cmd/5l/doc.go @@ -9,6 +9,8 @@ http://plan9.bell-labs.com/magic/man2html/1/2l Its target architecture is the ARM, referred to by these tools as arm. +It reads files in .5 format generated by 5g, 5c, and 5a and emits +a binary called 5.out by default. Major changes include: - support for segmented stacks (this feature is implemented here, not in the compilers). diff --git a/src/cmd/6g/doc.go b/src/cmd/6g/doc.go new file mode 100644 index 0000000000..e4964dbd0a --- /dev/null +++ b/src/cmd/6g/doc.go @@ -0,0 +1,13 @@ +// 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. + +/* + +6g is the version of the gc compiler for the x86-64, +referred to by these tools as amd64. + +It reads .go files and outputs .6 files. The flags are documented in ../gc/doc.go. + +*/ +package documentation diff --git a/src/cmd/6l/doc.go b/src/cmd/6l/doc.go index 8d87f820ef..51663a8c8f 100644 --- a/src/cmd/6l/doc.go +++ b/src/cmd/6l/doc.go @@ -9,6 +9,8 @@ http://plan9.bell-labs.com/magic/man2html/1/2l Its target architecture is the x86-64, referred to by these tools as amd64. +It reads files in .6 format generated by 6g, 6c, and 6a and emits +a binary called 6.out by default. Major changes include: - support for ELF and Mach-O binary files diff --git a/src/cmd/8g/doc.go b/src/cmd/8g/doc.go new file mode 100644 index 0000000000..5b522fd14e --- /dev/null +++ b/src/cmd/8g/doc.go @@ -0,0 +1,15 @@ +// 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. + +/* + +8g is the version of the gc compiler for the x86, +referred to by these tools for historical reasons as 386. + +It reads .go files and outputs .8 files. The flags are documented in ../gc/doc.go. + +There is no instruction optimizer, so the -N flag is a no-op. + +*/ +package documentation diff --git a/src/cmd/8l/doc.go b/src/cmd/8l/doc.go index 36628045c5..e960159422 100644 --- a/src/cmd/8l/doc.go +++ b/src/cmd/8l/doc.go @@ -9,6 +9,8 @@ http://plan9.bell-labs.com/magic/man2html/1/2l Its target architecture is the x86, referred to by these tools for historical reasons as 386. +It reads files in .8 format generated by 8g, 8c, and 8a and emits +a binary called 8.out by default. Major changes include: - support for ELF and Mach-O binary files diff --git a/src/cmd/gc/doc.go b/src/cmd/gc/doc.go new file mode 100644 index 0000000000..f231132909 --- /dev/null +++ b/src/cmd/gc/doc.go @@ -0,0 +1,46 @@ +// 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. + +/* + +The name gc is the generic label given to the family of Go compilers +that function as part of the (modified) Plan 9 tool chain. The C compiler +documentation at + + http://plan9.bell-labs.com/sys/doc/comp.pdf (Tools overview) + http://plan9.bell-labs.com/sys/doc/compiler.pdf (C compiler architecture) + +gives the overall design of the tool chain. Aside from a few adapted pieces, +such as the optimizer, the Go compilers are wholly new programs. + +The compiler reads in a set of Go files, typically suffixed ".go". They +must all be part of one package. The output is a single intermediate file +representing the "binary assembly" of the compiled package, ready as input +for the linker (6l, etc.). + +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. + +Usage: 6g [flags] *.go (or 8g or 5g) + +Flags: + -o file + output file, default 6.out for 6g, etc. + -e + normally the compiler quits after 10 errors; -e prints all errors + -I dir1 -I dir2 + add dir1 and dir2 to the list of paths to check for imported packages + -N + disable optimization + -S + write assembly language text to standard output + +There are also a number of debugging flags; run the command with no arguments +to get a usage message. + +*/ +package documentation diff --git a/src/cmd/gc/lex.c b/src/cmd/gc/lex.c index f356906e50..c2818fc10e 100644 --- a/src/cmd/gc/lex.c +++ b/src/cmd/gc/lex.c @@ -141,7 +141,7 @@ usage: print(" -h panic on an error\n"); print(" -k name specify package name\n"); print(" -o file specify output file\n"); - print(" -p print the assembly language\n"); + print(" -S print the assembly language\n"); print(" -w print the parse tree after typing\n"); print(" -x print lex tokens\n"); exit(0);