stamp

README

Stamp

Stamp exposes information about the build (user, host, time) and code version (description, commit, branch) at runtime.

Configuration

To include the library, add the following to your WORKSPACE:

load("@bazel_gazelle//:deps.bzl", "go_repository")
go_repository(
    name = "com_github_gebn_go_stamp",
    tag = "v2.0.0",
    importpath = "github.com/gebn/go-stamp",
)

Stamp uses a combination of workspace_status_command and x_defs to substitute values of Go vars at link time. Unfortunately, there does not currently appear to be a way to add to the workspace status from Starlark, so this must be manually configured.

First, create an executable script with the following contents somewhere in your workspace, e.g. bin/workspace_status (if you already have a workspace status script, you just need to add the three echo lines to it). N.B. due to this issue, having Bazel execute a script in the workspace root is awkward.

#!/bin/bash

set -o errexit
set -o nounset
set -o pipefail

echo "STABLE_STAMP_COMMIT $(git rev-parse HEAD)"
echo "STABLE_STAMP_BRANCH $(git rev-parse --abbrev-ref HEAD)"  # will be HEAD in detached HEAD state
echo "STABLE_STAMP_VERSION $(git describe --always --tags --dirty)"

Then add the following line to .bazelrc to execute the script during the build:

build --workspace_status_command=bin/workspace_status

You can test everything is working by calling Summary() in your project, which summarises all information gathered by this library:

package main

import (
    "fmt"
    "github.com/gebn/go-stamp"
)

func main() {
    fmt.Println(stamp.Summary())
}

This should print something similar to:

v1.0.0-11-gcb25cf1 (cb25cf163fdb9f4d5033b9a4d70e9b259ef4b9b2, master), built with go1.11.5 by george@dev on 2019-02-01T21:07:53Z

Kingpin

If using Kingpin, Stamp can be integrated like this:

func main() {
    kingpin.Version(stamp.Version) // or indeed the full .Summary() for everything
    kingpin.Parse()
    // ...
}

Documentation

Overview

Package stamp provides build-time workspace status information at runtime, including the revision version and build metadata.

Index

• Variables
• func BuildSummary() string
• func CodeSummary() string
• func Summary() string
• func Time() time.Time

Variables

var (
	// User is the username of the account that built the library.
	User string

	// Host is the unqualified hostname of the machine the library was
	// built on.
	Host string
)

var (
	// Commit is the unique identifier of the revision that was built
	// to produce this library. If using the provided `workspace_status`
	// script, this is the SHA-1 hash of the revision.
	Commit string

	// Branch is the name of the branch the above commit was on at
	// the time the library was built.
	// N.B. When using Git, most CI systems check out a specific commit,
	// meaning Git is in a detached HEAD state, so this will usually be
	// "HEAD" for official releases.
	Branch string

	// Version is a human-readable alternative to Commit, providing
	// more context about where we are in the history. If using the
	// provided `workspace_status` commands for Git, this is the output
	// of `git describe --always --tags --dirty`.
	Version string
)

Functions

func BuildSummary

func BuildSummary() string

BuildSummary returns a human-readable summary of the build metadata, e.g. "built with go1.11.5 by george@dev on 2019-02-01T22:45:21Z".

func CodeSummary

func CodeSummary() string

CodeSummary returns a human-readable summary of the revision metadata, e.g. "1.0.0-1-g157ed0b (157ed0bb7b7de3c4c2e750a5b9ee675e2997ea80, master)".

func Summary

func Summary() string

Summary returns a human-readable summary of the revision version and build metadata, e.g. "1.0.0-1-g157ed0b (157ed0bb7b7de3c4c2e750a5b9ee675e2997ea80, master), built with go1.11.5 by george@dev on 2019-02-01T22:45:21Z".

func Time

func Time() time.Time

Time returns the build time string in its native representation. If the build time was not provided, returns the zero time instant.