github.com/mdempsky/go@v0.0.0-20151201204031-5dd372bd1e70/src/cmd/compile/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  /*
     6  Compile, typically invoked as ``go tool compile,'' compiles a single Go package
     7  comprising the files named on the command line. It then writes a single
     8  object file named for the basename of the first source file with a .o suffix.
     9  The object file can then be combined with other objects into a package archive
    10  or passed directly to the linker (``go tool link''). If invoked with -pack, the compiler
    11  writes an archive directly, bypassing the intermediate object file.
    12  
    13  The generated files contain type information about the symbols exported by
    14  the package and about types used by symbols imported by the package from
    15  other packages. It is therefore not necessary when compiling client C of
    16  package P to read the files of P's dependencies, only the compiled output of P.
    17  
    18  Command Line
    19  
    20  Usage:
    21  
    22  	go tool compile [flags] file...
    23  
    24  The specified files must be Go source files and all part of the same package.
    25  The same compiler is used for all target operating systems and architectures.
    26  The GOOS and GOARCH environment variables set the desired target.
    27  
    28  Flags:
    29  
    30  	-D path
    31  		Set relative path for local imports.
    32  	-I dir1 -I dir2
    33  		Search for imported packages in dir1, dir2, etc,
    34  		after consulting $GOROOT/pkg/$GOOS_$GOARCH.
    35  	-L
    36  		Show complete file path in error messages.
    37  	-N
    38  		Disable optimizations.
    39  	-S
    40  		Print assembly listing to standard output (code only).
    41  	-S -S
    42  		Print assembly listing to standard output (code and data).
    43  	-V
    44  		Print compiler version and exit.
    45  	-asmhdr file
    46  		Write assembly header to file.
    47  	-complete
    48  		Assume package has no non-Go components.
    49  	-cpuprofile file
    50  		Write a CPU profile for the compilation to file.
    51  	-dynlink
    52  		Allow references to Go symbols in shared libraries (experimental).
    53  	-e
    54  		Remove the limit on the number of errors reported (default limit is 10).
    55  	-h
    56  		Halt with a stack trace at the first error detected.
    57  	-importmap old=new
    58  		Interpret import "old" as import "new" during compilation.
    59  		The option may be repeated to add multiple mappings.
    60  	-installsuffix suffix
    61  		Look for packages in $GOROOT/pkg/$GOOS_$GOARCH_suffix
    62  		instead of $GOROOT/pkg/$GOOS_$GOARCH.
    63  	-largemodel
    64  		Generated code that assumes a large memory model.
    65  	-memprofile file
    66  		Write memory profile for the compilation to file.
    67  	-memprofilerate rate
    68  		Set runtime.MemProfileRate for the compilation to rate.
    69  	-msan
    70  		Insert calls to C/C++ memory sanitizer.
    71  	-nolocalimports
    72  		Disallow local (relative) imports.
    73  	-o file
    74  		Write object to file (default file.o or, with -pack, file.a).
    75  	-p path
    76  		Set expected package import path for the code being compiled,
    77  		and diagnose imports that would cause a circular dependency.
    78  	-pack
    79  		Write a package (archive) file rather than an object file
    80  	-race
    81  		Compile with race detector enabled.
    82  	-trimpath prefix
    83  		Remove prefix from recorded source file paths.
    84  	-u
    85  		Disallow importing packages not marked as safe; implies -nolocalimports.
    86  
    87  There are also a number of debugging flags; run the command with no arguments
    88  for a usage message.
    89  
    90  Compiler Directives
    91  
    92  The compiler accepts compiler directives in the form of // comments at the
    93  beginning of a line. To distinguish them from non-directive comments, the directives
    94  require no space between the slashes and the name of the directive. However, since
    95  they are comments, tools unaware of the directive convention or of a particular
    96  directive can skip over a directive like any other comment.
    97  
    98  	//line path/to/file:linenumber
    99  
   100  The //line directive specifies that the source line that follows should be recorded
   101  as having come from the given file path and line number. Successive lines are
   102  recorded using increasing line numbers, until the next directive. This directive
   103  typically appears in machine-generated code, so that compilers and debuggers
   104  will show lines in the original input to the generator.
   105  
   106  The //line directive is an historical special case; all other directives are of the form
   107  //go:name, indicating that the directive is defined by the Go toolchain.
   108  
   109  	//go:noescape
   110  
   111  The //go:noescape directive specifies that the next declaration in the file, which
   112  must be a func without a body (meaning that it has an implementation not written
   113  in Go) does not allow any of the pointers passed as arguments to escape into the
   114  heap or into the values returned from the function. This information can be used
   115  during the compiler's escape analysis of Go code calling the function.
   116  
   117  	//go:nosplit
   118  
   119  The //go:nosplit directive specifies that the next function declared in the file must
   120  not include a stack overflow check. This is most commonly used by low-level
   121  runtime sources invoked at times when it is unsafe for the calling goroutine to be
   122  preempted.
   123  
   124  	//go:linkname localname importpath.name
   125  
   126  The //go:linkname directive instructs the compiler to use ``importpath.name'' as the
   127  object file symbol name for the variable or function declared as ``localname'' in the
   128  source code. Because this directive can subvert the type system and package
   129  modularity, it is only enabled in files that have imported "unsafe".
   130  */
   131  package main