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