gover

Documentation

Overview

Package gover implements support for Go toolchain versions like 1.21.0 and 1.21rc1. (For historical reasons, Go does not use semver for its toolchains.) This package provides the same basic analysis that golang.org/x/mod/semver does for semver. It also provides some helpers for extracting versions from go.mod files and for dealing with module.Versions that may use Go versions or semver depending on the module path.

Index

• Constants
• Variables
• func Compare(x, y string) int
• func FromGoMod(mf *modfile.File) string
• func FromGoWork(wf *modfile.WorkFile) string
• func FromToolchain(name string) string
• func GoModLookup(gomod []byte, key string) string
• func IsLang(x string) bool
• func IsPrerelease(x string) bool
• func IsToolchain(path string) bool
• func IsValid(x string) bool
• func Lang(x string) string
• func Local() string
• func LocalToolchain() string
• func Max(x, y string) string
• func ModCompare(path string, x, y string) int
• func ModIsPrefix(path, vers string) bool
• func ModIsPrerelease(path, vers string) bool
• func ModIsValid(path, vers string) bool
• func ModMajorMinor(path, vers string) string
• func ModSort(list []module.Version)
• func Prev(x string) string
• func ToolchainMax(x, y string) string
• type Switcher
• type TooNewError
  • func (e *TooNewError) Error() string
  • func (e *TooNewError) Is(err error) bool

Constants

const (
	// narrowAllVersion is the Go version at which the
	// module-module "all" pattern no longer closes over the dependencies of
	// tests outside of the main module.
	NarrowAllVersion = "1.16"

	// DefaultGoModVersion is the Go version to assume for go.mod files
	// that do not declare a Go version. The go command has been
	// writing go versions to modules since Go 1.12, so a go.mod
	// without a version is either very old or recently hand-written.
	// Since we can't tell which, we have to assume it's very old.
	// The semantics of the go.mod changed at Go 1.17 to support
	// graph pruning. If see a go.mod without a go line, we have to
	// assume Go 1.16 so that we interpret the requirements correctly.
	// Note that this default must stay at Go 1.16; it cannot be moved forward.
	DefaultGoModVersion = "1.16"

	// DefaultGoWorkVersion is the Go version to assume for go.work files
	// that do not declare a Go version. Workspaces were added in Go 1.18,
	// so use that.
	DefaultGoWorkVersion = "1.18"

	// ExplicitIndirectVersion is the Go version at which a
	// module's go.mod file is expected to list explicit requirements on every
	// module that provides any package transitively imported by that module.
	//
	// Other indirect dependencies of such a module can be safely pruned out of
	// the module graph; see https://golang.org/ref/mod#graph-pruning.
	ExplicitIndirectVersion = "1.17"

	// separateIndirectVersion is the Go version at which
	// "// indirect" dependencies are added in a block separate from the direct
	// ones. See https://golang.org/issue/45965.
	SeparateIndirectVersion = "1.17"

	// tidyGoModSumVersion is the Go version at which
	// 'go mod tidy' preserves go.mod checksums needed to build test dependencies
	// of packages in "all", so that 'go test all' can be run without checksum
	// errors.
	// See https://go.dev/issue/56222.
	TidyGoModSumVersion = "1.21"

	// goStrictVersion is the Go version at which the Go versions
	// became "strict" in the sense that, restricted to modules at this version
	// or later, every module must have a go version line ≥ all its dependencies.
	// It is also the version after which "too new" a version is considered a fatal error.
	GoStrictVersion = "1.21"
)

Variables

var ErrTooNew = errors.New("module too new")

var Startup struct {
	GOTOOLCHAIN   string // $GOTOOLCHAIN setting
	AutoFile      string // go.mod or go.work file consulted
	AutoGoVersion string // go line found in file
	AutoToolchain string // toolchain line found in file
}

Startup records the information that went into the startup-time version switch. It is initialized by switchGoToolchain.

var TestVersion string

TestVersion is initialized in the go command test binary to be $TESTGO_VERSION, to allow tests to override the go command's idea of its own version as returned by Local.

Functions

func Compare

func Compare(x, y string) int

Compare returns -1, 0, or +1 depending on whether x < y, x == y, or x > y, interpreted as toolchain versions. The versions x and y must not begin with a "go" prefix: just "1.21" not "go1.21". Malformed versions compare less than well-formed versions and equal to each other. The language version "1.21" compares less than the release candidate and eventual releases "1.21rc1" and "1.21.0".

func FromGoMod

func FromGoMod(mf *modfile.File) string

FromGoMod returns the go version from the go.mod file. It returns DefaultGoModVersion if the go.mod file does not contain a go line or if mf is nil.

func FromGoWork

func FromGoWork(wf *modfile.WorkFile) string

