The Official Go SDK

Currently, the tools in the official Go SDK are the most used tools to develop Go projects. In Go 101 article series, all examples are compiled and verified with the standard Go compiler.

This article will introduce how to setup the Go development environment and how to run simple Go programs. Some tools of the official Go SDK will also be introduced.

Install Go SDK

Please download the official Go SDK and install it according the instructions shown in the download page.

The version of an official Go SDK release is consistent with the highest Go language version the release supports. For example, the latest Go SDK 1.12.x supports all Go language versions from 1.0 to Go 1.12.

The path to the bin subfolder in the Go SDK installation root path must be put in the PATH environment variable to execute the tools (mainly the go subcommands) in the SDK without inputting their full paths. If your Go SDK is installed with an installer or by a package manager, the path to the bin subfolder may have been already set in the PATH environment variable automatically for you.

Earlier Go SDK versions might require GOROOT and GOPATH environment variables to be set. The latest Go SDK has no such requirements. The default value of the GOPATH environment variable is the path to the go folder under the home directory of the current user. GOPATH environment variable may list multiple paths.

There is a GOBIN environment variable which controls where the binary files created by some go subcommands, such as the go install subcommand (see below), will be stored. If the environment variable is not set, the go command will use the path to bin subfolder in the first path specified in the GOPATH environment variable to store the created binary files. The path to the folder for storing the binary files should be set in the PATH environment variable to run the binary files without specifying their full paths.

Before Go SDK 1.11, it is recommended to put all custom Go packages into the src subfolder of any path specified in the GOPATH environment variable, in particular when a Go project depends on some third party packages. Packages will be introduced in packages and imports later.

In Go SDK 1.11, an experimental feature, Go modules, is supported. The Go modules feature lets us put our Go projects freely in any folder. We can get more module releated information from this wiki page.

Note, from the next main release (version 1.13) of Go SDK, the Go modules feature will become as the preferred mode (to the old GOPATH mode). The necessity and meaningfulenss of the GOPATH environment variable will be weakened much, even be abolished eventually. On the other hand, the importance of the GOBIN environment variable will be promoted, for there is still a need to store the binary files produced by some go subcommands.

The Simplest Go Program

Let's write a simple example and learn how to run simple Go programs.

The following program is the simplest Go program.

package main

func main() {
}

The words package and func are two keywords. The two main words are two identifiers. Keywords and identifiers are introduced in a coming article.

The first line package main specifies the package name (main here) of the source file.

The second line is a blank line for better readability.

The remaining code declares a function which is also called main. This main function in a main package specifies the entry point of a program. (Note that some other user code might be executed before the main function gets invoked.)

Run Go Programs

The official Go SDK requires that Go source code file to have the extension .go. Here, we assume the above source code is saved in a file named simplest-go-program.go.

Open a terminal and change the current directory to the directory which contains the above source file, then run

$ go run simplest-go-program.go

Nothing is output? Yes, this program outputs nothing.

If there are some syntax errors in the source code, then these errors will be reported as compilation errors.

Note: if multiple source files are in the main package of a program, then we should run the program with the following command

$ go run *.go

Note, the go run command is not recommended to compile and run large Go projects. It is just a convenient way to run simple Go programs, like the ones in the Go 101 articles. For large Go projects, please use the commands go build or go install to create (and run) executable binary files instead.

More `go` Subcommands

The three commands, go run, go build and go install, will only show code syntax errors (if any). They don't (try to) show code warnings (a.k.a., possible code logic mistakes). We can use the go vet command to check and report such warnings.

We can use the go fmt command to format Go source code with a consistent coding style.

We can use the go get command to get a remote third-party go package to lcoal. go get requires the corresponding version control tool must be installed.

We can use the go test command to run tests and benchmarks.

We can use the go doc command to view Go documentations in terminal windows.

Since Go SDK 1.11, we can use the go mod command to package dependencies.

We can use the go help aSubCommand command to view the help message for a specified sub command.

The go command run without any arguments shows the supported subcommands.

The Go 101 article series will not explain much more on how to use the tools provided by the official Go SDK. Please read the official documentations for details.

View Go Documentations in Browsers

We can view all kinds of Go documentations at the official Go website golang.org.

We can also run godoc -http=:9999 to start a local clone of the official website at localhost:9999.

Please note,

for Go SDK 1.10, if the GOROOT environment variable is unset, we must specify the goroot flag when running the local godoc server, e. g. godoc -http=:9999 -goroot path/to/go/sdk. This inconvenience is caused by a bug in Go SDK 1.10. This bug has been fixed since Go SDK 1.11.
since Go SDK 1.12, the documentation "A Tour of Go" is not packaged in Go SDK any more. We can run go get golang.org/x/tour; tour to view the documentation locally.
it is possible that the godoc command will be removed from Go SDK since version 1.13.

Currently (Go SDK 1.12), the godoc command doesn't support showing documentations of packages outside of the paths specified in the GOPATH environment variable.

The godoc command tries to list the documentations of all the packages under the paths specified in the GOPATH environment variable. If you only want to view the documentations of the standard packages, you can set the GOPATH environment variable to a non-exist path before running godoc, e. g. GOPATH=nonexist godoc -http=:9999.

The Go 101 project is hosted on both Github and Gitlab. Welcome to improve Go 101 articles by submitting corrections for all kinds of mistakes, such as typos, grammar errors, wording inaccuracies, description flaws, code bugs and broken links.

The digital versions of this book are available at the following stores and forms:

Leanpub store, $19.99+, Leanpub gets 20%, Tapir gets 80%.
Apple Books store, $19.99, Apple gets 30%, Tapir gets 70%.
Amazon Kindle store, $39.99, Amazon gets 65%, Tapir gets 35%.
Free ebooks, including pdf, epub and azw3 formats.

Tapir, the author of Go 101, has spent 2.5+ years on writing the Go 101 book and maintaining the go101.org website. New contents will continue being added to the book and the website from time to time. If you would like to, you can support the book and the website by making a donation (through Paypal) or buying Tapir a coffee (way 1 and way 2).

(Paypal donation QR code)
paypal donate QR code

You can also support Go 101 by playing Tapir's games.

Color Infection (★★★★★), a physics based original casual puzzle game. 140+ levels.
Rectangle Pushers (★★★★★), an original casual puzzle game. Two modes, 104+ levels.
Let's Play With Particles, a casual action original game. Three mini games are included.

Cryptocurrency donations are welcome too: