This document assumes Go version 1.0.3.

Motivation
The Go way
Go tool doesn't do everything
FAQ

Motivation

The go tool is bundled with Go distribution by default and it's convenient for automating common tasks such as getting dependencies, building, and testing your code. It's easy to use and provides a consistent command-line interface and it also expects you to respect a bunch of conventions, some of which I find peculiar and think they introduce a slight learning curve for some users and require a bit of getting used to.

While the conventions imposed by go tool might seem natural for a hardcore gopher, it takes effort for a newcomer to get up to speed with it. If you hit a wall trying to make it work for you and ask for help on #go-nuts channel or [golang-nuts group][2] showing your code layout and error messages go get or go build produces, you will most likely be told to first learn how to use go tool properly before you start coding in Go. Its documentation is actually pretty good, but it's not easy to absorb it all at once.

My experience was such that neither the recommended [initial reading][1], nor discussions on the mailing list cleared up the picture completely for me. I was only able to eventually grasp the go way by gathering tidbits from the net, through experimentation, and by looking at the go tool's source code.

In this article I'm going to explain the go way from an outsider's point of view. Assuming you're likely to encounter similar hurdles along your way, this guide should answer your questions and help you understand go tool's conventions. There is also a FAQ with code samples at the bottom.

The Go way

Here are some fundamentals you need to be aware of when using go tool.

1. Go tool is only compatible with code that resides in a workspace

This is the fundamental rule of writing Go code. There are some exceptions that apply to little programs and throw-away code, but in general everything you write in Go will reside in your workspace. So what is a workspace?

A workspace is a directory in your file system, the path to which is stored in the environment variable GOPATH. This directory has a certain structure, in the most basic terms it should have one subdirectory named src. Within the latter you create new subdirectories, one for each separate Go package.

This is described in more detail in the aforementioned [article][1] and in the FAQ near the end of the present document. To keep it simple, always create a new directory inside $GOPATH/src when you're starting a new Go project.

2. Go tool does not allow you to depend on specific versions of external packages

If you really need to have a specific version of a certain package, you'll need to fork that package and check it out at the specific version you desire. If you need to use different versions of a single package, you'll need to create a separate fork for each version.

Obviously, this approach doesn't scale and gets tedious once you need more than one version of any given package. Go's reasoning behind this is that versioning is so damn hard that your dependencies should better all be working for you at their latest versions and also at the latest versions of their respective dependencies, and so on recursively. While this is a sound advice, it is generally not possible to adhere to it in practice. You will need to depend on specific versions of your immediate dependencies or dependencies of your dependencies, etc.

In a nutshell, don't try to emulate versioning with go tool, it just doesn't play well with it.

3. When working with Go tool, use fully qualified imports and always build import paths from $GOPATH

There is no such thing as local packages in Go. While local imports are possible to some extent, they're meant more for the Go devs themselves than for Go users.

Anything you import is relative to your $GOPATH/src. Thus, if you have a directory structure like the following one:

.
└── src
    └── gopher
        ├── main.go
        └── sub
            └── sub.go

in your main.go file you'll need to import sub as follows:

package main

import "gopher/sub"

func main() {
    sub.ExportedFunction()
}

If you'd like to use a go package that's publicly available from some code hosting site, the recommended approach is to import it like this:

import "codehosting.com/path/to/package"

func main() {
    package.ExportedFunction()
}

Go tool let's you download remote packages either by passing their import path to go get or calling go get ./... inside your project's directory to recursively get all remote dependencies.

go get codehosting.com/path/to/package

The source for the downloaded package will end up in $GOPATH/src/codehosting.com/path/to/package. Go tool will also automatically build a static lib and put it in $GOPATH/pkg/.... To read more about this, run go help get and go help gopath. Also, see question 10.

Go tool doesn't do everything

Coming from other languages/environments, you may expect that go is a full package management solution. It isn't! The following FAQ entries might be useful:

How do I set up multiple workspaces?
Can I create a package outside of $GOPATH?
How do I manage package versions?
How do I freeze packages when deploying?

FAQ

0. What is GOPATH and what should I do with it?

The best way to go about GOPATH for a beginner is to set it and forget it. If you're just starting with Go, do this:

Install Go.
Choose a directory where you'll be keeping all of your Go code and set GOPATH to it, e.g.
```
# in your .bashrc or similar file
export GOPATH=$HOME/go
```
Forget about it. Start every new project inside your $GOPATH/src and use the go tool for building, testing, fetching dependencies.

If you'd like to know more about GOPATH, it's frequently mentioned throughout this FAQ. Also, take a look at the following resources.

official [How to Write Go Code][1] guide
the build package [documentation][3]
[GOPATH][4] (community wiki)
[Troublingshooting your Go installation][5] (community wiki)

1. How do I start writing Go code?

Before you start any coding, you should pick a directory that will become your Go workspace. All your Go code will reside there. Set the GOPATH environment variable to the path to that directory in your .bashrc or similar file for the shell you're using.

export GOPATH=/Users/alco/go

You'll also need to create a subdirectory named src inside your $GOPATH, this is where you'll be keeping your Go packages and commands. Here's what your initial directory structure is going to look like:

$ tree -L 2 $GOPATH
/Users/alco/go
└── src
    ├── example
    ├── gopher
    └── testy

Each of the subdirectories inside src represents a separate package or a command (see question 11 describing the difference between packages and commands). Each one will contain at least one .go file and may also have subdirectories of its own.

For more information about GOPATH and workspace directory structure, run go help gopath.

2. I've written some code. How do I run it?

Navigate to your package's directory and use the go tool to build and run your code.

Let's assume you created a program in $GOPATH/src/example directory:

$ cd $GOPATH/src/example
$ ls
main.go

$ cat main.go
package main

import "fmt"

func main() {
    fmt.Println("Hello world!")
}

The quickest way to run it is using go run:

$ go run main.go
Hello world!

If your main package is split into multiple files (see question 3 for details on how to do that), you will need to pass them all as arguments to go run.

Soon, however, you'll want to produce a binary from your Go source that you can run as a standalone executable, without using go tool. Use go build for that, it will create an executable in the current directory.

You can also run go install, it will build the code and place the executable in $GOPATH/bin. You might want to add the latter to your PATH environment variable to be able to run your Go programs anywhere in the file system. If you set GOBIN environment variable, then results of running go install will be placed there.

$ go build
$ ls
example main.go

$ ./example
Hello world!

$ go install
$ $GOPATH/bin/ex

Gostart

Install / Use

README

Table of contents