Compile git version inside go binary

Compile git version inside go binary

Abstract

在我们编写的程序中总是希望可以直接查阅程序的版本，通过--version参数就会输出如下版本信息。

BuildTime: 2018-10-17 17:31:36 +0800 CST (762h17m59.837121151s ago)
BuildHost: gaorong-TM1604
Branch: master
CommitID: acd4a73a5424d3b328c527afea0983d797499ae3
Tags: v0.1.6
Version: v0.1.6
RepoStatus: dirty

我们可以直接将版本信息写在源码里面，但是每次都需要修改源码，比较繁琐； golang 提供了-ldflags flag在编译时动态注入版本信息，生成相关代码，这种方式使用很广泛，本文将会对其进行简单介绍; 最后还会介绍一种特殊的方式： 通过go generate 命令自动生成版本信息代码。

Backgroud

最简单的输出版本信息的方式如下：

package main

import (
    "flag"
    "fmt"
)

var (
    version = flag.Bool("version", false， "print version and exit.")
)

const (
    versionStr = "v0.0.1"
)

func main() {
    flag.Parse()
    if *version {
        fmt.Println("version: %s", versionStr)
    }

    // do something...
}

虽然可以打印出程序的版本信息， 但是每次都需要重新修改versionStr变量的值， 比较繁琐。

动态编译版本信息

动态编译版本信息是利用 go build 的 -ldflags 参数在编译时候传入版本信息， 在主程序中定义并使用变量：

package main

import "fmt"

var Version string
var Buildtime string

func main() {
    fmt.Printf("Version: %s\n", Version)
    fmt.Printf("Buildtime: %s\n", Buildtime)
}

在Makefile对上述变量赋值是中并传递进去的，如下：

VERSION := $(shell git rev-parse --short HEAD)
BUILDTIME := $(shell date -u '+%Y-%m-%dT%H:%M:%SZ')

GOLDFLAGS += -X main.Version=$(VERSION)
GOLDFLAGS += -X main.Buildtime=$(BUILDTIME)
GOFLAGS = -ldflags "$(GOLDFLAGS)"

build:
    go build -o mybinary $(GOFLAGS) .

首先获取git的版本信息， 然后在执行go build时， 通过ldflag 参数赋值给main package中的Version, BuildTime变量。
这种方式是使用最为广泛的， docker, kubernetes都是通过这种方式来生成版本信息。

利用go generate生成相关代码

上面动态编译版本信息是通过编译时赋值给变量，其实我们也可以换一种思路：在方法一中我们发现每次版本升级都需要修改代码，替换对应版本信息变量的值，如果我们能够自动化地生成版本信息相关代码，那也可以实现动态编译版本信息。

首先我们新建一个package: buildinfo, 包含buildinfo.go, generat_build_info.go 两个文件。
buildinfo.go 创建buildInfo结构体，包含所有的版本信息及其对应的method:

package buildinfo

//go:generate go run generate-build-info.go

import (
    "fmt"
    "strings"
    "time"
)

type buildInfo struct {
    Time        time.Time
    Host        string
    Branch      string
    CommitID    string
    Tags        []string
    Version     string
    IsRepoClean bool
}

func (bi buildInfo) Show() {
    fmt.Printf("BuildTime: %s (%s ago)\n", bi.Time, time.Since(bi.Time))
    fmt.Printf("BuildHost: %s\n", bi.Host)
    fmt.Printf("Branch: %s\n", bi.Branch)
    fmt.Printf("CommitID: %s\n", bi.CommitID)
    fmt.Printf("Tags: %s\n", strings.Join(bi.Tags, ", "))
    fmt.Printf("Version: %s\n", bi.Version)
    repoStatus := "dirty"
    if bi.IsRepoClean {
        repoStatus = "clean"
    }
    fmt.Printf("RepoStatus: %s\n", repoStatus)
}

// New returns the build time meta variables
func New() buildInfo {
    return buildInfo{
        Time:        buildTime,
        Host:        buildHost,
        Branch:      branch,
        CommitID:    commitID,
        Tags:        gitTags,
        Version:     version,
        IsRepoClean: isRepoClean,
    }
}

可以看到New function会初始化整个结构体， 使用到的变量来自generated_build_info.go 文件。 generated_build_info.go 文件通过名字就可以知道他是一个自动生成的文件，那他是如何自动生成的呐？ 仔细查看原来上述代码中包含了一行注释//go:generate go run generate-build-info.go, 就是这一行代码生成的内容。
在golang 中， 提供了go generate subcommand 来自动生成代码， 具体的使用参见官方解释, 使用时在文件前面添加注释//go:generate command ， 然后执行 go generate 就会自动搜索找到拥有该注释的文件，并调用指定的command来生成代码， 此处执行的就是go run generate-build-info.go， generate-build-info.go的内容如下：

// +build ignore

package main

import (
    "bytes"
    "fmt"
    "log"
    "os"
    "os/exec"
    "path"
    "strings"
    "text/template"
    "time"
)

var hostname, _ = os.Hostname()

