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 To distinguish them from non-directive comments, directives 157 require no space between the comment opening and the name of the directive. However, since 158 they are comments, tools unaware of the directive convention or of a particular 159 directive can skip over a directive like any other comment. 160 */ 161 // Line directives come in several forms: 162 // 163 // //line :line 164 // //line :line:col 165 // //line filename:line 166 // //line filename:line:col 167 // /*line :line*/ 168 // /*line :line:col*/ 169 // /*line filename:line*/ 170 // /*line filename:line:col*/ 171 // 172 // In order to be recognized as a line directive, the comment must start with 173 // //line or /*line followed by a space, and must contain at least one colon. 174 // The //line form must start at the beginning of a line. 175 // A line directive specifies the source position for the character immediately following 176 // the comment as having come from the specified file, line and column: 177 // For a //line comment, this is the first character of the next line, and 178 // for a /*line comment this is the character position immediately following the closing */. 179 // If no filename is given, the recorded filename is empty if there is also no column number; 180 // otherwise it is the most recently recorded filename (actual filename or filename specified 181 // by previous line directive). 182 // If a line directive doesn't specify a column number, the column is "unknown" until 183 // the next directive and the compiler does not report column numbers for that range. 184 // The line directive text is interpreted from the back: First the trailing :ddd is peeled 185 // off from the directive text if ddd is a valid number > 0. Then the second :ddd 186 // is peeled off the same way if it is valid. Anything before that is considered the filename 187 // (possibly including blanks and colons). Invalid line or column values are reported as errors. 188 // 189 // Examples: 190 // 191 // //line foo.go:10 the filename is foo.go, and the line number is 10 for the next line 192 // //line C:foo.go:10 colons are permitted in filenames, here the filename is C:foo.go, and the line is 10 193 // //line a:100 :10 blanks are permitted in filenames, here the filename is " a:100 " (excluding quotes) 194 // /*line :10:20*/x the position of x is in the current file with line number 10 and column number 20 195 // /*line foo: 10 */ this comment is recognized as invalid line directive (extra blanks around line number) 196 // 197 // Line directives typically appear in machine-generated code, so that compilers and debuggers 198 // will report positions in the original input to the generator. 199 /* 200 The line directive is a historical special case; all other directives are of the form 201 //go:name, indicating that they are defined by the Go toolchain. 202 Each directive must be placed its own line, with only leading spaces and tabs 203 allowed before the comment. 204 Each directive applies to the Go code that immediately follows it, 205 which typically must be a declaration. 206 207 //go:noescape 208 209 The //go:noescape directive must be followed by a function declaration without 210 a body (meaning that the function has an implementation not written in Go). 211 It specifies that the function does not allow any of the pointers passed as 212 arguments to escape into the heap or into the values returned from the function. 213 This information can be used during the compiler's escape analysis of Go code 214 calling the function. 215 216 //go:uintptrescapes 217 218 The //go:uintptrescapes directive must be followed by a function declaration. 219 It specifies that the function's uintptr arguments may be pointer values that 220 have been converted to uintptr and must be on the heap and kept alive for the 221 duration of the call, even though from the types alone it would appear that the 222 object is no longer needed during the call. The conversion from pointer to 223 uintptr must appear in the argument list of any call to this function. This 224 directive is necessary for some low-level system call implementations and 225 should be avoided otherwise. 226 227 //go:noinline 228 229 The //go:noinline directive must be followed by a function declaration. 230 It specifies that calls to the function should not be inlined, overriding 231 the compiler's usual optimization rules. This is typically only needed 232 for special runtime functions or when debugging the compiler. 233 234 //go:norace 235 236 The //go:norace directive must be followed by a function declaration. 237 It specifies that the function's memory accesses must be ignored by the 238 race detector. This is most commonly used in low-level code invoked 239 at times when it is unsafe to call into the race detector runtime. 240 241 //go:nosplit 242 243 The //go:nosplit directive must be followed by a function declaration. 244 It specifies that the function must omit its usual stack overflow check. 245 This is most commonly used by low-level runtime code invoked 246 at times when it is unsafe for the calling goroutine to be preempted. 247 248 //go:linkname localname [importpath.name] 249 250 The //go:linkname directive conventionally precedes the var or func 251 declaration named by ``localname``, though its position does not 252 change its effect. 253 This directive determines the object-file symbol used for a Go var or 254 func declaration, allowing two Go symbols to alias the same 255 object-file symbol, thereby enabling one package to access a symbol in 256 another package even when this would violate the usual encapsulation 257 of unexported declarations, or even type safety. 258 For that reason, it is only enabled in files that have imported "unsafe". 259 260 It may be used in two scenarios. Let's assume that package upper 261 imports package lower, perhaps indirectly. In the first scenario, 262 package lower defines a symbol whose object file name belongs to 263 package upper. Both packages contain a linkname directive: package 264 lower uses the two-argument form and package upper uses the 265 one-argument form. In the example below, lower.f is an alias for the 266 function upper.g: 267 268 package upper 269 import _ "unsafe" 270 //go:linkname g 271 func g() 272 273 package lower 274 import _ "unsafe" 275 //go:linkname f upper.g 276 func f() { ... } 277 278 The linkname directive in package upper suppresses the usual error for 279 a function that lacks a body. (That check may alternatively be 280 suppressed by including a .s file, even an empty one, in the package.) 281 282 In the second scenario, package upper unilaterally creates an alias 283 for a symbol in package lower. In the example below, upper.g is an alias 284 for the function lower.f. 285 286 package upper 287 import _ "unsafe" 288 //go:linkname g lower.f 289 func g() 290 291 package lower 292 func f() { ... } 293 294 The declaration of lower.f may also have a linkname directive with a 295 single argument, f. This is optional, but helps alert the reader that 296 the function is accessed from outside the package. 297 298 //go:wasmimport importmodule importname 299 300 The //go:wasmimport directive is wasm-only and must be followed by a 301 function declaration. 302 It specifies that the function is provided by a wasm module identified 303 by ``importmodule`` and ``importname``. 304 305 //go:wasmimport a_module f 306 func g() 307 308 The types of parameters and return values to the Go function are translated to 309 Wasm according to the following table: 310 311 Go types Wasm types 312 int32, uint32 i32 313 int64, uint64 i64 314 float32 f32 315 float64 f64 316 unsafe.Pointer i32 317 318 Any other parameter types are disallowed by the compiler. 319 320 */ 321 package main 322