[build] rename buildTag to version

As most commonly it will be used as version marker it is renamed to
version.

Change-Id: Ic9137e9540eb553ecf5e98b92a10fa0c4c220bea

Author: xobotyi

build/doc.go

@@ -3,7 +3,22 @@
 //
 // The package automatically extracts build information from Go's runtime debug data,
 // including Go version, target OS and architecture, and version control system details.
-// It also provides methods to format this information as human-readable text or structured data.
+// It also provides methods to format this information as human-readable text or structured
+// data.
+//
+// The Info struct has the following fields:
+//   - Version (user-defined, settable via ldflags or taken from debug info)
+//   - BuildTime (user-defined, settable via ldflags)
+//   - GoVersion
+//   - GoOS
+//   - GoArch
+//   - VCSRevision
+//   - VCSModified
+//
+// The ToFields() method returns fields in the same order as described.
+//
+// Any of following fields can be set via ldflags, and, if so, they won't be overridden
+// by parsed info, except for GoVersion.
 //
 // # Usage
 //
@@ -28,9 +43,10 @@
 // # Custom Build Information
 //
 // Info can also include custom information that is expected to be set by developer at build time
-// via ldflags as follows:
+// via ldflags as follows (note the variables names):
 //
-//	`go build -ldflags "-X 'dev.gaijin.team/go/golib/build.time=<current-time>' -X 'dev.gaijin.team/go/golib/build.vcsTag=v1.0.0'"``
+//	go build -ldflags "-X 'dev.gaijin.team/go/golib/build.version=v1.0.0' -X 'dev.gaijin.team/go/golib/build.buildTime=<current-time>'"
 //
+// If not set, these fields will be populated from Go build info or default to "unknown".
 //nolint
 package build

build/info.go