FromGoWork returns the go version from the go.mod file. It returns DefaultGoWorkVersion if the go.mod file does not contain a go line or if wf is nil.

func FromToolchain

func FromToolchain(name string) string

FromToolchain returns the Go version for the named toolchain, derived from the name itself (not by running the toolchain). A toolchain is named "goVERSION". A suffix after the VERSION introduced by a -, space, or tab is removed. Examples:

FromToolchain("go1.2.3") == "1.2.3"
FromToolchain("go1.2.3-bigcorp") == "1.2.3"
FromToolchain("invalid") == ""

func GoModLookup

func GoModLookup(gomod []byte, key string) string

GoModLookup takes go.mod or go.work content, finds the first line in the file starting with the given key, and returns the value associated with that key.

Lookup should only be used with non-factored verbs such as "go" and "toolchain", usually to find versions or version-like strings.

func IsLang

func IsLang(x string) bool

IsLang reports whether v denotes the overall Go language version and not a specific release. Starting with the Go 1.21 release, "1.x" denotes the overall language version; the first release is "1.x.0". The distinction is important because the relative ordering is

1.21 < 1.21rc1 < 1.21.0

meaning that Go 1.21rc1 and Go 1.21.0 will both handle go.mod files that say "go 1.21", but Go 1.21rc1 will not handle files that say "go 1.21.0".

func IsPrerelease

func IsPrerelease(x string) bool

IsPrerelease reports whether v denotes a Go prerelease version.

func IsToolchain

func IsToolchain(path string) bool

IsToolchain reports whether the module path corresponds to the virtual, non-downloadable module tracking go or toolchain directives in the go.mod file.

Note that IsToolchain only matches "go" and "toolchain", not the real, downloadable module "golang.org/toolchain" containing toolchain files.

IsToolchain("go") = true
IsToolchain("toolchain") = true
IsToolchain("golang.org/x/tools") = false
IsToolchain("golang.org/toolchain") = false

func IsValid

func IsValid(x string) bool

IsValid reports whether the version x is valid.

func Lang

func Lang(x string) string

Lang returns the Go language version. For example, Lang("1.2.3") == "1.2".

func Local

func Local() string

Local returns the local Go version, the one implemented by this go command.

func LocalToolchain

func LocalToolchain() string

LocalToolchain returns the local toolchain name, the one implemented by this go command.

func Max

func Max(x, y string) string

Max returns the maximum of x and y interpreted as toolchain versions, compared using Compare. If x and y compare equal, Max returns x.

func ModCompare

func ModCompare(path string, x, y string) int

ModCompare returns the result of comparing the versions x and y for the module with the given path. The path is necessary because the "go" and "toolchain" modules use a different version syntax and semantics (gover, this package) than most modules (semver).

func ModIsPrefix

func ModIsPrefix(path, vers string) bool

ModIsPrefix reports whether v is a valid version syntax prefix for the module with the given path. The caller is assumed to have checked that ModIsValid(path, vers) is true.

func ModIsPrerelease

func ModIsPrerelease(path, vers string) bool

ModIsPrerelease reports whether v is a prerelease version for the module with the given path. The caller is assumed to have checked that ModIsValid(path, vers) is true.

func ModIsValid

func ModIsValid(path, vers string) bool

ModIsValid reports whether vers is a valid version syntax for the module with the given path.

func ModMajorMinor

func ModMajorMinor(path, vers string) string

ModMajorMinor returns the "major.minor" truncation of the version v, for use as a prefix in "@patch" queries.

func ModSort

func ModSort(list []module.Version)

ModSort is like module.Sort but understands the "go" and "toolchain" modules and their version ordering.

func Prev

func Prev(x string) string

Prev returns the Go major release immediately preceding v, or v itself if v is the first Go major release (1.0) or not a supported Go version.

Examples:

Prev("1.2") = "1.1"
Prev("1.3rc4") = "1.2"

func ToolchainMax

func ToolchainMax(x, y string) string

Toolchain returns the maximum of x and y interpreted as toolchain names, compared using Compare(FromToolchain(x), FromToolchain(y)). If x and y compare equal, Max returns x.

Types

type Switcher

type Switcher interface {
	Error(err error)
	Switch(ctx context.Context)
}

A Switcher provides the ability to switch to a new toolchain in response to TooNewErrors. See cmd/go/internal/toolchain.Switcher for documentation.

type TooNewError

type TooNewError struct {
	What      string
	GoVersion string
	Toolchain string // for callers if they want to use it, but not printed
}

A TooNewError explains that a module is too new for this version of Go.

func (*TooNewError) Error

func (e *TooNewError) Error() string

func (*TooNewError) Is

func (e *TooNewError) Is(err error) bool