-
Notifications
You must be signed in to change notification settings - Fork 16
/
Copy pathgo_build.cli.txt
413 lines (331 loc) · 21.5 KB
/
go_build.cli.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
┏━━━━━━━━━━━━━━┓
┃ GO_BUILD ┃
┗━━━━━━━━━━━━━━┛
VERSION ==> #See Go language
RELATED DOCUMENTATION ==> #See Go language
┌───────────┐
│ BUILD │
└───────────┘
go build IMPORT_PATHS #Compile *.go:
# - single main PACKAGE: to BINARY
# - multiple PACKAGEs, or non-main PACKAGE: build but discard result, i.e. just checks it can be built
#Executable name is:
# - if argument is FILE.go..., first FILE name
# - if module-aware, MODULE_PATH last part
# - otherwise, DIR name
#Always ignored: *_test.go, .*.go, _*.go, testdata/**.go
go tool compile|link #Can use -installsuffix|linkshared
go tool compile|asm #Can use -trimpath
go tool compile #Can use -p (named -c and defaulting to 1)
go tool link #Can use -buildmode (def: 'exe')
-o FILE|DIR #Output BINARY path
-installsuffix STR #Prepend STR to installation DIR name
#Automatically done by:
# - "-race": -race flag
# - "-msan": -msan flag
# - -buildmode flag
-n #Dry run
-v #Verbose: print PACKAGE names
-x #Print the commands.
-p NUM #Max number of processes in parallel. Def: number of CPUs
-buildmode=STR #Among:
# - "default": main PACKAGEs into BINARY, non-main PACKAGEs into *.a
# - "archive": only non-main PACKAGEs into *.a (static library)
# - "shared": only non-main PACKAGEs into a shared library
# - "exe": only main PACKAGEs into BINARY
# - "pie": only main PACKAGEs into BINARY, using position idependent executables (PIE)
# - "plugin": only main PACKAGEs into a Go plugin
-linkshared #Links to dependencies dynamically instead of statically
#Much smaller executable size.
#Requires using -buildmode=shared first
go tool compile|asm -shared #Create shared library
go tool compile|asm -dynlink #Allow shared libraries to use Go variables
-trimpath #Binaries contain source files absolute paths, for debugging.
#This replaces the beginning of those absolute paths with the relevant IMPORT_PATH
# - including for standard library
#Goal: make the executable binary identical even on different machines
#Does not modify "PATH" in source files themselves.
┌────────────────┐
│ BUILD TAGS │
└────────────────┘
// +build ALL_CONSTRAINTS #"Build constraint|tag".
#Comment in source code applying to whole file
# - must be at top of file (except other comments or blank lines)
# - must be followed by a blank line
#Skips building the file unless STR condition matches
#Syntax:
# - ALL_CONSTRAINTS: CONSTRAINTS ... (or'd)
# - CONSTRAINTS: [!]CONSTRAINT,... (and'd, not'd)
#If several comments, and'd
#Available CONSTRAINT:
# - any value of runtime.GOOS|GOARCH|Compiler
# - goVERSION (>=)
# - cgo
# - any BUILD_TAG passed to -tags BUILD_TAG,...
# - by convention, "ignore" is kept to mean to never build a file
*[_GOOS][_GOARCH][_test].go #Alternative way to set build constraint, using filename
-tags BUILD_TAG,... #Specify a BUILD_TAG
┌─────────────────────────┐
│ COMPILER DIRECTIVES │
└─────────────────────────┘
//line [FILE]:LINE[:COL] #Specifies that the next line was implemented in FILE:LINE:COL
#Meant for debugging information of FUNCs implemented in C|ASM.
//go:linkname VAR #Make VAR (declared in current PACKAGE) available to any other PACKAGEs
[IMPORT_PATH.VAR2] #If specified, also alias it to VAR2, importable with IMPORT_PATH
#IMPORT_PATH must declare VAR2, but without body (if FUNC)
#Must import "unsafe"
FUNCTION DIRECTIVES ==> #All the following directives target the FUNC declaration on next line.
#All only needed for very low-level code.
//go:noinline #Do not inline this FUNC.
//go:noescape #Any *TYPE argument|returns of this FUNC must never be stored on the heap.
#Only for FUNCs implemented in C|ASM.
//go:uintptrescapes #Keep reference of value of this FUNC's uintptr argument.
//go:nosplit #Do not check for stack overflow on this FUNC.
//go:norace #Do not run the data race detector (-race) on this FUNC.
┌─────────────┐
│ COMPILE │
└─────────────┘
go tool compile FILE.go... #Low-level API, first step of go build
#Compile a single PACKAGE into a FILE.o ("Go object", ar achive)
go build -gcflags
'[IMPORT_PATHS=]ARGS' #Pass arguments to underlying go tool compile ARGS
go tool asm #Can use -spectre
-o FILE #Output file (def: FILE.o or, if -pack, FILE.a)
-pack #Create a FILE.a instead of FILE.o
-linkobj=FILE.o #Split output into two files:
# - -o=FILE.o: compiler-specific output
# - -linkobj=FILE2.o: linker-specific output
-h #Make build errors print a stack trace, and abort building
-L #Show complete file paths in build errors
-C #Do not show column number in build errors
-e #Unless set, only show maximum of 10 build errors
-s #Warn on STRUCT that can use inline infering
-p IMPORT_PATH #Warn on circular dependencies
#IMPORT_PATH is the one of the code being compiled
-m #Print which optimizations were applied
-N #Disable optimizations
-l #Disable inlining.
-B #Disable bounds checking
-smallframes #Forces big local variables to be allocated on the heap instead of on stack.
-complete #Optimize when package uses no C|ASM packages
-wb=false #Do not use the write barrier.
#I.e. do not ensure that I/O writes are not partially flushed in case of power outage.
#Is a speed optimization.
-dwarf=false #Do not generate DWARF symbols (used by debuggers)
-dwarflocationlists=false #Do not add DWARF location lists in optimized mode
-dwarfbasentries=false #Do not use DWARF base address selection entries
-gendwarfinl=INT #How many DWARF inline info records to generate (def: 2)
-spectre=STR,... #Protect against Spectre CPU vulnerabilities. Slower.
#Can be:
# - index: against Spectre variant 1 ("bound check bypass"). 5-10% slower code.
# - ret: against Spectre variant 2 ("branch target injection"). 10-15% slower code.
# - all: same as index,ret
-bench=FILE #Write durations of each compilation stage
-json=0,/PATH #JSON verbose mode
-%
-E
-K
-d
-j
-live
-r
-v
-w
-W #Various low-level debugging flags
-+
-std #Flags meant to compile Go itself
┌──────────┐
│ PACK │
└──────────┘
go tool pack ACTION FILE.o|a #Low-level API to manipulate FILE.o|a
#ACTION can be:
# - t: list each file's name
# - p: print each file
# - x: extract files
# - c FILE2.o|a: copy
# - r FILE2.o|a: append
┌──────────┐
│ LINK │
└──────────┘
go tool link FILE.o|a #Low-level API, second step of go build
#From a main PACKAGE's FILE.o|a, find all dependent PACKAGEs, and link them as a single executable BINARY
go build -ldflags
'[IMPORT_PATHS=]ARGS' #Pass arguments to underlying go tool link ARGS
-o=FILE #Output path (def: FILE.out[.exe])
-tmpdir=DIR #Only used with -linkmode=external
-X IMPORT_PATH.VAR=VAL #Sets the value of a VAR to VAL, at link-time (like a directive)
#VAR must:
# - be STR
# - be package scoped
# - not be const
# - be either unitialized, or initialized to a const STR
#Does not work when init() is used, under some conditions
-u #Aborts if import "unsafe"
-h #Aborts on error
-strictdups=0|1|2 #Warn on duplicate variables among 0|1|2 (none|warn|error) (def: 0)
#This can happen when inlining functions, which will then be removed from DWARF (which is the only impact)
#Not recommended since it creates too many false positives
-f #Do not warn when PACKAGEs used different Go versions
-g #Disable some data checks.
-c #Prints list of function calls
-dumpdep #Prints list of variable and which variables each of them refer to.
-compressdwarf=false #Do not compress DWARF
-w #Do not include DWARF (used by debuggers)
-s #Do not include DWARF and symbol table (variable names, used for debugging)
-n #Print symbol table
-benchmark=mem|cpu #Print benchmark information about linking operations
-benchmarkprofile=FILE #Use a base profile
-H=GOOS #Target OS (def: use GOOS|GOARCH)
#Can also be "windowsgui"
-extar=PROG #Customize archive program (def: 'ar')
#Only with -buildmode=c-archive
-extld=PROG #Customize linker program (def: 'clang|gcc')
#Meant for cross-compiling
-extldflags=ARGS #Arguments to linker program
-libgcc=STR|none #Customize compiler tools program (def: based on -extld)
#Only with -linkmode=internal
-I=PROG #Customize dynamic linker (ELF only) (def: 'ld')
-r=DIR:... #Customize dynamic linker search path (ELF only)
-d #Do not include header in binary needed for dynamic linkers
-E=VAR #Rename "main" to VAR
-T=ADDRESS #Set executable text segment address
-R=UINT #Customize address rounding
-k=VAR
-debugtramp
-v #Low-level debug flags
┌─────────┐
│ ASM │
└─────────┘
ASM ==> #Assembly language is Go-specific
#It is machine-agnostic
go tool asm FILE.s #Like go tool compile, but from ASM files
go build -asmflags
'[IMPORT_PATHS=]ARGS' #Pass arguments to underlying go tool asm ARGS
go build -toolexec 'PATH [ARGS]' #Use a different program than go tool asm under the hood
#This also sets ENVVAR TOOLEXEC_IMPORTPATH
-o=FILE #Output file (def: FILE.o)
-D=VAR[=VAL] #Declare VAR=VAL
-debug #Verbose mode
-gensymabis #Instead of compiling, only produces ABI file (ASM header files)
go tool compile -symabis=FILE #Use ABI file
go tool compile -asmhdr=FILE #Write ABI header file
┌─────────────┐
│ OBJDUMP │
└─────────────┘
go tool objdump BINARY #Disassembles BINARY:
# - prints its ASM instructions, including file, line and address
# - grouped by executable segment
[START END] #Only from START to END address
-s REGEXP #Only symbols matching REGEXP
-S #Show Go source code line too
-gnu #Show gcc ASM (besides gc ASM)
go tool compile|asm
-S #Prints same output as go tool objdump
-S -S #Same but also include data segments
┌────────┐
│ NM │
└────────┘
go tool nm BINARY #Prints all exported variables with:
# - address
# - size (if -size)
# - type 'CHAR' among:
# - t|T: code, static|dynamic
# - r|R: data, read-only, static|dynamic
# - d|D: data, read-write, static|dynamic
# - b|B: BSS data, static|dynamic
# - C: constant address
# - U: referenced but undefined
# - name
-sort=NAME #Can sort by: address, size, name (def), none
-n #Same as -sort=address
┌──────────────┐
│ BUILD ID │
└──────────────┘
BUILD_ID ==> #BINARY checksum that does not include data that might change between machines.
#Stored within the BINARY itself
go tool buildid BINARY #Prints BUILD_ID
-w #Re-create BUILD_ID
go tool compile|link -buildid=ID #Sets explicit BUILD_ID
go tool link -B=STR #Set a BUILD_ID note (ELF binary only)
┌───────────┐
│ GCCGO │
└───────────┘
go build -compiler gc|gcco #gc is default compiler
#GCC go is alternative compiler
# - prefer default one.
# - not documented until needed
runtime.Compiler #"gc|gcco"
ENVVAR GCCGO #
ENVVAR GOGCCFLAGS #CLI flags passed to cc under the hood
#Read-only
┌─────────┐
│ CGO │
└─────────┘
CGO ==> #Used to use C from|to Go
#Only with gc compiler
#Not documented until needed
go tool cgo #
import "C" #
// #cgo ... #
ENVVAR CGO_ENABLED #
ENVVAR AR|CC|CCX|FC #
ENVVAR CGO_CFLAGS|CPPFLAGS|
CXXFLAGS|FFLAGS|
LDFLAGS[_ALLOW|DISALLOW] #
ENVVAR PKG_CONFIG #
ENVVAR GCCGOTOOLDIR #
ENVVAR GO_EXTLINK_ENABLED #
ENVVAR GODEBUG="cgocheck=0|1|2" #
go build
-buildmode=c-archive|c-shared #
go build -gccgoflags STR #
go tool link -linkmode=STR #
runtime.NumCgoCall()->INT64 #
runtime.SetCgoTraceback(...) #
import "runtime/cgo" #
┌─────────┐
│ RUN │
└─────────┘
go run IMPORT_PATHS [ARG...] #Runs go build IMPORT_PATHS, then execute BINARY ARG...
#Exit code is not same as BINARY ARG...
-exec COMMAND #Run COMMAND BINARY ARG... instead
#If go_GOOS_GOARCH_exec is an executable available in $PATH, is used as default value
# - providing GOOS|GOARCH set differently to current OS|arch
-ANY_GO_BUILD_FLAG #
┌───────────┐
│ CLEAN │
└───────────┘
ENVVAR GOCACHE #Cache directory for go build
#Def: CACHE_DIR/go-build (CACHE_DIR is ~/.cache on Linux)
go build -a #Bypass GOCACHE
#Useful when changing C library used through cgo, since that does not update cache
ENVVAR GODEBUG=gocacheverify=1 #Bypass GOCACHE and verify it
ENVVAR GODEBUG=gocachehash=1 #Verbose mode showing what is used in GOCACHE
ENVVAR GODEBUG=gocachetest=1 #Same but only for tests
ENVVAR GOTMPDIR #Temporary directory used by build, e.g. in GOTMPDIR/go-build
#Def: os.TempDir(), i.e. /tmp on Unix
go build -work #Print GOTMPDIR and do not delete it on exit
go clean IMPORT_PATHS #Remove temporary files
-i #Remove BINARY built with go build|test
-cache #Remove GOCACHE directory
-testcache #Same but only tests
-modcache #Remove package downloads cache (GOMODCACHE)
-ANY_GO_BUILD_FLAG #
-r #On dependencies too
-x #Verbose
-n #Dry run
┌─────────────┐
│ PLUGINS │
└─────────────┘
PLUGIN ==> #Library loaded at runtime instead of compile-time
#Is FILE.so
#Only Linux|macOS|freeBSD
go build -buildmode=plugin #Build code as plugin
go tool link -pluginpath=PATH #Output to PATH.so instead
import "plugin" #
plugin.Open('PATH')
->*PLUGIN[,ERROR] #Loads|parse plugin, but does not execute it yet
plugin.Plugin #
PLUGIN.Lookup('VAR')
->SYMBOL[,ERROR] #Retrieve pointer to exported VAR
plugin.Symbol #*TYPE