Graven is a build management tool for Go projects. It takes light cues from projects like Maven and Leiningen, but given Go's much simpler environment and far different take on dependency management, little is shared beyond the goals.
Want to know more? Read about the Motivation for Graven.
Graven currently requires the following tools to be on your path:
go- the Go build tool, used to compile and test your application.git- used during the release process to validate the state of your repo, and tag your repo.
Of course if you don't plan to use the release command commands, you
can still use graven just for building, testing and packaging, and thus
would only require the go tool.
If you want to run the latest, you can just go get the tool.
go get -u github.com/cbegin/graven
For greater consistency and stability, you can run a specific relese version from:
Whether your starting an entirely new project, or working with existing source, the workflow should be the same.
Not all of these steps are always necessary. See below for a description of implied workflow dependencies.
# Once per project, run the init command and modify
# default project.yaml with relevant names and repos etc.
$ cd ./some/working/directory
$ graven init
$ vi project.yaml
# Typical development cycle
$ graven clean
$ graven build
$ graven test
$ graven package
# When you're ready to release
$ graven repo --login --name github
Please type or paste a github token (will not echo):
$ graven release
$ graven bump [major|minor|patch|QUALIFIER]A typical development cycle looks like the following diagram. The init command
is run once per project, then clean, build, test and package are typically used
throughout the development cycle. Releases occur less frequently, and versions
are bumped after the release.
The freeze and unfreeze commands are optional and on a completely
independent flow, thus can be executed any time. They are discussed separately
here: Freezing Dependencies.
+----------+
> | build | \
/ +----------+ \
/ \
/ v
+----------+ +----------+ +----------+
| init |--->| clean | | test |
+----------+ +----------+ +----------+
^ /
\ /
\ +----------+ /
\| package |<-
+----------+ +----------+
| freeze | |
+----------+ v
| +----------+
| | release |
+-----v----+ +----------+
| unfreeze | |
+----------+ |
+-----v----+
| bump |
+----------+
Before you have flashbacks of Maven POMs... note that this is probably the biggest project.yaml file you'll ever see. Most projects will have shorter, simpler project.yaml files, and you'll rarely have to modify them once initialized.
The following documented structure (derived from this very project) will help better understand what you can do with it.
# Name, initially derived from parent directory.
name: graven
# Version is typically managed with the graven bump command.
version: 0.6.6
# You can specify a required go version, supporting ranges.
go_version: ">=1.9.1"
# List of artifacts. Each artifact builds one or more packages into executables,
# and provides compiler flags, environment variables, and resources.
# Upon initialization, an artifact config will be generated for darwin, linux and
# windows. You can safely delete any artifacts you don't need. The classifier
# will be used in artifact names and target build directory names.
artifacts:
- classifier: darwin
# Each target is a package/executable combo with compiler flags and environment variables.
# Upon initialization, a target will be created for each main package found in the path.
# You can safely delete any you don't want.
targets:
- executable: bin/graven
package: .
flags: ""
env: {}
# archive supports zip and tar.gz (or tgz, as a single dot alias)
archive: tgz
resources: []
# Environment variables, can be set at project, artifact and target level.
env:
GOARCH: amd64
GOOS: darwin
- classifier: linux
targets:
- executable: bin/graven
package: .
flags: ""
env: {}
archive: tar.gz
resources: []
env:
GOARCH: amd64
GOOS: linux
- classifier: win
targets:
- executable: graven.exe
package: .
flags: ""
env: {}
archive: zip
resources: []
env:
GOARCH: amd64
GOOS: windows
# Resources will be included in the packaged archive. Can be overridden at
# artifact level.
resources:
- LICENSE
# Configures a repository for deployment.
# Use graven repo --login --name [name] to authenticate
repositories:
github:
url: https://api.github.com/
group: cbegin
artifact: graven
type: github
# Github repos only support releases
roles:
- release
artifactory:
url: http://localhost:8081/artifactory/releases/
group: cbegin
artifact: graven
type: maven
# Supports both releases and frozen dependencies
roles:
- release
- dependency
nexus:
url: http://localhost:8082/nexus/content/repositories/releases/
group: cbegin
artifact: graven
type: maven
# Supports both releases and frozen dependencies
roles:
- release
- dependency
docker:
url: docker.io
group: cbegin
artifact: graven
type: docker
file: Dockerfile
# Docker repos only support releases
roles:
- releasename: graven
version: 0.6.6
The name of your project will initially be set by the parent directory in which it was created when the
init command was run. You can change it to whatever you like, but it's recommended to keep it simple,
short and alphabetic. It may be used for generating other values.
The version of your project follows a minimalist set of semantic version practices. That being:
M.m.p-Q
- M: Major version. Incremented when the software changes significantly and typically in incompatible ways.
- m: Minor version. Incremented when new features are added, and backward compatibility is maintained.
- p: Patch version. Incremented when bugs are fixed. Backward compatibility is typically maintained, but is
- sometimes unavoidably broken.
- Q: Qualifier. This is used to qualify a pre-release build and is typically something like RC1, DEV or TEST.
artifacts:
- classifier: darwin
targets:
- executable: bin/graven
package: .
flags: ""
env: {}
archive: tgz
resources: []
env:
GOARCH: amd64
GOOS: darwin
- ...
Each entity listed in the artifacts section represents a distributable artifact that consists of one or more executables built from a number of packages compiled with specified flags and environment variables. The resulting binaries are packaged up in an archive format (e.g. zip or tar.gz) and additional resources can be included in the archive, specified in the resources array. Both resources and environment variables can be specified at higher levels to avoid duplication. More specific environment variables will override broader scoped ones. The classifier specifies a suffix for the artifact that is usually used to indicate the target platform, but can be used to indicate anything that differs among distributable artifacts.
repositories:
artifactory:
url: http://localhost:8081/artifactory/releases/
group: cbegin
artifact: graven
type: maven
# Supports both releases and frozen dependencies
roles:
- release
- dependency
...
In the repositories section you can define both release and dependency repositories. A release repository is where this project will be released. A dependency repository will be used to store frozen vendor dependencies, so that you don't need to check in your vendor directories or .freezer directory.
Three repository types are currently supported: Github, Docker and Maven (including Nexus and Artifactory). Their capabilities and settings are summarized in the table below.
| Field | Github | Docker | Maven |
|---|---|---|---|
| type | github | docker | maven |
| url | Github API URL | Docker registry URL | Maven release URL |
| group | Owner | Repository | Group ID |
| artifact | Repo | Image Name | Artifact ID |
| roles | release | release | release, dependency |
| file | unused | Dockerfile | unused |
In order to use a repository for releases or dependencies, you'll need to authenticate.
To do so, simply call graven repo --login --name [repo-name]. The credentials you enter
will be stored in your home directory in the .graven.yaml file. Your credentials will be
obfuscated to discourage over-the-shoulder or casual exposure. Even though a strong
encryption algorithm is used, the key is not secure and thus you should treat it as
such.