Go Tool

External

• https://pkg.go.dev/cmd/go

Internal

• Go Operations

Overview

go is a command line tool with multiple uses: package manager, build tool and test driver. go manage packages in workspaces, query metadata about packages, print documentation, build, format, download, test, etc.

Shared Flags

Shared Flags

Commands

Help

go help <command>

go help build

build

The build command compiles one or more packages. If a "main" package is among the arguments, the tool creates an executable as described below. The following flags apply:

Shared Flags

TO DEPLETE: Go_Commands_-_build

Build an Executable with go build

go build [options] <main-package-import-path>

Note that depending on whether the package is part of module or not, the main package import path may include the module path.

The executable is placed in the directory go build is executed from.

The name of the executable is given by the last segment of the main package import path, and it can be configured with the -o command line option. The argument of -o can be the new name of the executable file, in which case the executable will be written in the current directory, or an absolute or relative path, in which case the executable, named after the last segment of the path, will be written at the given path.

Package without Module Support

In case of a package without module support, with the go tool configured in GOPATH mode (GOPATH configured to include the parent of the src directory and GO111MODULE set to "auto"), and with this directory layout:

.
└─ src
   └─ a
      └─ b
         └─ c
            └─ main.go # package main

the executable is built with:

go build a/b/c

The executable will be named "c", based on the last segment of the package import path and will be place in the directory go build was executed from. To change the name of the executable, use the -o option:

go build -o blue a/b/c

This will create an executable named "blue".

Package within a Module

An a/b/c main package with a similar layout, but this time included within an example.com module

.
├─ a
│  └─ b
│     └─ c
│        └─ main.go # package main
└─ go.mod

can have its executable built with:

go build [-o blue] example.com/a/b/c

install

go install

go install is similar to go build except that is saves the compiled code in form of object files and possibly binary executables, locally for each packages instead of discarding it. The shared flags describe here apply:

Shared Flags

go install is used for building and publishing packages and modules.

If executed from a git workarea, there is underlying git interaction.

Build and Install an Executable with go install

go install [options] <main-package-import-path>

Note that depending on whether the package is part of module or not, the main package import path may include the module path.

The name of the executable is given by the last segment of the main package import path and cannot be changed with -o option, as in the case of the go build command. Because of this detail, go build is probably a better way to build executables, if you want to change the name of the executable.

The executable is placed under ${GOBIN} directory if the GOBIN environment variable is set, or under ${GOPATH}/bin otherwise. The default value for ${GOPATH} is ~/go. For more details see GOPATH.

Package without Module Support

In case of a package without module support, with the go tool configured in GOPATH mode (GOPATH configured to include the parent of the src directory and GO111MODULE set to "auto"), and with this directory layout:

.
└─ src
   └─ a
      └─ b
         └─ c
            └─ main.go # package main

the executable is built with:

go install a/b/c

The executable will be named "c", based on the last segment of the package import path and will be place in a directory determined by the rules described above.

Unlike go build, go install does not accept an -o option to change the name of the executable.

Package within a Module

An a/b/c main package with a similar layout, but this time included within an example.com module

.
├─ a
│  └─ b
│     └─ c
│        └─ main.go # package main
└─ go.mod

can have its executable built with:

go install example.com/a/b/c

The executable is named based on the last sentiment of the package import path and it placed in a directory determined by the rules described here.

Build and Install Package Object Files

Package without Module Support

GOPATH and GO111MODULE should be configured as described in the Package without Module Support executable install section, above. The package object file is built and installed with:

go install <package-import-path>

The command will compile and install the object file under ${GOPATH}/pkg/${GOOS}_${GOARCH}/<import-path>.

If the package specified as argument has dependency packages, go install will correctly locate and compile the source files for both the dependent package and all dependency packages identified walking the transitive dependency graph. If any of the dependencies fails to compile, the installation process will fail. However, only the object file corresponding to specified package will be written in ${GOPATH}/pkg. To install the object files for the entire dependency chain, the packages have to be explicitly specified on the command line.

If the pkg subdirectory does not exist, it will be created. The go install can be run from the ${GOPATH} directory, or from some any other directory. As long the GOPATH and GO111MODULE are correctly set, the results will be the same.

GOPATH may list multiple colon-separated directories. As long as the package to be installed is declared under one of those directories, it will be correctly located and go install will write the corresponding object files under the pkg subdirectory of the corresponding root. If multiple GOPATH directories contain package with the same import path, only the first package will be processed.

Package within a Module

TODO

run

The run command compiles the specified packages or files by delegating to go build and then runs the executable. There must be a main for an executable to be generated.

cd $PROJECT_DIR
go run ./src/main/main.go some-arg-1 some-arg-2

The first argument that does not end in .go is assumed to be the beginning of the list of command line arguments of the executable.

The shared flags described here apply:

Shared Flags

clean

The shared flags described here apply:

Shared Flags

-cache

Clean the build cache:

go clean -cache

-fuzzcache

Clean the fuzz cache:

go clean -fuzzcache

doc

The doc command prints documentation for a package or a package member:

go doc time

go doc time.Since

fmt

The fmt ("format") command formats source code files.

get

The get command downloads packages and installs them. The shared flags described here apply:

Shared Flags

list

The list command lists all installed packages. The shared flags described here apply:

Shared Flags

test

The test command runs tests. The shared flags described here apply:

Shared Flags

For more details, see:

Go Testing

env

The env command prints the effective values of the environment variables relevant to the tool chain.

go env GOOS GOARCH GOPATH

get

The get command retrieve and update packages.

TODO Addison-Wesley The Go Programming Language Section 10.7.2

mod

go mod

TO DEPLETE

Deplete:

• doc
• fmt
• get
• version
• vet