doc.go

     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  	-asan
    48  		Insert calls to C/C++ address sanitizer.
    49  	-buildid id
    50  		Record id as the build id in the export metadata.
    51  	-blockprofile file
    52  		Write block profile for the compilation to file.
    53  	-c int
    54  		Concurrency during compilation. Set 1 for no concurrency (default is 1).
    55  	-complete
    56  		Assume package has no non-Go components.
    57  	-cpuprofile file
    58  		Write a CPU profile for the compilation to file.
    59  	-dynlink
    60  		Allow references to Go symbols in shared libraries (experimental).
    61  	-e
    62  		Remove the limit on the number of errors reported (default limit is 10).
    63  	-goversion string
    64  		Specify required go tool version of the runtime.
    65  		Exits when the runtime go version does not match goversion.
    66  	-h
    67  		Halt with a stack trace at the first error detected.
    68  	-importcfg file
    69  		Read import configuration from file.
    70  		In the file, set importmap, packagefile to specify import resolution.
    71  	-importmap old=new
    72  		Interpret import "old" as import "new" during compilation.
    73  		The option may be repeated to add multiple mappings.
    74  	-installsuffix suffix
    75  		Look for packages in $GOROOT/pkg/$GOOS_$GOARCH_suffix
    76  		instead of $GOROOT/pkg/$GOOS_$GOARCH.
    77  	-l
    78  		Disable inlining.
    79  	-lang version
    80  		Set language version to compile, as in -lang=go1.12.
    81  		Default is current version.
    82  	-linkobj file
    83  		Write linker-specific object to file and compiler-specific
    84  		object to usual output file (as specified by -o).
    85  		Without this flag, the -o output is a combination of both
    86  		linker and compiler input.
    87  	-m
    88  		Print optimization decisions. Higher values or repetition
    89  		produce more detail.
    90  	-memprofile file
    91  		Write memory profile for the compilation to file.
    92  	-memprofilerate rate
    93  		Set runtime.MemProfileRate for the compilation to rate.
    94  	-msan
    95  		Insert calls to C/C++ memory sanitizer.
    96  	-mutexprofile file
    97  		Write mutex profile for the compilation to file.
    98  	-nolocalimports
    99  		Disallow local (relative) imports.
   100  	-o file
   101  		Write object to file (default file.o or, with -pack, file.a).
   102  	-p path
   103  		Set expected package import path for the code being compiled,
   104  		and diagnose imports that would cause a circular dependency.
   105  	-pack
   106  		Write a package (archive) file rather than an object file
   107  	-race
   108  		Compile with race detector enabled.
   109  	-s
   110  		Warn about composite literals that can be simplified.
   111  	-shared
   112  		Generate code that can be linked into a shared library.
   113  	-spectre list
   114  		Enable spectre mitigations in list (all, index, ret).
   115  	-traceprofile file
   116  		Write an execution trace to file.
   117  	-trimpath prefix
   118  		Remove prefix from recorded source file paths.
   119  
   120  Flags related to debugging information:
   121  
   122  	-dwarf
   123  		Generate DWARF symbols.
   124  	-dwarflocationlists
   125  		Add location lists to DWARF in optimized mode.
   126  	-gendwarfinl int
   127  		Generate DWARF inline info records (default 2).
   128  
   129  Flags to debug the compiler itself:
   130  
   131  	-E
   132  		Debug symbol export.
   133  	-K
   134  		Debug missing line numbers.
   135  	-d list
   136  		Print debug information about items in list. Try -d help for further information.
   137  	-live
   138  		Debug liveness analysis.
   139  	-v
   140  		Increase debug verbosity.
   141  	-%
   142  		Debug non-static initializers.
   143  	-W
   144  		Debug parse tree after type checking.
   145  	-f
   146  		Debug stack frames.
   147  	-i
   148  		Debug line number stack.
   149  	-j
   150  		Debug runtime-initialized variables.
   151  	-r
   152  		Debug generated wrappers.
   153  	-w
   154  		Debug type checking.
   155  
   156  Compiler Directives
   157  
   158  The compiler accepts directives in the form of comments.
   159  To distinguish them from non-directive comments, directives
   160  require no space between the comment opening and the name of the directive. However, since
   161  they are comments, tools unaware of the directive convention or of a particular
   162  directive can skip over a directive like any other comment.
   163  */
   164  // Line directives come in several forms:
   165  //
   166  // 	//line :line
   167  // 	//line :line:col
   168  // 	//line filename:line
   169  // 	//line filename:line:col
   170  // 	/*line :line*/
   171  // 	/*line :line:col*/
   172  // 	/*line filename:line*/
   173  // 	/*line filename:line:col*/
   174  //
   175  // In order to be recognized as a line directive, the comment must start with
   176  // //line or /*line followed by a space, and must contain at least one colon.
   177  // The //line form must start at the beginning of a line.
   178  // A line directive specifies the source position for the character immediately following
   179  // the comment as having come from the specified file, line and column:
   180  // For a //line comment, this is the first character of the next line, and
   181  // for a /*line comment this is the character position immediately following the closing */.
   182  // If no filename is given, the recorded filename is empty if there is also no column number;
   183  // otherwise it is the most recently recorded filename (actual filename or filename specified
   184  // by previous line directive).
   185  // If a line directive doesn't specify a column number, the column is "unknown" until
   186  // the next directive and the compiler does not report column numbers for that range.
   187  // The line directive text is interpreted from the back: First the trailing :ddd is peeled
   188  // off from the directive text if ddd is a valid number > 0. Then the second :ddd
   189  // is peeled off the same way if it is valid. Anything before that is considered the filename
   190  // (possibly including blanks and colons). Invalid line or column values are reported as errors.
   191  //
   192  // Examples:
   193  //
   194  //	//line foo.go:10      the filename is foo.go, and the line number is 10 for the next line
   195  //	//line C:foo.go:10    colons are permitted in filenames, here the filename is C:foo.go, and the line is 10
   196  //	//line  a:100 :10     blanks are permitted in filenames, here the filename is " a:100 " (excluding quotes)
   197  //	/*line :10:20*/x      the position of x is in the current file with line number 10 and column number 20
   198  //	/*line foo: 10 */     this comment is recognized as invalid line directive (extra blanks around line number)
   199  //
   200  // Line directives typically appear in machine-generated code, so that compilers and debuggers
   201  // will report positions in the original input to the generator.
   202  /*
   203  The line directive is a historical special case; all other directives are of the form
   204  //go:name, indicating that they are defined by the Go toolchain.
   205  Each directive must be placed its own line, with only leading spaces and tabs
   206  allowed before the comment.
   207  Each directive applies to the Go code that immediately follows it,
   208  which typically must be a declaration.
   209  
   210  	//go:noescape
   211  
   212  The //go:noescape directive must be followed by a function declaration without
   213  a body (meaning that the function has an implementation not written in Go).
   214  It specifies that the function does not allow any of the pointers passed as
   215  arguments to escape into the heap or into the values returned from the function.
   216  This information can be used during the compiler's escape analysis of Go code
   217  calling the function.
   218  
   219  	//go:uintptrescapes
   220  
   221  The //go:uintptrescapes directive must be followed by a function declaration.
   222  It specifies that the function's uintptr arguments may be pointer values
   223  that have been converted to uintptr and must be treated as such by the
   224  garbage collector. The conversion from pointer to uintptr must appear in
   225  the argument list of any call to this function. This directive is necessary
   226  for some low-level system call implementations and should be avoided otherwise.
   227  
   228  	//go:noinline
   229  
   230  The //go:noinline directive must be followed by a function declaration.
   231  It specifies that calls to the function should not be inlined, overriding
   232  the compiler's usual optimization rules. This is typically only needed
   233  for special runtime functions or when debugging the compiler.
   234  
   235  	//go:norace
   236  
   237  The //go:norace directive must be followed by a function declaration.
   238  It specifies that the function's memory accesses must be ignored by the
   239  race detector. This is most commonly used in low-level code invoked
   240  at times when it is unsafe to call into the race detector runtime.
   241  
   242  	//go:nosplit
   243  
   244  The //go:nosplit directive must be followed by a function declaration.
   245  It specifies that the function must omit its usual stack overflow check.
   246  This is most commonly used by low-level runtime code invoked
   247  at times when it is unsafe for the calling goroutine to be preempted.
   248  
   249  	//go:linkname localname [importpath.name]
   250  
   251  This special directive does not apply to the Go code that follows it.
   252  Instead, the //go:linkname directive instructs the compiler to use ``importpath.name''
   253  as the object file symbol name for the variable or function declared as ``localname''
   254  in the source code.
   255  If the ``importpath.name'' argument is omitted, the directive uses the
   256  symbol's default object file symbol name and only has the effect of making
   257  the symbol accessible to other packages.
   258  Because this directive can subvert the type system and package
   259  modularity, it is only enabled in files that have imported "unsafe".
   260  */
   261  package main
   262
View as plain text