Skip to main content
The Go compiler, invoked as go tool compile, compiles a single Go package comprising the files named on the command line. It writes object files that can be combined into packages or passed to the linker.

​
Overview

The compiler is typically invoked indirectly through the go build command, but can be used directly for specialized build processes or when debugging compilation issues.
Most users should use go build instead of calling the compiler directly. Direct compiler invocation is primarily for advanced use cases and build system integration.

​
Usage

go tool compile [flags] file...
The specified files must be Go source files and all part of the same package. The same compiler is used for all target operating systems and architectures.

​
Basic Flags

​
Output Control

​
-o
file
Write object to file (default: file.o or with -pack, file.a)
go tool compile -o output.o main.go
​
-pack
flag
Write a package (archive) file rather than an object file
go tool compile -pack -o lib.a *.go
​
-S
flag
Print assembly listing to standard output. Use -S -S to include data sections.
go tool compile -S main.go

​
Path and Import Flags

​
-D
path
Set relative path for local imports
​
-I
directory
Search for imported packages in specified directories (can be repeated)
go tool compile -I /path/to/packages main.go
​
-p
path
Set expected package import path for the code being compiled
go tool compile -p example.com/myapp main.go

​
Optimization Flags

​
-N
flag
Disable optimizations. Useful for debugging.
go tool compile -N -l main.go  # -l disables inlining
​
-l
flag
Disable inlining. Combining with -N provides better debugging experience.
​
-m
flag
Print optimization decisions. Use multiple times for more detail.
go tool compile -m -m main.go  # More verbose output

​
Common Workflows

​
Viewing Assembly Output

1

Generate Assembly Listing

Compile and view assembly code:
go tool compile -S main.go > main.s
2

View Specific Function

Filter assembly for a specific function:
go tool compile -S main.go | grep -A 20 "TEXT.*myFunction"
3

Include Data Sections

View both code and data sections:
go tool compile -S -S main.go

​
Analyzing Optimizations

# See what functions are inlined
go tool compile -m main.go

# More detailed inlining info
go tool compile -m -m main.go

​
Advanced Flags

​
Debug and Analysis

​
-race
flag
Compile with race detector enabled
go tool compile -race main.go
​
-asan
flag
Insert calls to C/C++ address sanitizer (Linux only)
​
-msan
flag
Insert calls to C/C++ memory sanitizer (Linux only)

​
Build Configuration

​
-buildid
id
Record id as the build id in the export metadata
go tool compile -buildid=myBuildId main.go
​
-importcfg
file
Read import configuration from file. Used to specify import resolution.
​
-embedcfg
file
Read go:embed configuration from file. Required if any //go:embed directives are used.

​
Language Version

​
-lang
version
Set language version to compile, as in -lang=go1.21
go tool compile -lang=go1.20 main.go
​
-goversion
string
Specify required go tool version of the runtime

​
DWARF Debug Information

​
-dwarf
flag
Generate DWARF symbols for debugging
​
-dwarflocationlists
flag
Add location lists to DWARF in optimized mode
​
-gendwarfinl
int
Generate DWARF inline info records (default: 2)

​
Profiling Flags

# CPU profiling during compilation
go tool compile -cpuprofile cpu.prof main.go

# Memory profiling
go tool compile -memprofile mem.prof main.go

# Block profiling
go tool compile -blockprofile block.prof main.go

# Mutex profiling
go tool compile -mutexprofile mutex.prof main.go

​
Compiler Debugging Flags

These flags are for debugging the compiler itself and are rarely needed by regular users.
​
-d
list
Print debug information about items in list
go tool compile -d=ssa/check_bce/debug=1 main.go
go tool compile -d=help  # List available debug options
​
-live
flag
Debug liveness analysis
​
-v
flag
Increase debug verbosity
​
-h
flag
Halt with a stack trace at the first error detected
​
-e
flag
Remove the limit on the number of errors reported (default limit is 10)

​
Examples

​
Basic Compilation

# Compile to object file
go tool compile main.go
# Creates main.o

# Compile with custom output
go tool compile -o myapp.o main.go

​
Cross-Compilation

# Set target architecture
GOOS=linux GOARCH=amd64 go tool compile main.go

# Compile for different platforms
GOOS=windows GOARCH=amd64 go tool compile -o main.obj main.go
GOOS=darwin GOARCH=arm64 go tool compile main.go

​
Debugging Compilation

# Better debugging experience
go tool compile -N -l main.go

# With DWARF symbols
go tool compile -N -l -dwarf main.go

​
Using with go build

Pass compiler flags through go build using -gcflags: 
# View optimization decisions
go build -gcflags='-m' .

# Disable optimizations for debugging
go build -gcflags='-N -l' .

# View assembly for specific package
go build -gcflags='-S' example.com/myapp

# Multiple flags
go build -gcflags='-m -m -l' .

​
Compiler Directives

The compiler accepts directives in the form of comments:

​
Function Directives

//go:noinline
func myFunction() {
    // This function will not be inlined
}

//go:nosplit
func criticalFunction() {
    // Omits stack overflow check
}

//go:noescape
func externalFunc(p *int)

//go:linkname localname importpath.name

​
Line Directives

//line filename:line
//line filename:line:col
/*line filename:line*/

​
WebAssembly Directives

//go:wasmimport module_name function_name
func importedWasmFunc()

//go:wasmexport export_name
func exportedWasmFunc() {
    // Function body
}

​
Compiler Internals

​
Compilation Phases

1

Parsing

Source code is parsed into an Abstract Syntax Tree (AST)
2

Type Checking

The AST is type-checked and decorated with type information
3

IR Generation

The AST is converted to intermediate representation (IR)
4

Optimizations

Various optimizations are applied (inlining, escape analysis, etc.)
5

SSA Generation

IR is lowered to Static Single Assignment (SSA) form
6

Code Generation

Machine code is generated from SSA
7

Object File Writing

Final object file is written with export data

​
Performance Tuning

​
Compilation Speed

# Increase concurrency
go tool compile -c 8 *.go

# Profile compilation time
go tool compile -cpuprofile cpu.prof main.go

​
Binary Size

# Remove debug information
go build -ldflags='-s -w' .

# Use -trimpath to remove paths
go build -trimpath .

​
Troubleshooting

Use -e flag to see all errors at once:
go tool compile -e main.go
Disable optimizations and check if issue persists:
go build -gcflags='-N -l' .
Check inlining decisions:
go build -gcflags='-m -m' . 2>&1 | grep -i inline

​
See Also

Building Programs

Using go build command

go Command

Overview of go command

Build docs developers (and LLMs) love

Get started for freeTalk to us