meta

package module

v0.1.0 Latest Latest Go to latest Published: Oct 3, 2021 License: MIT Imports: 8 Imported by: 5

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/joshdk/meta

Links

Open Source Insights

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:

A number of appropriately named variables that can accept values when running go build.
The automatic conversion of string values into complex types (like url.URL) where appropriate.
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