Source file src/cmd/compile/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  	-installsuffix suffix
    72  		Look for packages in $GOROOT/pkg/$GOOS_$GOARCH_suffix
    73  		instead of $GOROOT/pkg/$GOOS_$GOARCH.
    74  	-l
    75  		Disable inlining.
    76  	-lang version
    77  		Set language version to compile, as in -lang=go1.12.
    78  		Default is current version.
    79  	-linkobj file
    80  		Write linker-specific object to file and compiler-specific
    81  		object to usual output file (as specified by -o).
    82  		Without this flag, the -o output is a combination of both
    83  		linker and compiler input.
    84  	-m
    85  		Print optimization decisions. Higher values or repetition
    86  		produce more detail.
    87  	-memprofile file
    88  		Write memory profile for the compilation to file.
    89  	-memprofilerate rate
    90  		Set runtime.MemProfileRate for the compilation to rate.
    91  	-msan
    92  		Insert calls to C/C++ memory sanitizer.
    93  	-mutexprofile file
    94  		Write mutex profile for the compilation to file.
    95  	-nolocalimports
    96  		Disallow local (relative) imports.
    97  	-o file
    98  		Write object to file (default file.o or, with -pack, file.a).
    99  	-p path
   100  		Set expected package import path for the code being compiled,
   101  		and diagnose imports that would cause a circular dependency.
   102  	-pack
   103  		Write a package (archive) file rather than an object file
   104  	-race
   105  		Compile with race detector enabled.
   106  	-s
   107  		Warn about composite literals that can be simplified.
   108  	-shared
   109  		Generate code that can be linked into a shared library.
   110  	-spectre list
   111  		Enable spectre mitigations in list (all, index, ret).
   112  	-traceprofile file
   113  		Write an execution trace to file.
   114  	-trimpath prefix
   115  		Remove prefix from recorded source file paths.
   116  
   117  Flags related to debugging information:
   118  
   119  	-dwarf
   120  		Generate DWARF symbols.
   121  	-dwarflocationlists
   122  		Add location lists to DWARF in optimized mode.
   123  	-gendwarfinl int
   124  		Generate DWARF inline info records (default 2).
   125  
   126  Flags to debug the compiler itself:
   127  
   128  	-E
   129  		Debug symbol export.
   130  	-K
   131  		Debug missing line numbers.
   132  	-d list
   133  		Print debug information about items in list. Try -d help for further information.
   134  	-live
   135  		Debug liveness analysis.
   136  	-v
   137  		Increase debug verbosity.
   138  	-%
   139  		Debug non-static initializers.
   140  	-W
   141  		Debug parse tree after type checking.
   142  	-f
   143  		Debug stack frames.
   144  	-i
   145  		Debug line number stack.
   146  	-j
   147  		Debug runtime-initialized variables.
   148  	-r
   149  		Debug generated wrappers.
   150  	-w
   151  		Debug type checking.
   152  
   153  # Compiler Directives
   154  
   155  The compiler accepts directives in the form of comments.
   156  Each directive must be placed its own line, with only leading spaces and tabs
   157  allowed before the comment, and there must be no space between the comment
   158  opening and the name of the directive, to distinguish it from a regular comment.
   159  Tools unaware of the directive convention or of a particular
   160  directive can skip over a directive like any other comment.
   161  
   162  Other than the line directive, which is a historical special case;
   163  all other compiler directives are of the form
   164  //go:name, indicating that they are defined by the Go toolchain.
   165  */
   166  // # Line Directives
   167  //
   168  // Line directives come in several forms:
   169  //
   170  // 	//line :line
   171  // 	//line :line:col
   172  // 	//line filename:line
   173  // 	//line filename:line:col
   174  // 	/*line :line*/
   175  // 	/*line :line:col*/
   176  // 	/*line filename:line*/
   177  // 	/*line filename:line:col*/
   178  //
   179  // In order to be recognized as a line directive, the comment must start with
   180  // //line or /*line followed by a space, and must contain at least one colon.
   181  // The //line form must start at the beginning of a line.
   182  // A line directive specifies the source position for the character immediately following
   183  // the comment as having come from the specified file, line and column:
   184  // For a //line comment, this is the first character of the next line, and
   185  // for a /*line comment this is the character position immediately following the closing */.
   186  // If no filename is given, the recorded filename is empty if there is also no column number;
   187  // otherwise it is the most recently recorded filename (actual filename or filename specified
   188  // by previous line directive).
   189  // If a line directive doesn't specify a column number, the column is "unknown" until
   190  // the next directive and the compiler does not report column numbers for that range.
   191  // The line directive text is interpreted from the back: First the trailing :ddd is peeled
   192  // off from the directive text if ddd is a valid number > 0. Then the second :ddd
   193  // is peeled off the same way if it is valid. Anything before that is considered the filename
   194  // (possibly including blanks and colons). Invalid line or column values are reported as errors.
   195  //
   196  // Examples:
   197  //
   198  //	//line foo.go:10      the filename is foo.go, and the line number is 10 for the next line
   199  //	//line C:foo.go:10    colons are permitted in filenames, here the filename is C:foo.go, and the line is 10
   200  //	//line  a:100 :10     blanks are permitted in filenames, here the filename is " a:100 " (excluding quotes)
   201  //	/*line :10:20*/x      the position of x is in the current file with line number 10 and column number 20
   202  //	/*line foo: 10 */     this comment is recognized as invalid line directive (extra blanks around line number)
   203  //
   204  // Line directives typically appear in machine-generated code, so that compilers and debuggers
   205  // will report positions in the original input to the generator.
   206  /*
   207  # Function Directives
   208  
   209  A function directive applies to the Go function that immediately follows it.
   210  
   211  	//go:noescape
   212  
   213  The //go:noescape directive must be followed by a function declaration without
   214  a body (meaning that the function has an implementation not written in Go).
   215  It specifies that the function does not allow any of the pointers passed as
   216  arguments to escape into the heap or into the values returned from the function.
   217  This information can be used during the compiler's escape analysis of Go code
   218  calling the function.
   219  
   220  	//go:uintptrescapes
   221  
   222  The //go:uintptrescapes directive must be followed by a function declaration.
   223  It specifies that the function's uintptr arguments may be pointer values that
   224  have been converted to uintptr and must be on the heap and kept alive for the
   225  duration of the call, even though from the types alone it would appear that the
   226  object is no longer needed during the call. The conversion from pointer to
   227  uintptr must appear in the argument list of any call to this function. This
   228  directive is necessary for some low-level system call implementations and
   229  should be avoided otherwise.
   230  
   231  	//go:noinline
   232  
   233  The //go:noinline directive must be followed by a function declaration.
   234  It specifies that calls to the function should not be inlined, overriding
   235  the compiler's usual optimization rules. This is typically only needed
   236  for special runtime functions or when debugging the compiler.
   237  
   238  	//go:norace
   239  
   240  The //go:norace directive must be followed by a function declaration.
   241  It specifies that the function's memory accesses must be ignored by the
   242  race detector. This is most commonly used in low-level code invoked
   243  at times when it is unsafe to call into the race detector runtime.
   244  
   245  	//go:nosplit
   246  
   247  The //go:nosplit directive must be followed by a function declaration.
   248  It specifies that the function must omit its usual stack overflow check.
   249  This is most commonly used by low-level runtime code invoked
   250  at times when it is unsafe for the calling goroutine to be preempted.
   251  
   252  # Linkname Directive
   253  
   254  	//go:linkname localname [importpath.name]
   255  
   256  The //go:linkname directive conventionally precedes the var or func
   257  declaration named by ``localname``, though its position does not
   258  change its effect.
   259  This directive determines the object-file symbol used for a Go var or
   260  func declaration, allowing two Go symbols to alias the same
   261  object-file symbol, thereby enabling one package to access a symbol in
   262  another package even when this would violate the usual encapsulation
   263  of unexported declarations, or even type safety.
   264  For that reason, it is only enabled in files that have imported "unsafe".
   265  
   266  It may be used in two scenarios. Let's assume that package upper
   267  imports package lower, perhaps indirectly. In the first scenario,
   268  package lower defines a symbol whose object file name belongs to
   269  package upper. Both packages contain a linkname directive: package
   270  lower uses the two-argument form and package upper uses the
   271  one-argument form. In the example below, lower.f is an alias for the
   272  function upper.g:
   273  
   274      package upper
   275      import _ "unsafe"
   276      //go:linkname g
   277      func g()
   278  
   279      package lower
   280      import _ "unsafe"
   281      //go:linkname f upper.g
   282      func f() { ... }
   283  
   284  The linkname directive in package upper suppresses the usual error for
   285  a function that lacks a body. (That check may alternatively be
   286  suppressed by including a .s file, even an empty one, in the package.)
   287  
   288  In the second scenario, package upper unilaterally creates an alias
   289  for a symbol in package lower. In the example below, upper.g is an alias
   290  for the function lower.f.
   291  
   292      package upper
   293      import _ "unsafe"
   294      //go:linkname g lower.f
   295      func g()
   296  
   297      package lower
   298      func f() { ... }
   299  
   300  The declaration of lower.f may also have a linkname directive with a
   301  single argument, f. This is optional, but helps alert the reader that
   302  the function is accessed from outside the package.
   303  
   304  # WebAssembly Directives
   305  
   306  	//go:wasmimport importmodule importname
   307  
   308  The //go:wasmimport directive is wasm-only and must be followed by a
   309  function declaration with no body.
   310  It specifies that the function is provided by a wasm module identified
   311  by ``importmodule'' and ``importname''. For example,
   312  
   313  	//go:wasmimport a_module f
   314  	func g()
   315  
   316  causes g to refer to the WebAssembly function f from module a_module.
   317  
   318  	//go:wasmexport exportname
   319  
   320  The //go:wasmexport directive is wasm-only and must be followed by a
   321  function definition.
   322  It specifies that the function is exported to the wasm host as ``exportname''.
   323  For example,
   324  
   325  	//go:wasmexport h
   326  	func hWasm() { ... }
   327  
   328  make Go function hWasm available outside this WebAssembly module as h.
   329  
   330  For both go:wasmimport and go:wasmexport,
   331  the types of parameters and return values to the Go function are translated to
   332  Wasm according to the following table:
   333  
   334      Go types        Wasm types
   335      bool            i32
   336      int32, uint32   i32
   337      int64, uint64   i64
   338      float32         f32
   339      float64         f64
   340      unsafe.Pointer  i32
   341      pointer         i32 (more restrictions below)
   342      string          (i32, i32) (only permitted as a parameters, not a result)
   343  
   344  Any other parameter types are disallowed by the compiler.
   345  
   346  For a pointer type, its element type must be a bool, int8, uint8, int16, uint16,
   347  int32, uint32, int64, uint64, float32, float64, an array whose element type is
   348  a permitted pointer element type, or a struct, which, if non-empty, embeds
   349  [structs.HostLayout], and contains only fields whose types are permitted pointer
   350  element types.
   351  */
   352  package main
   353  

View as plain text