toolchain

Documentation

Overview

Package toolchain implements dynamic switching of Go toolchains.

Index

• Variables
• func Exec(gotoolchain string)
• func FilterEnv(env []string) []string
• func HasAuto() bool
• func HasPath() bool
• func NewerToolchain(ctx context.Context, version string) (string, error)
• func Select()
• func SwitchOrFatal(ctx context.Context, err error)
• type Switcher
  • func (s *Switcher) Error(err error)
  • func (s *Switcher) NeedSwitch() bool
  • func (s *Switcher) Switch(ctx context.Context)

Variables

var TestVersionSwitch string

TestVersionSwitch is set in the test go binary to the value in $TESTGO_VERSION_SWITCH. Valid settings are:

"switch" - simulate version switches by reinvoking the test go binary with a different TESTGO_VERSION.
"mismatch" - like "switch" but forget to set TESTGO_VERSION, so it looks like we invoked a mismatched toolchain
"loop" - like "mismatch" but forget the target check, causing a toolchain switching loop

Functions

func Exec

func Exec(gotoolchain string)

Exec invokes the specified Go toolchain or else prints an error and exits the process. If $GOTOOLCHAIN is set to path or min+path, Exec only considers the PATH as a source of Go toolchains. Otherwise Exec tries the PATH but then downloads a toolchain if necessary.

func FilterEnv

func FilterEnv(env []string) []string

FilterEnv returns a copy of env with internal GOTOOLCHAIN environment variables filtered out.

func HasAuto

func HasAuto() bool

HasAuto reports whether the GOTOOLCHAIN setting allows "auto" upgrades.

func HasPath

func HasPath() bool

HasPath reports whether the GOTOOLCHAIN setting allows "path" upgrades.

func NewerToolchain

func NewerToolchain(ctx context.Context, version string) (string, error)

NewerToolchain returns the name of the toolchain to use when we need to switch to a newer toolchain that must support at least the given Go version. See https://go.dev/doc/toolchain#switch.

If the latest major release is 1.N.0, we use the latest patch release of 1.(N-1) if that's >= version. Otherwise we use the latest 1.N if that's allowed. Otherwise we use the latest release.

func Select

func Select()

Select invokes a different Go toolchain if directed by the GOTOOLCHAIN environment variable or the user's configuration or go.mod file. It must be called early in startup. See https://go.dev/doc/toolchain#select.

func SwitchOrFatal

func SwitchOrFatal(ctx context.Context, err error)

SwitchOrFatal attempts a toolchain switch based on the information in err and otherwise falls back to base.Fatal(err).

Types

type Switcher

type Switcher struct {
	TooNew *gover.TooNewError // max go requirement observed
	Errors []error            // errors collected so far
}

A Switcher collects errors to be reported and then decides between reporting the errors or switching to a new toolchain to resolve them.

The client calls Switcher.Error repeatedly with errors encountered and then calls Switcher.Switch. If the errors included any *gover.TooNewErrors (potentially wrapped) and switching is permitted by GOTOOLCHAIN, Switch switches to a new toolchain. Otherwise Switch prints all the errors using base.Error.

See https://go.dev/doc/toolchain#switch.

func (*Switcher) Error

func (s *Switcher) Error(err error)

Error reports the error to the Switcher, which saves it for processing during Switch.

func (*Switcher) NeedSwitch

func (s *Switcher) NeedSwitch() bool

NeedSwitch reports whether Switch would attempt to switch toolchains.

func (*Switcher) Switch

func (s *Switcher) Switch(ctx context.Context)

Switch decides whether to switch to a newer toolchain to resolve any of the saved errors. It switches if toolchain switches are permitted and there is at least one TooNewError.

If Switch decides not to switch toolchains, it prints the errors using base.Error and returns.

If Switch decides to switch toolchains but cannot identify a toolchain to use. it prints the errors along with one more about not being able to find the toolchain and returns.

Otherwise, Switch prints an informational message giving a reason for the switch and the toolchain being invoked and then switches toolchains. This operation never returns.