Go Development Environment
30 June 2014
Recently, I’ve started to work with the Go language. One initial point of confusion for me was how to use workspaces. They work a little different than other frameworks and languages.
In simple terms, a workspace sets the context for running the go tool. Go is implemented by a suite of binaries similar to GCC. There is a compiler, linker and other tools for managing specific aspects of the Go workflow. On top of all of this is a tool called go
that lets you use much simpler meta tasks like build
, install
, and test
. For the high level tool to operate, it needs to have a context to work within. This includes where to find code and dependencies, where to build and install components, and generally set the state of the world.
Many languages have the concept of a path. Python, Ruby, and Java all operate where you set an environment variable that lets the tools resolve where to find dependencies. Go has a similar concept. There are two primary environment variables that are used by the go
tool. GOROOT
is typically set to the location where the go binaries and standard libraries are installed. For example, on Mac OS X, this would be /usr/local/go
. The second variable is GOPATH
. This represents where you would put your code and any code you have pulled in as dependencies.
The GOPATH
variable can have as many components as you like. It could be one location or several. It is up to you. This is where workspaces come in. A go workspace is effectively a working area that is composed of the following:
bin/
pkg/
src/
These three directories form the conventions that the go tool will use to find and build things. All paths are relative to the workspace root and component directory.
A more complete example would be like the following:
bin/
todo
pkg/
linux_amd64/
code.google.com/p/goauth2
oauth.a
github.com/nf/todo
task.a
src/
oauth/
oauth.go
oauth_test.go
github.com/nf/
todo/
task/
task.go
todo.go
...
Go recommends using repository paths as name spacing mechanism. Even if you never check in your code, using this layout makes things easier. The GOPATH
is simply a list of all these workspaces you might want to use.
So far so good - you have a way of collecting code and working with it. You have a mechanism for convenience tools to interact with it. You might be tempted to just make ~/Projects/my_gocode
and set that to GOPATH
and put everything in there. That might be fine but anyone who has spent time working with code that involves external dependencies can tell you, that can get messy fast. Languages like Python and Ruby have helpers like virtualenv or rbenv for creating isolated environments. It seems like a useful idea in Go as well.
Go has a different kind of package manager. It has similarities to PyPi or Rubygems but without a strong notion of versioning. Go strongly encourages using the latest version in master. There is no general versioning support. Whether that is good or not is still being debated. The go
tool itself has a get
command that will fetch the head of a dependency much like a package manager would. The key thing here is that it will fetch it to the first workspace on the GOPATH
. Alternately, you could git checkout
any version you wanted directly into src/
to lock to a version or control it more precisely.
With all that in mind, I wanted to give myself a little more flexibility. Conceptually putting everything in one place didn’t feel right to me. I would prefer a little more flexibility and isolation. The nice thing is that GOPATH
gives you all that power - you just need to set it.
I created a simple workspace manager tool. I found several others (even with the same name) but none did quite what I wanted. I don’t want a Go version of virtualenv or rbenv. That seems heavier than what I want. All I need is a more convenient way to switch my workspace context and then use all the standard Go tools.
The tool I created is goenv.
Go workspace manager
Usage:
goenv command [arguments]
The commands are:
init initialize path as workspace (default working directory)
switch switch workspace to path (default to working directory)
add add path to workspace (default working directory)
rm remove path from workspace (default working directory)
reset reset to workspace to empty
list list all workspace paths
which show current Go workspace
env environment variables for workspace
goenv manages the workspace by setting the GOPATH environment variable
When setting or adding a workspace, goenv will search up the path
to find the parent with the required GOPATH entries of bin, pkg, and
src
Let’s see an example workflow.
You can create a new workspace by using goenv init
. This will create a standard Go workspace layout (bin/
, pkg/
, /src
) and add it to the GOPATH
. The path to the workspace can be relative or absolute. The command goenv list
shows all the active workspaces. The command goenv env
is a short version of go env
that is just the GOROOT
and GOPATH
currently set.
% goenv init myapp
% cd myapp
% goenv list
/Users/andrew/Projects/myapp
% goenv env
GOPATH=/Users/andrew/Projects/myapp
GOROOT=/usr/local/go
With the GOPATH
set, you can use standard go tool commands like go get
. All workspaces added via goenv
will have the bin/
path added to the PATH
so you can easily run any binaries you build.
% go get code.google.com/p/go.example/hello
% ls -l src/code.google.com/p/go.example/
total 24
-rw-r--r-- 1 andrew staff 1.4K Jun 30 09:36 LICENSE
-rw-r--r-- 1 andrew staff 1.3K Jun 30 09:36 PATENTS
-rw-r--r-- 1 andrew staff 102B Jun 30 09:36 codereview.cfg
drwxr-xr-x 3 andrew staff 102B Jun 30 09:36 hello/
drwxr-xr-x 4 andrew staff 136B Jun 30 09:36 newmath/
% ls bin/
hello*
% hello
Hello, world. Sqrt(2) = 1.414213562373095
Adding a second workspace works like before. If it already exists, go add
will amend it. Alternately, if you use go switch
, it will clear any currently set workspace and set it to only the new one you added.
% cd ..
% goenv init myapp2
% goenv list
/Users/andrew/Projects/myapp
/Users/andrew/Projects/myapp2
Removing a workspace works like add.
% goenv rm myapp
% goenv list
/Users/andrew/Projects/myapp2
If you are in a working directory, you can find the implied workspace with the goenv which
command. This will walk up the path until it finds a go workspace root and either return that path or none if it isn’t in a go workspace. This is how the go add
and go switch
methods determine it implicitly.
% cd myapp
% goenv which
/Users/andrew/Projects/myapp
% cd src/code.google.com/p/go.example/hello
% goenv switch
% goenv list
/Users/andrew/Projects/myapp
Also you can work with multiple paths.
% cd ~/Projects/myapp
% goenv reset
% goenv list
Go workspace not set
% goenv add myapp myapp2
% goenv list
/Users/andrew/Projects/myapp
/Users/andrew/Projects/myapp2
I’m finding this is about all I’ve needed for managing workspaces. It is convenient to set the context and use the built in tools. Additionally, it is easily transferrable to a Make file in that you simply would need to set the GOPATH
and the rest would fall out. Like a lot of Go, the simplicity is a little misleading at first but it is elegant when you wrap your head around it.
For BBEdit users, I’m working on a Go.bbpackage that includes some similar ideas for running go commands on the current document. Since BBEdit will run each in a new shell context, the workspace is always dynamically found and used. I’m not sure yet if or how I want to bubble up some of the more complicated methods.