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 -blockprofile file 48 Write block profile for the compilation to file. 49 -complete 50 Assume package has no non-Go components. 51 -cpuprofile file 52 Write a CPU profile for the compilation to file. 53 -dynlink 54 Allow references to Go symbols in shared libraries (experimental). 55 -e 56 Remove the limit on the number of errors reported (default limit is 10). 57 -h 58 Halt with a stack trace at the first error detected. 59 -importmap old=new 60 Interpret import "old" as import "new" during compilation. 61 The option may be repeated to add multiple mappings. 62 -installsuffix suffix 63 Look for packages in $GOROOT/pkg/$GOOS_$GOARCH_suffix 64 instead of $GOROOT/pkg/$GOOS_$GOARCH. 65 -l 66 Disable inlining. 67 -largemodel 68 Generate code that assumes a large memory model. 69 -linkobj file 70 Write linker-specific object to file and compiler-specific 71 object to usual output file (as specified by -o). 72 Without this flag, the -o output is a combination of both 73 linker and compiler input. 74 -memprofile file 75 Write memory profile for the compilation to file. 76 -memprofilerate rate 77 Set runtime.MemProfileRate for the compilation to rate. 78 -msan 79 Insert calls to C/C++ memory sanitizer. 80 -mutexprofile file 81 Write mutex profile for the compilation to file. 82 -nolocalimports 83 Disallow local (relative) imports. 84 -o file 85 Write object to file (default file.o or, with -pack, file.a). 86 -p path 87 Set expected package import path for the code being compiled, 88 and diagnose imports that would cause a circular dependency. 89 -pack 90 Write a package (archive) file rather than an object file 91 -race 92 Compile with race detector enabled. 93 -trimpath prefix 94 Remove prefix from recorded source file paths. 95 -u 96 Disallow importing packages not marked as safe; implies -nolocalimports. 97 98 There are also a number of debugging flags; run the command with no arguments 99 for a usage message. 100 101 Compiler Directives 102 103 The compiler accepts compiler directives in the form of // comments at the 104 beginning of a line. To distinguish them from non-directive comments, the directives 105 require no space between the slashes and the name of the directive. However, since 106 they are comments, tools unaware of the directive convention or of a particular 107 directive can skip over a directive like any other comment. 108 109 //line path/to/file:linenumber 110 111 The //line directive specifies that the source line that follows should be recorded 112 as having come from the given file path and line number. Successive lines are 113 recorded using increasing line numbers, until the next directive. This directive 114 typically appears in machine-generated code, so that compilers and debuggers 115 will show lines in the original input to the generator. 116 117 The //line directive is an historical special case; all other directives are of the form 118 //go:name, indicating that the directive is defined by the Go toolchain. 119 120 //go:noescape 121 122 The //go:noescape directive specifies that the next declaration in the file, which 123 must be a func without a body (meaning that it has an implementation not written 124 in Go) does not allow any of the pointers passed as arguments to escape into the 125 heap or into the values returned from the function. This information can be used 126 during the compiler's escape analysis of Go code calling the function. 127 128 //go:nosplit 129 130 The //go:nosplit directive specifies that the next function declared in the file must 131 not include a stack overflow check. This is most commonly used by low-level 132 runtime sources invoked at times when it is unsafe for the calling goroutine to be 133 preempted. 134 135 //go:linkname localname importpath.name 136 137 The //go:linkname directive instructs the compiler to use ``importpath.name'' as the 138 object file symbol name for the variable or function declared as ``localname'' in the 139 source code. Because this directive can subvert the type system and package 140 modularity, it is only enabled in files that have imported "unsafe". 141 */ 142 package main 143