@@ -20,14 +20,24 @@ var (
 	vcsRevision = unknown
 	vcsModified = unknown
 
-	time   = unknown
-	vcsTag = unknown
+	buildTime = unknown
+	version   = unknown
 )
 
 // Info represents the build information for a Go binary.
 // It contains details about the Go environment used for building,
 // version control system state, and custom build-time information.
 type Info struct {
+	//
+	// User-defined information, set at build time.
+	//
+
+	// Version is the version of the binary. In case parameter is not set,
+	// via linker flags it will be taken from debug.ReadBuildInfo().
+	Version string `json:"version"`
+	// BuildTime is the build time.
+	BuildTime string `json:"build-time"`
+
 	//
 	// Basic go information, detected automatically.
 	//
@@ -48,25 +58,16 @@ type Info struct {
 	// VCSModified is the version control system modified status. "true" in case
 	// repo is "dirty".
 	VCSModified string `json:"vcs-modified"`
-
-	//
-	// User-defined information, set at build time.
-	//
-
-	// BuildTime is the build time.
-	BuildTime string `json:"build-time"`
-	// BuildTag is the vcs tag of the commit, binary built from.
-	BuildTag string `json:"build-tag"`
 }
 
 // String returns a human-readable representation of build information.
-// The format includes Go version, OS, architecture, VCS revision, and build details.
+// The format includes version, Go version, OS, architecture, VCS revision, and build details.
 // If the repository was modified (dirty), this is indicated in the output.
-// If a build tag is present, it's included in square brackets. after the revision.
 func (i Info) String() string {
 	b := &strings.Builder{}
 
-	b.WriteString("built with ")
+	b.WriteString(i.Version)
+	b.WriteString(" built with ")
 	b.WriteString(i.GoVersion)
 	b.WriteString(" for ")
 	b.WriteString(i.GoOS)
@@ -75,12 +76,6 @@ func (i Info) String() string {
 	b.WriteString(" from ")
 	b.WriteString(i.VCSRevision)
 
-	if i.BuildTag != unknown {
-		b.WriteString(" [")
-		b.WriteString(i.BuildTag)
-		b.WriteRune(']')
-	}
-
 	if i.VCSModified == "true" {
 		b.WriteString(" (dirty)")
 	}
@@ -96,19 +91,20 @@ func (i Info) String() string {
 // build information as key-value pairs.
 func (i Info) ToFields() fields.List {
 	return fields.List{
+		fields.F("version", i.Version),
 		fields.F("go-version", i.GoVersion),
 		fields.F("go-os", i.GoOS),
 		fields.F("go-arch", i.GoArch),
 		fields.F("vcs-revision", i.VCSRevision),
 		fields.F("vcs-modified", i.VCSModified),
 		fields.F("build-time", i.BuildTime),
-		fields.F("build-tag", i.BuildTag),
 	}
 }
 
 // GetInfo returns the build information.
 // It automatically parses build information from runtime debug data
 // the first time it's called, and caches the result for subsequent calls.
+// Values set via linker flags (-X) are preserved and not overwritten.
 func GetInfo() Info {
 	if !buildInfoParsed {
 		buildInfoParsed = true
@@ -117,22 +113,24 @@ func GetInfo() Info {
 	}
 
 	return Info{
+		Version:     version,
 		GoVersion:   goVersion,
 		GoOS:        goOS,
 		GoArch:      goArch,
 		VCSRevision: vcsRevision,
 		VCSModified: vcsModified,
-		BuildTime:   time,
-		BuildTag:    vcsTag,
+		BuildTime:   buildTime,
 	}
 }
 
 //nolint:gochecknoglobals
-var settingsProcessors = map[string]func(s debug.BuildSetting){
-	"GOOS":         func(s debug.BuildSetting) { goOS = s.Value },
-	"GOARCH":       func(s debug.BuildSetting) { goArch = s.Value },
-	"vcs.revision": func(s debug.BuildSetting) { vcsRevision = s.Value },
-	"vcs.modified": func(s debug.BuildSetting) { vcsModified = s.Value },
+var settingsValues = map[string]*string{
+	"GOOS":         &goOS,
+	"GOARCH":       &goArch,
+	"vcs.revision": &vcsRevision,
+	"vcs.modified": &vcsModified,
+	"build-time":   &buildTime,
+	"version":      &version,
 }
 
 func parseBuildInfo() {
@@ -143,9 +141,13 @@ func parseBuildInfo() {
 
 	goVersion = info.GoVersion
 
+	if version == unknown {
+		version = info.Main.Version
+	}
+
 	for _, s := range info.Settings {
-		if f, ok := settingsProcessors[s.Key]; ok {
-			f(s)
+		if ptr, ok := settingsValues[s.Key]; ok && *ptr == unknown {
+			*ptr = s.Value
 		}
 	}
 }

build/info_test.go

@@ -26,22 +26,22 @@ func TestInfo_String(t *testing.T) { //nolint:tparallel
 				VCSRevision: "abcdef123456",
 				VCSModified: "false",
 				BuildTime:   "2023-07-15T12:34:56Z",
-				BuildTag:    "v1.0.0",
+				Version:     "v1.0.0",
 			},
-			expected: "built with go1.17.5 for linux amd64 from abcdef123456 [v1.0.0] build time 2023-07-15T12:34:56Z",
+			expected: "v1.0.0 built with go1.17.5 for linux amd64 from abcdef123456 build time 2023-07-15T12:34:56Z",
 		},
 		{
-			name: "with unknown build tag",
+			name: "with unknown version",
 			info: build.Info{
 				GoVersion:   "go1.18.0",
 				GoOS:        "darwin",
 				GoArch:      "arm64",
 				VCSRevision: "987654abcdef",
 				VCSModified: "unknown",
 				BuildTime:   "2023-08-20T10:11:12Z",
-				BuildTag:    "unknown",
+				Version:     "unknown",
 			},
-			expected: "built with go1.18.0 for darwin arm64 from 987654abcdef build time 2023-08-20T10:11:12Z",
+			expected: "unknown built with go1.18.0 for darwin arm64 from 987654abcdef build time 2023-08-20T10:11:12Z",
 		},
 		{
 			name: "with dirty repo",
@@ -52,23 +52,24 @@ func TestInfo_String(t *testing.T) { //nolint:tparallel
 				VCSRevision: "1a2b3c4d5e6f",
 				VCSModified: "true",
 				BuildTime:   "2023-09-25T15:16:17Z",
-				BuildTag:    "v2.0.0",
+				Version:     "v2.0.0",
 			},
-			//revive:disable-next-line:line-length-limit
-			expected: "built with go1.19.0 for windows amd64 from 1a2b3c4d5e6f [v2.0.0] (dirty) build time 2023-09-25T15:16:17Z",
+			//nolint:lll
+			expected: "v2.0.0 built with go1.19.0 for windows amd64 from 1a2b3c4d5e6f (dirty) build time 2023-09-25T15:16:17Z",
 		},
 		{
-			name: "unknown build tag and dirty repo",
+			name: "unknown version and dirty repo",
 			info: build.Info{
 				GoVersion:   "go1.20.0",
 				GoOS:        "freebsd",
 				GoArch:      "amd64",
 				VCSRevision: "a1b2c3d4e5f6",
 				VCSModified: "true",
 				BuildTime:   "2023-10-30T20:21:22Z",
-				BuildTag:    "unknown",
+				Version:     "unknown",
 			},
-			expected: "built with go1.20.0 for freebsd amd64 from a1b2c3d4e5f6 (dirty) build time 2023-10-30T20:21:22Z",
+			//nolint:lll
+			expected: "unknown built with go1.20.0 for freebsd amd64 from a1b2c3d4e5f6 (dirty) build time 2023-10-30T20:21:22Z",
 		},
 	}
 
@@ -89,23 +90,23 @@ func TestInfo_ToFields(t *testing.T) {
 		VCSRevision: "abcdef123456",
 		VCSModified: "false",
 		BuildTime:   "2023-07-15T12:34:56Z",
-		BuildTag:    "v1.0.0",
+		Version:     "v1.0.0",
 	}
 
 	expectedFields := fields.List{
+		fields.F("version", "v1.0.0"),
 		fields.F("go-version", "go1.17.5"),
 		fields.F("go-os", "linux"),
 		fields.F("go-arch", "amd64"),
 		fields.F("vcs-revision", "abcdef123456"),
 		fields.F("vcs-modified", "false"),
 		fields.F("build-time", "2023-07-15T12:34:56Z"),
-		fields.F("build-tag", "v1.0.0"),
 	}
 
 	resultFields := info.ToFields()
 
 	// Test length
-	assert.Equal(t, len(expectedFields), len(resultFields), "fields list length should match")
+	assert.Len(t, resultFields, len(expectedFields), "fields list length should match")
 
 	// Test each field
 	for i := range len(expectedFields) {