github.com/razvanm/vanadium-go-1.3@v0.0.0-20160721203343-4a65068e5915/src/cmd/gc/doc.go (about)

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // +build ignore
     6  
     7  /*
     8  
     9  Gc is the generic label for the family of Go compilers
    10  that function as part of the (modified) Plan 9 tool chain.  The C compiler
    11  documentation at
    12  
    13  	http://plan9.bell-labs.com/sys/doc/comp.pdf     (Tools overview)
    14  	http://plan9.bell-labs.com/sys/doc/compiler.pdf (C compiler architecture)
    15  
    16  gives the overall design of the tool chain.  Aside from a few adapted pieces,
    17  such as the optimizer, the Go compilers are wholly new programs.
    18  
    19  The compiler reads in a set of Go files, typically suffixed ".go".  They
    20  must all be part of one package.  The output is a single intermediate file
    21  representing the "binary assembly" of the compiled package, ready as input
    22  for the linker (6l, etc.).
    23  
    24  The generated files contain type information about the symbols exported by
    25  the package and about types used by symbols imported by the package from
    26  other packages. It is therefore not necessary when compiling client C of
    27  package P to read the files of P's dependencies, only the compiled output
    28  of P.
    29  
    30  Command Line
    31  
    32  Usage:
    33  	go tool 6g [flags] file...
    34  The specified files must be Go source files and all part of the same package.
    35  Substitute 6g with 8g or 5g where appropriate.
    36  
    37  Flags:
    38  	-o file
    39  		output file, default file.6 for 6g, etc.
    40  	-pack
    41  		write an archive file rather than an object file
    42  	-e
    43  		normally the compiler quits after 10 errors; -e prints all errors
    44  	-p path
    45  		assume that path is the eventual import path for this code,
    46  		and diagnose any attempt to import a package that depends on it.
    47  	-D path
    48  		treat a relative import as relative to path
    49  	-L
    50  		show entire file path when printing line numbers in errors
    51  	-I dir1 -I dir2
    52  		add dir1 and dir2 to the list of paths to check for imported packages
    53  	-N
    54  		disable optimizations
    55  	-nolocalimports
    56  		disallow local (relative) imports
    57  	-S
    58  		write assembly language text to standard output (code only)
    59  	-S -S
    60  		write assembly language text to standard output (code and data)
    61  	-u
    62  		disallow importing packages not marked as safe; implies -nolocalimports
    63  	-V
    64  		print the compiler version
    65  	-race
    66  		compile with race detection enabled
    67  
    68  There are also a number of debugging flags; run the command with no arguments
    69  to get a usage message.
    70  
    71  Compiler Directives
    72  
    73  The compiler accepts two compiler directives in the form of // comments at the
    74  beginning of a line. To distinguish them from non-directive comments, the directives
    75  require no space between the slashes and the name of the directive. However, since
    76  they are comments, tools unaware of the directive convention or of a particular
    77  directive can skip over a directive like any other comment.
    78  
    79      //line path/to/file:linenumber
    80  
    81  The //line directive specifies that the source line that follows should be recorded
    82  as having come from the given file path and line number. Successive lines are
    83  recorded using increasing line numbers, until the next directive. This directive
    84  typically appears in machine-generated code, so that compilers and debuggers
    85  will show lines in the original input to the generator.
    86  
    87      //go:noescape
    88  
    89  The //go:noescape directive specifies that the next declaration in the file, which
    90  must be a func without a body (meaning that it has an implementation not written
    91  in Go) does not allow any of the pointers passed as arguments to escape into the
    92  heap or into the values returned from the function. This information can be used as
    93  during the compiler's escape analysis of Go code calling the function.
    94  */
    95  package main