Purpose
I try to write all documentation with a purpose, and this is no different. My goal is to document some of the basic tasks a System Administrator, Site Reliability Engineer (SRE), or even enthusiast can pickup using Go. I won’t make you an expert, but hopefully some working examples will get you motivated to pickup other parts of the language. When I started down the Python path I felt the most accomplished when I could demonstrate a new library or tool I recently picked up. My goal here is to demonstrate some common tasks you can look to take with you.
Hopefully this will fire you up, and you will begin to explore other parts of the language, and hopefully I will pickup more about the language as I go.
A Little Help
You may find the official Golang book as useful as I did. I think this is easily one of the best first chapters to a programming book I’ve ever read. You will step through example code that will do some math, draw a gif, and even run a small web service. Clicking on the link below helps support the website!
Go Documentation!
I wish this came up earlier in my short journey with Golang. Go is prepacked some serious documentation power. You can get documentation in the command line or right in your browser.
We’re going to build godoc. Go’s built in documentation helper. To me
godoc shares a lot of the same power that pydoc has for Python.
Developing in a new language means you don’t know much, but if you know where
to look for help you’ll get farther. Not only will godoc provide help on
the command line for libaries, but it’ll also leverage the Go language and run
a local documentation server on your machine.
Go requires you specify a few environment variables to begin: GOPATH &
GOBIN are two of them. GOPATH tells the Go binary where your workspace
is. Lately I’ve made $HOME/go my workspace. Within your workspace is where
your Go binary will collect sources. GOBIN is where Go will install Go
binaries when you tell it to.
Let’s set them now. If you’re planning on trying out Go for more than a few
minutes go ahead and drop it in $HOME/.bashrc. For Mac OSX, your operating
system doesn’t respect .bashrc so just append to $HOME/.bash_profile.
export GOPATH="${HOME}/go"
export GOBIN="${HOME}/go/bin"
Build godoc
We start by acquiring godoc
go get golang.org/x/tools/godoc
Go knows how to talk to code repositories out of the gate. Here we ask Go to
download the source for the tool godoc. godoc lives in
golang.org/x/tools, which is where tools live outside of the language tree.
Find out more from the official website
Once we have godoc source, you’ll see the path $HOME/go/src/golang.org/x/tools/godoc
has been populated with the source code. Change directories there and let’s build it.
cd $HOME/go/src/golang.org/x/tools/godoc
go install
This will build & install the godoc binary to $HOME/go/bin. If this
directory is in your executable path you can call it from anywhere on the
command line.
export PATH=$HOME/go/bin:$PATH
Go Documentation at Your Fingertips
Given our new tool, when we want to see the documentation on a given library
(maybe net/http) we can do the following:
godoc net/http
That’s a little messy so send it to a pager for easier nagivation:
godoc net/http | less
Go makes it extremely easy to get your hands on the documentation. They provide lots of example code within the docs, and the source code itsel can be used for reference when writing new code.
Your Own Local Documentation Server
This is one of my favorite features as a new Go user: your very own doc server.
The go-doc binary is ready to be your own self-contained web based
documentation server.
# Run on localhost port 8001
godoc -http 'localhost:8001'
# shorthand for all interfaces 8001
godoc -http ':8001'
This will fire up the server right on your laptop. Just fire up your browser, and go to http://localhost:8001 for the intro page or http://localhost:8001/pkg to go straight to the documentation.
I hope this has been helpful.