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 -largemodel 81 Generate code that assumes a large memory model. 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. 89 -memprofile file 90 Write memory profile for the compilation to file. 91 -memprofilerate rate 92 Set runtime.MemProfileRate for the compilation to rate. 93 -msan 94 Insert calls to C/C++ memory sanitizer. 95 -mutexprofile file 96 Write mutex profile for the compilation to file. 97 -nolocalimports 98 Disallow local (relative) imports. 99 -o file 100 Write object to file (default file.o or, with -pack, file.a). 101 -p path 102 Set expected package import path for the code being compiled, 103 and diagnose imports that would cause a circular dependency. 104 -pack 105 Write a package (archive) file rather than an object file 106 -race 107 Compile with race detector enabled. 108 -s 109 Warn about composite literals that can be simplified. 110 -shared 111 Generate code that can be linked into a shared library. 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 an historical special case; all other directives are of the form 201 //go:name and must start at the beginning of a line, indicating that the directive is defined 202 by the Go toolchain. 203 204 //go:noescape 205 206 The //go:noescape directive specifies that the next declaration in the file, which 207 must be a func without a body (meaning that it has an implementation not written 208 in Go) does not allow any of the pointers passed as arguments to escape into the 209 heap or into the values returned from the function. This information can be used 210 during the compiler's escape analysis of Go code calling the function. 211 212 //go:nosplit 213 214 The //go:nosplit directive specifies that the next function declared in the file must 215 not include a stack overflow check. This is most commonly used by low-level 216 runtime sources invoked at times when it is unsafe for the calling goroutine to be 217 preempted. 218 219 //go:linkname localname [importpath.name] 220 221 The //go:linkname directive instructs the compiler to use ``importpath.name'' as the 222 object file symbol name for the variable or function declared as ``localname'' in the 223 source code. 224 If the ``importpath.name'' argument is omitted, the directive uses the 225 symbol's default object file symbol name and only has the effect of making 226 the symbol accessible to other packages. 227 Because this directive can subvert the type system and package 228 modularity, it is only enabled in files that have imported "unsafe". 229 */ 230 package main 231