meta

README

Go Build Metadata

✨ Common application metadata for use with go build and ldflags

Motivations

The Go toolchain has a feature where you can specify the value for a named variable at go build-time on the command line, and that value will be embedded into that variable in the resulting binary.

This feature is primarily used for embedding a version string or git SHA, so that the provenance of the resulting binary can be traced back to the exact ref from which it was produced.

See this blog post from Cloudflare for an introduction.

This library provides three things:

1. A number of appropriately named variables that can accept values when running go build.
2. The automatic conversion of string values into complex types (like url.URL) where appropriate.
3. Public functions for retrieving these typed values.

This library also has the capacity to accept a wide variety of relevant build values, and uses a short import path so that they can be succinctly configured as part of a go build command.

Installing

This library can be installed by running:

go get -u jdk.sh/meta

Usage

Example

Create a main.go file containing the following:

package main

import (
    "fmt"
    "jdk.sh/meta"
)

func main() {
    fmt.Println(
        "version", meta.Version(),
        "built on", meta.Date(),
    )
}

Build your main.go into a binary using go build. Notice the usage of -ldflags, specifying values for the variables jdk.sh/meta.version and jdk.sh/meta.date:

go build -ldflags "\
    -X 'jdk.sh/meta.version=v1.2.3' \
    -X 'jdk.sh/meta.date=$(date -R)' \
  " main.go

Finally, execute the program and observe that the given values are now "baked" into the resulting binary:

./main
version v1.2.3 built on 2019-08-23 18:00:00 +0000 UTC

Variables

Name	Purpose
jdk.sh/meta.author	The name of the application author. May contain their name, email address, or optionally both.
jdk.sh/meta.author_url	URL for the application author. Typically links to the author's personal homepage or Github profile.
jdk.sh/meta.copyright	The copyright for the application. Typically the name if the author or organization, sometimes prefixed with a year or year range.
jdk.sh/meta.date	The time that the application was built. Supports several common formats.
jdk.sh/meta.desc	Description for the application. Typically a longer statement describing what the application does.
jdk.sh/meta.dev	The development status for the application. An application in development mode may indicate that it's using experimental or untested features, and should be used with caution.
jdk.sh/meta.docs	URL for application documentation. Typically links to a page where a user can find technical documentation.
jdk.sh/meta.license	The license identifier for the application. Should not the full license body, but one of the identifiers from https://spdx.org/licenses, so that the type of license can be easily determined.
jdk.sh/meta.license_url	URL for the application license. Typically links to a page where the verbatim license body is available.
jdk.sh/meta.name	The name of the application. Typically named the same as the binary, or for display in an error or help message.
jdk.sh/meta.note	An arbitrary message for the application. Can be used to store a message about the build environment, release, etc.
jdk.sh/meta.sha	Git SHA that was used to build the application. A 40 character "long" SHA should be provided.
jdk.sh/meta.src	URL for the application source code. Typically links to a repository where a user can browse or clone the source code.
jdk.sh/meta.title	The title of the application. Typically a full or non-abbreviated form of the application name.
jdk.sh/meta.url	URL for the application homepage. Typically links to a page where a user can learn more about the application.
jdk.sh/meta.version	The version slug for the application. The value can be used to point back to a specific tag or release. Supports semver, see https://semver.org.

License

This code is distributed under the MIT License, see LICENSE.txt for more information.

Documentation

Overview

Package meta provides common application metadata for use with go build and ldflags. This package is intended to be imported, where variable values can be set by using -X arguments, tp the -ldflags argument, when running go build. See https://pkg.go.dev/cmd/go and https://pkg.go.dev/cmd/link.

List of variable names:

jdk.sh/meta.author
jdk.sh/meta.author_url
jdk.sh/meta.copyright
jdk.sh/meta.date
jdk.sh/meta.desc
jdk.sh/meta.dev
jdk.sh/meta.docs
jdk.sh/meta.license
jdk.sh/meta.license_url
jdk.sh/meta.name
jdk.sh/meta.note
jdk.sh/meta.sha
jdk.sh/meta.src
jdk.sh/meta.title
jdk.sh/meta.url
jdk.sh/meta.version

Index

• func Arch() string
• func Author() string
• func AuthorEmail() string
• func AuthorURL() *u.URL
• func Copyright() string
• func Date() *time.Time
• func Description() string
• func Development() bool
• func Docs() *u.URL
• func Go() string
• func License() string
• func LicenseURL() *u.URL
• func Name() string
• func Note() string
• func OS() string
• func SHA() string
• func ShortSHA() string
• func Source() *u.URL
• func Title() string
• func URL() *u.URL
• func Version() string
• func VersionBuild() string
• func VersionMajor() string
• func VersionMinor() string
• func VersionPatch() string
• func VersionPreRelease() string

Functions

func Arch

func Arch() string

Arch is the architecture target that the application is running on.

func Author

func Author() string

Author is the name of the application author.

func AuthorEmail

func AuthorEmail() string

AuthorEmail is the email address for the application author.

func AuthorURL

func AuthorURL() *u.URL

AuthorURL is the homepage URL for the application author.

func Copyright

func Copyright() string

Copyright is the copyright for the application.

func Date

func Date() *time.Time

Date is the time at which the application was built.

func Description

func Description() string

Description is the description of the application.

func Development

func Development() bool

Development is the development status for the application.

func Docs

func Docs() *u.URL

Docs is the documentation URL for the application.

func Go

func Go() string

Go is the version of the Go runtime that the application is running on.

func License

func License() string

License is the license identifier for the application.

func LicenseURL

func LicenseURL() *u.URL

LicenseURL is the license URL for the application.

func Name

func Name() string

Name is the name of the application.

func Note

func Note() string

Note is an arbitrary message for the application.

func OS

func OS() string

OS is the operating system target that the application is running on.

func SHA

func SHA() string

SHA is the git SHA used to build the application.

func ShortSHA

func ShortSHA() string

ShortSHA is the git "short" SHA used to build the application.

func Source

func Source() *u.URL

Source is the URL for the application source code.

func Title

func Title() string

Title is the title of the application.

func URL

func URL() *u.URL

URL is the homepage URL for the application.

func Version

func Version() string

Version is the version slug for the application.

func VersionBuild

func VersionBuild() string

VersionBuild is the semver build metadata version. See https://semver.org.

func VersionMajor

func VersionMajor() string

VersionMajor is the semver major version. See https://semver.org.

func VersionMinor

func VersionMinor() string

VersionMinor is the semver minor version. See https://semver.org.

func VersionPatch

func VersionPatch() string

VersionPatch is the semver patch version. See https://semver.org.

func VersionPreRelease

func VersionPreRelease() string

VersionPreRelease is the semver pre-release version. See https://semver.org.