Boilerplate
The way we Go
Boilerplate provides a simple tool which you can use to provision a new Go project with a Makefile, Dockerfile, and associated files.
Boilerplate revolves around 3 concepts, each of which are used to set up your new project:
repository
: the name of the source control repository (e.g. github.com)namespace
: the name of the organization/group in the repository (e.g. zulily)project
: the name of the binary (e.g. fizzbuzz)
Boilerplate makes/enforces several assumptions about the structure and conventions of a Go project. Among them:
- The project contains a single binary (aka
package main
). The name of this binary is the same as that of the project. - All dependencies are managed via godep.
- All builds are compiled in a Docker container, using a pinned version of Go (v1.4.2 at the time of writing)
- Binaries are compiled as true static binaries, with no cgo or dynamically-linked networking packages.
- Binaries have the
main.BuildSHA
var set to the latestgit
SHA in the repo. This is accomplished using the Go linker's-ldflags -X
option. - A Docker image is created for the resulting binary, which
exec
s the binary as the entrypoint. - The Docker image uses the naming convention
<namespace>/<project>
, and is tagged with the latestgit
SHA in the repo.
Prerequisites
boilerplate
depends on having the following installed on the host machine:
git
make
go
Docker
(orboot2docker
for OSX users)
Quick Start
boilerplate
may be invoked with no arguments, in which case you will be
interactively prompted for the repository
, namespace
, and project
names.
$ go get github.com/zulily/boilerplate
$ boilerplate
Enter the name of git repository (e.g. github.com): github.com
Enter the namespace in the repository (e.g. zulily): dcarney
Enter the name of the project (e.g. fizzbuzz): whizbang
GOPATH is: /home/dcarney/go
Creating a new project at: /home/dcarney/go/src/github.com/dcarney/whizbang
Creating new: .dockerignore
Creating new: .gitignore
Creating new: Dockerfile
Creating new: Makefile
Creating new: main.go
Initializing git repo
Initializing godeps
Done
Example
Values for the repository
, namespace
, and project
can also be supplied using command line flags:
$ boilerplate -repository=github.com -namespace=zulily -project=fizzbuzz
GOPATH is: /home/dcarney/go
Creating a new project at: /home/dcarney/go/src/foobar/zulily/fizzbuzz
Creating new: .dockerignore
Creating new: .gitignore
Creating new: Dockerfile
Creating new: Makefile
Creating new: main.go
Initializing git repo
Initializing godeps
Done
The resulting project can be compiled, linted, and "Dockerized" using the supplied Makefile
targets:
$ cd $GOPATH/src/foobar/zulily/fizzbuzz
$ make
building binary for fizzbuzz...
$ make lint
linting code...
main.go:8:6: exported type Foobar should have comment or be unexported
main.go:15:2: can probably use "var slice []string" instead
$ make dockerize
building binary for fizzbuzz...
running tests for fizzbuzz...
building Docker image 'zulily/fizzbuzz'...
$ docker images | grep fizzbuzz
zulily/fizzbuzz HEAD 4f679023d74c 5 seconds ago 1.94 MB
See the generated Makefile
in your boilerplate
-created project for more details and build targets
Limitations and known issues
Boilerplate was developed on, and is used daily on, various Linux OSes. It has been known to work on OSX with boot2docker
. It has not been used on Windows. (pull requests welcome!)