...
Run Format

Source file src/cmd/compile/doc.go

Documentation: cmd/compile

     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  	-blockprofile file
    48  		Write block profile for the compilation to file.
    49  	-complete
    50  		Assume package has no non-Go components.
    51  	-cpuprofile file
    52  		Write a CPU profile for the compilation to file.
    53  	-dynlink
    54  		Allow references to Go symbols in shared libraries (experimental).
    55  	-e
    56  		Remove the limit on the number of errors reported (default limit is 10).
    57  	-h
    58  		Halt with a stack trace at the first error detected.
    59  	-importmap old=new
    60  		Interpret import "old" as import "new" during compilation.
    61  		The option may be repeated to add multiple mappings.
    62  	-installsuffix suffix
    63  		Look for packages in $GOROOT/pkg/$GOOS_$GOARCH_suffix
    64  		instead of $GOROOT/pkg/$GOOS_$GOARCH.
    65  	-l
    66  		Disable inlining.
    67  	-largemodel
    68  		Generate code that assumes a large memory model.
    69  	-linkobj file
    70  		Write linker-specific object to file and compiler-specific
    71  		object to usual output file (as specified by -o).
    72  		Without this flag, the -o output is a combination of both
    73  		linker and compiler input.
    74  	-memprofile file
    75  		Write memory profile for the compilation to file.
    76  	-memprofilerate rate
    77  		Set runtime.MemProfileRate for the compilation to rate.
    78  	-msan
    79  		Insert calls to C/C++ memory sanitizer.
    80  	-mutexprofile file
    81  		Write mutex profile for the compilation to file.
    82  	-nolocalimports
    83  		Disallow local (relative) imports.
    84  	-o file
    85  		Write object to file (default file.o or, with -pack, file.a).
    86  	-p path
    87  		Set expected package import path for the code being compiled,
    88  		and diagnose imports that would cause a circular dependency.
    89  	-pack
    90  		Write a package (archive) file rather than an object file
    91  	-race
    92  		Compile with race detector enabled.
    93  	-trimpath prefix
    94  		Remove prefix from recorded source file paths.
    95  	-u
    96  		Disallow importing packages not marked as safe; implies -nolocalimports.
    97  
    98  There are also a number of debugging flags; run the command with no arguments
    99  for a usage message.
   100  
   101  Compiler Directives
   102  
   103  The compiler accepts directives in the form of comments.
   104  To distinguish them from non-directive comments, directives
   105  require no space between the comment opening and the name of the directive. However, since
   106  they are comments, tools unaware of the directive convention or of a particular
   107  directive can skip over a directive like any other comment.
   108  */
   109  // Line directives come in several forms:
   110  //
   111  // 	//line :line
   112  // 	//line :line:col
   113  // 	//line filename:line
   114  // 	//line filename:line:col
   115  // 	/*line :line*/
   116  // 	/*line :line:col*/
   117  // 	/*line filename:line*/
   118  // 	/*line filename:line:col*/
   119  //
   120  // In order to be recognized as a line directive, the comment must start with
   121  // //line or /*line followed by a space, and must contain at least one colon.
   122  // The //line form must start at the beginning of a line.
   123  // A line directive specifies the source position for the character immediately following
   124  // the comment as having come from the specified file, line and column:
   125  // For a //line comment, this is the first character of the next line, and
   126  // for a /*line comment this is the character position immediately following the closing */.
   127  // If no filename is given, the recorded filename is empty if there is also no column number;
   128  // otherwise is is the most recently recorded filename (actual filename or filename specified
   129  // by previous line directive).
   130  // If a line directive doesn't specify a column number, the column is "unknown" until
   131  // the next directive and the compiler does not report column numbers for that range.
   132  // The line directive text is interpreted from the back: First the trailing :ddd is peeled
   133  // off from the directive text if ddd is a valid number > 0. Then the second :ddd
   134  // is peeled off the same way if it is valid. Anything before that is considered the filename
   135  // (possibly including blanks and colons). Invalid line or column values are reported as errors.
   136  //
   137  // Examples:
   138  //
   139  //	//line foo.go:10      the filename is foo.go, and the line number is 10 for the next line
   140  //	//line C:foo.go:10    colons are permitted in filenames, here the filename is C:foo.go, and the line is 10
   141  //	//line  a:100 :10     blanks are permitted in filenames, here the filename is " a:100 " (excluding quotes)
   142  //	/*line :10:20*/x      the position of x is in the current file with line number 10 and column number 20
   143  //	/*line foo: 10 */     this comment is recognized as invalid line directive (extra blanks around line number)
   144  //
   145  // Line directives typically appear in machine-generated code, so that compilers and debuggers
   146  // will report positions in the original input to the generator.
   147  /*
   148  The line directive is an historical special case; all other directives are of the form
   149  //go:name and must start at the begnning of a line, indicating that the directive is defined
   150  by the Go toolchain.
   151  
   152  	//go:noescape
   153  
   154  The //go:noescape directive specifies that the next declaration in the file, which
   155  must be a func without a body (meaning that it has an implementation not written
   156  in Go) does not allow any of the pointers passed as arguments to escape into the
   157  heap or into the values returned from the function. This information can be used
   158  during the compiler's escape analysis of Go code calling the function.
   159  
   160  	//go:nosplit
   161  
   162  The //go:nosplit directive specifies that the next function declared in the file must
   163  not include a stack overflow check. This is most commonly used by low-level
   164  runtime sources invoked at times when it is unsafe for the calling goroutine to be
   165  preempted.
   166  
   167  	//go:linkname localname importpath.name
   168  
   169  The //go:linkname directive instructs the compiler to use ``importpath.name'' as the
   170  object file symbol name for the variable or function declared as ``localname'' in the
   171  source code. Because this directive can subvert the type system and package
   172  modularity, it is only enabled in files that have imported "unsafe".
   173  */
   174  package main
   175  

View as plain text