const goSourceTemplate = `package buildinfo
// Code generated by go generate; DO NOT EDIT.

import "time"

var (
    buildTime = time.Unix({{ .Timestamp }}, 0)
    gitTags      = {{ .Tags }}
)

const (
    buildHost   = {{ .Hostname }}
    branch      = {{ .Branch }}
    commitID    = {{ .CommitID }}
    version     = {{ .Version }}
    isRepoClean = {{ .IsRepoClean }}
)`

func main() {
    checkGitEnv()
    f, err := os.Create("generated_build_info.go")
    if err != nil {
        log.Print(err)
        os.Exit(1)
    }
    defer f.Close()
    if err := template.Must(template.New("").Funcs(nil).Parse(goSourceTemplate)).Execute(f, struct {
        Timestamp   int64
        Hostname    string
        Branch      string
        CommitID    string
        Tags        string
        Version     string
        IsRepoClean bool
    }{
        Timestamp:   time.Now().Unix(),
        Hostname:    toStrintLiteral(hostname),
        Branch:      toStrintLiteral(getBranch()),
        CommitID:    toStrintLiteral(getCommitID()),
        Tags:        toStringArrayLiteral(getTags()),
        Version:     toStrintLiteral(getVersion()),
        IsRepoClean: isRepoClean(),
    }); err != nil {
        log.Print(err)
        os.Exit(1)
    }
}

func checkGitEnv() {
    gitDir := os.Getenv("GIT_DIR")
    if gitDir == "" {
        log.Print("GIT_DIR must be set")
        os.Exit(1)
    }
    if gitWorkTree := os.Getenv("GIT_WORK_TREE"); gitWorkTree == "" {
        os.Setenv("GIT_WORK_TREE", path.Dir(gitDir))
    }
    fmt.Printf("Generating build info from GIT_DIR=%s, GIT_WORK_TREE=%s\n", green.T(gitDir), green.T(os.Getenv("GIT_WORK_TREE")))
}

func getBranch() string {
    return strings.TrimRight(run(`git`, `rev-parse`, `--abbrev-ref`, `HEAD`), "\n")
}

func getCommitID() string {
    return strings.TrimRight(run(`git`, `rev-parse`, `HEAD`), "\n")
}

func getTags() []string {
    gitOutput := strings.TrimRight(run(`git`, `tag`, `-l`, `--points-at`, `HEAD`), "\n")
    if len(gitOutput) == 0 {
        return nil
    }
    return strings.Split(gitOutput, "\n")
}

func isRepoClean() bool {
    return run(`git`, `status`, `--short`) == ""
}

func getVersion() string {
    tags := getTags()
    if isRepoClean() && len(tags) == 1 {
        return tags[0]
    }
    return "latest"
}

func run(prog string, args ...string) string {
    cmd := exec.Command(prog, args...)
    bs, err := cmd.Output()
    if err != nil {
        return ""
    }
    return string(bs)
}

func toStringArrayLiteral(arr []string) string {
    var items []string
    for _, s := range arr {
        items = append(items, toStrintLiteral(s))
    }
    return fmt.Sprintf("[]string{%s}", strings.Join(items, ", "))
}

func toStrintLiteral(s string) string {
    return fmt.Sprintf("%q", s)
}

// xterm

type xterm struct {
    f uint8
    b uint8
}

func (x xterm) T(text string) string {
    buf := &bytes.Buffer{}
    fmt.Fprintf(buf, "\x1b[%d;%dm", x.b, x.f)
    buf.WriteString(text)
    buf.WriteString("\x1b[m")
    return buf.String()
}

var green = xterm{f: 32, b: 1}

可以看到主要就是通过git获取tag作为版本， 并用template库生成内容写入generated_build_info.go文件中，该代码是直接被go run调用必须因此包含main function, 同时buildinfo package只是一个库， 会被其他程序所应用， 一个程序中包含两个main function编译就会报错， 需要在头部添加// +build ignore 注释来声明在编译时不需要包含该文件。最后生成的generated_build_info.go文件内容如下，上面buildinfo.go New function中所使用到的全部变量都是来自于自动生成的这个文件中。

package buildinfo
// Code generated by go generate; DO NOT EDIT.

import "time"

var (
    buildTime = time.Unix(1539768696, 0)
    gitTags      = []string{"v0.1.6"}
)

const (
    buildHost   = "gaorong-TM1604"
    branch      = "master"
    commitID    = "acd4a73a5424d3b328c527afea0983d797499ae3"
    version     = "latest"
    isRepoClean = false
)

上述文件是自动生成的， 无需提交到git中， 所以总共两个文件就构成了buildinfo package，使用的时候在makefile中调用go generate即可。
需要注意的是，在编写程序的时候， buildinfo作为一个独立git package 被主程序所引用，则需要通过GIT_DIR环境变量告诉git获取哪个repo信息， 否则获取到的信息是buildinfo repo而不是主程序repo的信息。 一个完整的命令如下：GIT_DIR=$(PWD)/.git go generate -v $(BUILD_INFO_PKG)， 其中BUILD_INFO_PKG 是buildinfo package所在的位置。
总的来说buildinfo package就是通过 go generate 命令结合template 库根据git信息自动生成binary版本信息。