buildinfo

README

buildinfo

Golang utility to generate build information suitable for embedding in code.

Applications usually expose their version information in one way or another. Up until this point, in the context of Golang, this information was embedded into the compiled artifact via linker flags during building. The actual information was calculated via a series of (shell-) commands. Since all of this requires orchestration, this was usually done using some kind of build system (Make, Bazel, ...)

buildinfo aims to remove all that cruft, by collecting and exposing the build information in a single call.

Despite the name, it has actually no relation and very little similarity to debug.Buildinfo, which is available since Golang 1.18.

Usage

Typically buildinfo is used as Golang generator.

It can create boilerplate code for setting up the required code on its own:

buildinfo --generate golang-embed --filename version.go

This will create a file named version.go in the current working directory.

To prevent muddying your repository, it is recommended to add the generator output to the VCS ignore list. To allow your project to run and compile in a development setting, where version information is not of the utmost importance, a minimalistic version should be kept under version control nontheless. To be more precise, create two files in the directory next to your code with the go:generate instruction:

.gitignore

buildinfo.json

buildinfo.json

{}

Building

buildinfo (the library) does not require any pre-processing. buildinfo (the tool) lives in the tools subdirectory. Generated files are shipped with the source code and can be recreated using the respective utilities.

Man pages

cd ./tools
go install github.com/mmarkdown/mmark/v2@latest
go generate ./man

Build information

cd ./tools
go install github.com/UiP9AV6Y/buildinfo/tools/cmd/buildinfo@latest
go generate ./version

buildinfo

cd ./tools
go build -o buildinfo ./cmd/buildinfo

Example

buildinfo dogfeeds its own product in ./tools/version/version.go.

Alternatives

• go-pogo/buildinfo
• jfrog/build-info-go
• hlandau/buildinfo

License

BSD 4-Clause, see LICENSE.

Documentation

Index

• Constants
• Variables
• type BuildInfo
  • func MustParse(info []byte) *BuildInfo
  • func New() *BuildInfo
  • func NewBuildInfo(v *VersionInfo, e *EnvironmentInfo) *BuildInfo
  • func Parse(info []byte) (result *BuildInfo, err error)
  • func TryParse(info []byte) *BuildInfo
  • func (i *BuildInfo) Clone() *BuildInfo
  • func (i *BuildInfo) Equal(o *BuildInfo) bool
  • func (i *BuildInfo) JSON() ([]byte, error)
  • func (i *BuildInfo) Print(program string) string
  • func (i *BuildInfo) String() string
• type EnvironmentInfo
  • func NewEnvironmentInfo() *EnvironmentInfo
  • func (i *EnvironmentInfo) Clone() *EnvironmentInfo
  • func (i *EnvironmentInfo) Equal(o *EnvironmentInfo) bool
  • func (i *EnvironmentInfo) String() string
  • func (i *EnvironmentInfo) UserHost() string
• type VersionInfo
  • func NewVersionInfo() *VersionInfo
  • func (i *VersionInfo) Clone() *VersionInfo
  • func (i *VersionInfo) Equal(o *VersionInfo) bool
  • func (i *VersionInfo) ShortRevision() string
  • func (i *VersionInfo) String() string
  • func (i *VersionInfo) VersionRevision() string

Constants

const (
	// default value for EnvironmentInfo.User
	DefaultUser = "unknown"
	// default value for EnvironmentInfo.Host
	DefaultHost = "localhost"
)

const (
	// default value for VersionInfo.Version
	DefaultVersion = "0.0.0"
	// default value for VersionInfo.Revision
	DefaultRevision = "HEAD"
	// default value for VersionInfo.Branch
	DefaultBranch = "trunk"
)

Variables

var (
	GoVersion = runtime.Version()
	GoOS      = runtime.GOOS
	GoArch    = runtime.GOARCH
)

Types

type BuildInfo

type BuildInfo struct {
	*VersionInfo
	*EnvironmentInfo
}

BuildInfo is a container for version- and environment information

func MustParse

func MustParse(info []byte) *BuildInfo

MustParse calls Parse and panics on any error

func New

func New() *BuildInfo

New returns a BuildInfo instance with default values

func NewBuildInfo

func NewBuildInfo(v *VersionInfo, e *EnvironmentInfo) *BuildInfo

NewBuildInfo returns a BuildInfo instance using the provided values

func Parse

func Parse(info []byte) (result *BuildInfo, err error)

Parse unmarshals the given JSON byte data into a BuildInfo instance. An empty input or even nil are considered valid values, and return a default instance.

func TryParse

func TryParse(info []byte) *BuildInfo

TryParse calls Parse and returns a default instance in case of an error

func (*BuildInfo) Clone

func (i *BuildInfo) Clone() *BuildInfo

Clone creates an independant copy of itself.

func (*BuildInfo) Equal

func (i *BuildInfo) Equal(o *BuildInfo) bool

Equal compares the fields of this instance to the given one

func (*BuildInfo) JSON

func (i *BuildInfo) JSON() ([]byte, error)

JSON is a wrapper for json.Marshal using the instance as parameter

func (*BuildInfo) Print

func (i *BuildInfo) Print(program string) string

Print returns version- and environment information.

func (*BuildInfo) String

func (i *BuildInfo) String() string

String returns the Version- and Environment information concatenated

type EnvironmentInfo

type EnvironmentInfo struct {
	User string    `json:"user,omitempty"`
	Host string    `json:"host,omitempty"`
	Date time.Time `json:"date,omitempty"`
}

EnvironmentInfo contains data about the build context of a project

func NewEnvironmentInfo

func NewEnvironmentInfo() *EnvironmentInfo

NewEnvironmentInfo returns a EnvironmentInfo instance with default values

func (*EnvironmentInfo) Clone

func (i *EnvironmentInfo) Clone() *EnvironmentInfo

Clone creates an independant copy of itself.

func (*EnvironmentInfo) Equal

func (i *EnvironmentInfo) Equal(o *EnvironmentInfo) bool

Equal compares the fields of this instance to the given one

func (*EnvironmentInfo) String

func (i *EnvironmentInfo) String() string

String returns build user, -host, and -date information.

func (*EnvironmentInfo) UserHost

func (i *EnvironmentInfo) UserHost() string

UserHost returns the User and Host value concatenated by an @ character

type VersionInfo

type VersionInfo struct {
	Version  string `json:"version,omitempty"`
	Revision string `json:"revision,omitempty"`
	Branch   string `json:"branch,omitempty"`
}

VersionInfo contains data about the project state in a version control system

func NewVersionInfo

func NewVersionInfo() *VersionInfo

NewVersionInfo returns a VersionInfo instance with default values

func (*VersionInfo) Clone

func (i *VersionInfo) Clone() *VersionInfo

Clone creates an independant copy of itself.

func (*VersionInfo) Equal

func (i *VersionInfo) Equal(o *VersionInfo) bool

Equal compares the fields of this instance to the given one

func (*VersionInfo) ShortRevision

func (i *VersionInfo) ShortRevision() string

ShortRevision returns the truncated Revision. If that value is less than 8 characters long, the result is the Revision value itself

func (*VersionInfo) String

func (i *VersionInfo) String() string

String returns version, branch and revision information.

func (*VersionInfo) VersionRevision

func (i *VersionInfo) VersionRevision() string

VersionRevision returns the Version and (short) Revision value concatenated by an hyphen character