new! Golds - a Go local docs server (and code reader) showing type implementation relations.

The Go Toolchain

Currently, the tools in the official Go Toolchain (called Go Toolchain later) 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 provided in Go Toolchain.

This article will introduce how to setup the Go development environment and how to the go command provided in Go Toolchain. Some other tools out of Go Toolchain will also be introduced.

Install Go Toolchain

Please download Go Toolchain and install it by following the instructions shown in the download page.

The version of a Go Toolchain release is consistent with the highest Go language version the release supports. For example, Go Toolchain 1.17.x supports all Go language versions from 1.0 to Go 1.17.

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

The recent Go Toolchain versions support a feature called modules to manage project dependencies. The feature was introduced experimentally in version 1.11 and has been enabled by default since version 1.16.

There is an environment variable, GOPATH, we should be aware of, though we don't need to care too much about it. It is defaulted to the path to the go folder under the home directory of the current user. The GOPATH environment variable may list multiple paths if it is specified manually. Later, when the GOPATH folder is mentioned, it means the folder at the first path in the GOPATH environment variable.

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 containing 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

Go Toolchain 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.

If multiple source files are in the main package of a program, then we should run the program with the following command
$ go run .
Note,

More go Subcommands

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

We can (and should often) use the go fmt command to format Go source code with a consistent coding style.

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

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

It is highly recommended to let your Go projects support the Go modules feature to ease dependency management. For projects supporting Go modules,

Since Go Toolchain 1.16, we can run go install example.com/program@latest to install the latest version of a third-party Go program (into the GOBIIN folder). Before Go Toolchain 1.16, the corresponding command is go get -u example.com/program, which has been depreciated now.

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

Run the go command without any arguments to show the supported subcommands.

The Go 101 article series will not explain much more on how to use the tools provided in Go Toolchain. Please read the official documentation for details.

View Go Documentation in Browsers

We can view all kinds of Go documentation on the official Go website golang.org and package docs on go.dev.

We can also install the godoc program (golang.org/x/tools/cmd/godoc), then run godoc -http=:9999 to view the docs of standard packages and packages in the current project at localhost:9999 locally.

Another docs view tool is Golds (go101.org/golds), which is developed by me (Tapir Liu). Golds supports richer code reading experiences (such as listing type implementation relations). After installing Golds, we can run golds std ./... to view the docs of standard packages and packages in the current folder.


Index↡

The Go 101 project is hosted on Github. 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.

If you would like to learn some Go details and facts every serveral days, please follow Go 101's official Twitter account @go100and1 or join Go 101 slack channels.

The digital versions of this book are available at the following places:
Tapir, the author of Go 101, has spent 4+ 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. Tapir is also an indie game developer. You can also support Go 101 by playing Tapir's games (made for both Android and iPhone/iPad):
Individual donations via PayPal are also welcome.

Index: