How to use the go build command line


Build compiles the packages named by the import paths, along with their dependencies, but it does not install the results.

go build
go build hello.go
ls -lh
1.9M Jun 29 17:38 hello
 74B Jun 29 17:37 hello.go

The build flags are shared by the build, clean, get, install, list, run, and test commands:

The go build Commands and Options

  go build [-o output] [build flags] [packages]

Build flags:
force rebuilding of packages that are already up-to-date.
print the commands but do not run them.
-p n
the number of programs, such as build commands or test binaries, that can be run in parallel. The default is the number of CPUs available.
enable data race detection. Supported only on linux/amd64, freebsd/amd64, darwin/amd64, windows/amd64, linux/ppc64le and linux/arm64 (only for 48-bit VMA).
enable interoperation with memory sanitizer. Supported only on linux/amd64, linux/arm64 and only with Clang/LLVM as the host C compiler. On linux/arm64, pie build mode will be used.
print the names of packages as they are compiled.
print the name of the temporary work directory and do not delete it when exiting.
print the commands.
-asmflags '[pattern=]arg list'
arguments to pass on each go tool asm invocation.
-buildmode mode
build mode to use. See 'go help buildmode' for more.
-compiler name
name of compiler to use, as in runtime.Compiler (gccgo or gc).
-gccgoflags '[pattern=]arg list'
arguments to pass on each gccgo compiler/linker invocation.
-gcflags '[pattern=]arg list'
arguments to pass on each go tool compile invocation.
-installsuffix suffix
a suffix to use in the name of the package installation directory, in order to keep output separate from default builds. If using the -race flag, the install suffix is automatically set to race or, if set explicitly, has _race appended to it. Likewise for the -msan flag. Using a -buildmode option that requires non-default compile flags has a similar effect.
-ldflags '[pattern=]arg list'
arguments to pass on each go tool link invocation.
build code that will be linked against shared libraries previously created with -buildmode=shared.
-mod mode
module download mode to use: readonly, vendor, or mod. By default, if a vendor directory is present and the go version in go.mod is 1.14 or higher, the go command acts as if -mod=vendor were set. Otherwise, the go command acts as if -mod=readonly were set.
leave newly-created directories in the module cache read-write instead of making them read-only.
-modfile file
in module aware mode, read (and possibly write) an alternate go.mod file instead of the one in the module root directory. A file named "go.mod" must still be present in order to determine the module root directory, but it is not accessed. When -modfile is specified, an alternate go.sum file is also used: its path is derived from the -modfile flag by trimming the ".mod" extension and appending ".sum".
-overlay file
read a JSON config file that provides an overlay for build operations. The file is a JSON struct with a single field, named 'Replace', that maps each disk file path (a string) to its backing file path, so that a build will run as if the disk file path exists with the contents given by the backing file paths, or as if the disk file path does not exist if its backing file path is empty. Support for the -overlay flag has some limitations:importantly, cgo files included from outside the include path must be in the same directory as the Go package they are included from, and overlays will not appear when binaries and tests are run through go run and go test respectively.
-pkgdir dir
install and load all packages from dir instead of the usual locations. For example, when building with a non-standard configuration, use -pkgdir to keep generated packages in a separate location.
-tags tag,list
a comma-separated list of build tags to consider satisfied during the build. For more information about build tags, see the description of build constraints in the documentation for the go/build package. (Earlier versions of Go used a space-separated list, and that form is deprecated but still recognized.)
remove all file system paths from the resulting executable. Instead of absolute file system paths, the recorded file names will begin with either "go" (for the standard library), or a module path@version (when using modules), or a plain import path (when using GOPATH).
-toolexec 'cmd args'
a program to use to invoke toolchain programs like vet and asm. For example, instead of running asm, the go command will run 'cmd args /path/to/asm <arguments for asm>'.

Compile and run Go program

Run compiles and runs the named main Go package. Typically the package is specified as a list of .go source files from a single directory, but it may also be an import path, file system path, or pattern matching a single known package, as in 'go run .' or 'go run my/cmd'.

  go run [build flags] [-exec xprog] package [arguments...]

If the -exec flag is given, 'go run' invokes the binary using xprog:
go run .
go run hello.go
Hello, World!

Test packages

'Go test' automates testing the packages named by the import paths. It prints a summary of the test results in the format:

  go test [build/test flags] [packages] [build/test flags & test binary flags]

In addition to the build flags:
Pass the remainder of the command line (everything after -args) to the test binary, uninterpreted and unchanged. Because this flag consumes the remainder of the command line, the package list (if present) must appear before this flag.
Compile the test binary to pkg.test but do not run it (where pkg is the last element of the package's import path). The file name can be changed with the -o flag.
-exec xprog
Run the test binary using xprog. The behavior is the same as in 'go run'. See 'go help run' for details.
Install packages that are dependencies of the test. Do not run the test. The -i flag is deprecated. Compiled packages are cached automatically.
Convert test output to JSON suitable for automated processing. See 'go doc test2json' for the encoding details.
-o file
Compile the test binary to the named file. The test still runs (unless -c or -i is specified).

Related Tags

#go# #go build#