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