mvs

Documentation

Overview

Package mvs implements Minimal Version Selection. See https://research.swtch.com/vgo-mvs.

Index

• func BuildList(target module.Version, reqs Reqs) ([]module.Version, error)
• func Downgrade(target module.Version, reqs Reqs, downgrade ...module.Version) ([]module.Version, error)
• func Req(target module.Version, base []string, reqs Reqs) ([]module.Version, error)
• func Upgrade(target module.Version, reqs Reqs, upgrade ...module.Version) ([]module.Version, error)
• func UpgradeAll(target module.Version, reqs Reqs) ([]module.Version, error)
• type BuildListError
  • func (e *BuildListError) Error() string
  • func (e *BuildListError) Module() module.Version
• type Reqs

Functions

func BuildList

func BuildList(target module.Version, reqs Reqs) ([]module.Version, error)

BuildList returns the build list for the target module. The first element is the target itself, with the remainder of the list sorted by path.

func Downgrade

func Downgrade(target module.Version, reqs Reqs, downgrade ...module.Version) ([]module.Version, error)

Downgrade returns a build list for the target module in which the given additional modules are downgraded.

The versions to be downgraded may be unreachable from reqs.Latest and reqs.Previous, but the methods of reqs must otherwise handle such versions correctly.

func Req

func Req(target module.Version, base []string, reqs Reqs) ([]module.Version, error)

Req returns the minimal requirement list for the target module, with the constraint that all module paths listed in base must appear in the returned list.

func Upgrade

func Upgrade(target module.Version, reqs Reqs, upgrade ...module.Version) ([]module.Version, error)

Upgrade returns a build list for the target module in which the given additional modules are upgraded.

func UpgradeAll

func UpgradeAll(target module.Version, reqs Reqs) ([]module.Version, error)

UpgradeAll returns a build list for the target module in which every module is upgraded to its latest version.

Types

type BuildListError

type BuildListError struct {
	Err error
	// contains filtered or unexported fields
}

BuildListError decorates an error that occurred gathering requirements while constructing a build list. BuildListError prints the chain of requirements to the module where the error occurred.

func (*BuildListError) Error

func (e *BuildListError) Error() string

func (*BuildListError) Module

func (e *BuildListError) Module() module.Version

Module returns the module where the error occurred. If the module stack is empty, this returns a zero value.

type Reqs

type Reqs interface {
	// Required returns the module versions explicitly required by m itself.
	// The caller must not modify the returned list.
	Required(m module.Version) ([]module.Version, error)

	// Max returns the maximum of v1 and v2 (it returns either v1 or v2).
	//
	// For all versions v, Max(v, "none") must be v,
	// and for the target passed as the first argument to MVS functions,
	// Max(target, v) must be target.
	//
	// Note that v1 < v2 can be written Max(v1, v2) != v1
	// and similarly v1 <= v2 can be written Max(v1, v2) == v2.
	Max(v1, v2 string) string

	// Upgrade returns the upgraded version of m,
	// for use during an UpgradeAll operation.
	// If m should be kept as is, Upgrade returns m.
	// If m is not yet used in the build, then m.Version will be "none".
	// More typically, m.Version will be the version required
	// by some other module in the build.
	//
	// If no module version is available for the given path,
	// Upgrade returns a non-nil error.
	// TODO(rsc): Upgrade must be able to return errors,
	// but should "no latest version" just return m instead?
	Upgrade(m module.Version) (module.Version, error)

	// Previous returns the version of m.Path immediately prior to m.Version,
	// or "none" if no such version is known.
	Previous(m module.Version) (module.Version, error)
}

A Reqs is the requirement graph on which Minimal Version Selection (MVS) operates.

The version strings are opaque except for the special version "none" (see the documentation for module.Version). In particular, MVS does not assume that the version strings are semantic versions; instead, the Max method gives access to the comparison operation.

It must be safe to call methods on a Reqs from multiple goroutines simultaneously. Because a Reqs may read the underlying graph from the network on demand, the MVS algorithms parallelize the traversal to overlap network delays.