gps

package
v0.5.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 13, 2019 License: BSD-3-Clause Imports: 44 Imported by: 0

Documentation

Overview

Package gps is a Go packaging solver library.

Index

Constants

This section is empty.

Variables

View Source 
var ErrSourceManagerIsReleased = fmt.Errorf("this SourceManager has been released, its methods can no longer be called")

ErrSourceManagerIsReleased is the error returned by any SourceManager method called after the SourceManager has been released, rendering its methods no longer safe to call.

Functions

func IsAny 

func IsAny(c Constraint) bool

IsAny indicates if the provided constraint is the wildcard "Any" constraint.

func PruneProject 

func PruneProject(baseDir string, lp LockedProject, options PruneOptions) error

PruneProject remove excess files according to the options passed, from the lp directory in baseDir.

func SortForDowngrade 

func SortForDowngrade(vl []Version)

SortForDowngrade sorts a slice of []Version in roughly ascending order, so that presumably older versions are visited first.

This is *not* the same as reversing SortForUpgrade (or you could simply sort.Reverse()). The type precedence is the same, including the semver vs. semver-with-prerelease relation. Lexicographical comparisons within non-semver tags, branches, and revisions remains the same as well; because we treat these domains as having no ordering relation, there can be no real concept of "upgrade" vs "downgrade", so there is no reason to reverse them.

Thus, the only binary relation that is reversed for downgrade is within-type comparisons for semver.

So, given a slice of the following versions:

  • Branch: master devel
  • Semver tags: v1.0.0, v1.1.0, v1.1.0-alpha1
  • Non-semver tags: footag
  • Revision: f6e74e8d

Sorting for downgrade will result in the following slice: 

[v1.0.0 v1.1.0 v1.1.0-alpha1 footag devel master f6e74e8d]

func SortForUpgrade 

func SortForUpgrade(vl []Version)

SortForUpgrade sorts a slice of []Version in roughly descending order, so that presumably newer versions are visited first. The rules are:

  • All semver versions come first, and sort mostly according to the semver 2.0 spec (as implemented by github.com/Masterminds/semver lib), with one exception:
  • Semver versions with a prerelease are after *all* non-prerelease semver. Within this subset they are sorted first by their numerical component, then lexicographically by their prerelease version.
  • The default branch(es) is next; the exact semantics of that are specific to the underlying source.
  • All other branches come next, sorted lexicographically.
  • All non-semver versions (tags) are next, sorted lexicographically.
  • Revisions, if any, are last, sorted lexicographically. Revisions do not typically appear in version lists, so the only invariant we maintain is determinism - deeper semantics, like chronology or topology, do not matter.

So, given a slice of the following versions:

  • Branch: master devel
  • Semver tags: v1.0.0, v1.1.0, v1.1.0-alpha1
  • Non-semver tags: footag
  • Revision: f6e74e8d

Sorting for upgrade will result in the following slice: 

[v1.1.0 v1.0.0 v1.1.0-alpha1 master devel footag f6e74e8d]

func SortPairedForDowngrade 

func SortPairedForDowngrade(vl []PairedVersion)

SortPairedForDowngrade has the same behavior as SortForDowngrade, but operates on []PairedVersion types.

func SortPairedForUpgrade 

func SortPairedForUpgrade(vl []PairedVersion)

SortPairedForUpgrade has the same behavior as SortForUpgrade, but operates on []PairedVersion types.

func ValidateParams 

func ValidateParams(params SolveParameters, sm SourceManager) error

ValidateParams validates the solver parameters to ensure solving can be completed.

func VersionComponentStrings 

func VersionComponentStrings(v Version) (revision string, branch string, version string)

VersionComponentStrings decomposes a Version into the underlying number, branch and revision.

func WriteDepTree 

func WriteDepTree(basedir string, l Lock, sm SourceManager, co CascadingPruneOptions, onWrite func(WriteProgress)) error

WriteDepTree takes a basedir, a Lock and a RootPruneOptions and exports all the projects listed in the lock to the appropriate target location within basedir.

If the goal is to populate a vendor directory, basedir should be the absolute path to that vendor directory, not its parent (a project root, typically).

It requires a SourceManager to do the work. Prune options are read from the passed manifest.

If onWrite is not nil, it will be called after each project write. Calls are ordered and atomic.

Types

type CascadingPruneOptions added in v0.4.1 

type CascadingPruneOptions struct {
	DefaultOptions    PruneOptions
	PerProjectOptions map[ProjectRoot]PruneOptionSet
}

CascadingPruneOptions is a set of rules for pruning a dependency tree.

The DefaultOptions are the global default pruning rules, expressed as a single PruneOptions bitfield. These global rules will cascade down to individual project rules, unless superseded.

func (CascadingPruneOptions) PruneOptionsFor added in v0.4.1 

func (o CascadingPruneOptions) PruneOptionsFor(pr ProjectRoot) PruneOptions

PruneOptionsFor returns the PruneOptions bits for the given project, indicating which pruning rules should be applied to the project's code.

It computes the cascade from default to project-specific options (if any) on the fly.

type Constraint 

type Constraint interface {
	fmt.Stringer

	// ImpliedCaretString converts the Constraint to a string in the same manner
	// as String(), but treats the empty operator as equivalent to ^, rather
	// than =.
	//
	// In the same way that String() is the inverse of NewConstraint(), this
	// method is the inverse of NewSemverConstraintIC().
	ImpliedCaretString() string

	// Matches indicates if the provided Version is allowed by the Constraint.
	Matches(Version) bool

	// MatchesAny indicates if the intersection of the Constraint with the
	// provided Constraint would yield a Constraint that could allow *any*
	// Version.
	MatchesAny(Constraint) bool

	// Intersect computes the intersection of the Constraint with the provided
	// Constraint.
	Intersect(Constraint) Constraint
	// contains filtered or unexported methods
}

A Constraint provides structured limitations on the versions that are admissible for a given project.

As with Version, it has a private method because the gps's internal implementation of the problem is complete, and the system relies on type magic to operate.

func Any 

func Any() Constraint

Any returns a constraint that will match anything.

func NewSemverConstraint 

func NewSemverConstraint(body string) (Constraint, error)

NewSemverConstraint attempts to construct a semver Constraint object from the input string.

If the input string cannot be made into a valid semver Constraint, an error is returned.

func NewSemverConstraintIC 

func NewSemverConstraintIC(body string) (Constraint, error)

NewSemverConstraintIC attempts to construct a semver Constraint object from the input string, defaulting to a caret, ^, when no operator is specified. Put differently, ^ is the default operator for NewSemverConstraintIC, while = is the default operator for NewSemverConstraint.

If the input string cannot be made into a valid semver Constraint, an error is returned.

type CouldNotCreateLockError 

type CouldNotCreateLockError struct {
	Path string
	Err  error
}

CouldNotCreateLockError describe failure modes in which creating a SourceMgr did not succeed because there was an error while attempting to create the on-disk lock file.

func (CouldNotCreateLockError) Error 

func (e CouldNotCreateLockError) Error() string

type DeductionErrs 

type DeductionErrs map[string]error

DeductionErrs maps package import path to errors occurring during deduction.

func (DeductionErrs) Error 

func (e DeductionErrs) Error() string

type Lock 

type Lock interface {
	// Projects returns the list of LockedProjects contained in the lock data.
	Projects() []LockedProject

	// The set of imports (and required statements) that were the inputs that
	// generated this Lock. It is acceptable to return a nil slice from this
	// method if the information cannot reasonably be made available.
	InputImports() []string
}

Lock represents data from a lock file (or however the implementing tool chooses to store it) at a particular version that is relevant to the satisfiability solving process.

In general, the information produced by gps on finding a successful solution is all that would be necessary to constitute a lock file, though tools can include whatever other information they want in their storage.

type LockedProject 

type LockedProject interface {
	Ident() ProjectIdentifier
	Version() Version
	Packages() []string
	Eq(LockedProject) bool
	String() string
}

LockedProject is a single project entry from a lock file. It expresses the project's name, one or both of version and underlying revision, the network URI for accessing it, the path at which it should be placed within a vendor directory, and the packages that are used in it.

func NewLockedProject 

func NewLockedProject(id ProjectIdentifier, v Version, pkgs []string) LockedProject

NewLockedProject creates a new LockedProject struct with a given ProjectIdentifier (name and optional upstream source URL), version. and list of packages required from the project.

Note that passing a nil version will cause a panic. This is a correctness measure to ensure that the solver is never exposed to a version-less lock entry. Such a case would be meaningless - the solver would have no choice but to simply dismiss that project. By creating a hard failure case via panic instead, we are trying to avoid inflicting the resulting pain on the user by instead forcing a decision on the Analyzer implementation.

type Manifest 

type Manifest interface {
	// Returns a list of project-level constraints.
	DependencyConstraints() ProjectConstraints
}

Manifest represents manifest-type data for a project at a particular version. The constraints expressed in a manifest determine the set of versions that are acceptable to try for a given project.

Expressing a constraint in a manifest does not guarantee that a particular dependency will be present. It only guarantees that if packages in the project specified by the dependency are discovered through static analysis of the (transitive) import graph, then they will conform to the constraint.

This does entail that manifests can express constraints on projects they do not themselves import. This is by design, but its implications are complex. See the gps docs for more information: https://github.com/sdboyer/gps/wiki

type PairedVersion 

type PairedVersion interface {
	Version

	// Revision returns the immutable Revision that identifies this Version.
	Revision() Revision

	// Unpair returns the surface-level UnpairedVersion that half of the pair.
	//
	// It does NOT modify the original PairedVersion.
	Unpair() UnpairedVersion
	// contains filtered or unexported methods
}

PairedVersion represents a normal Version, but paired with its corresponding, underlying Revision.

type ProjectAnalyzer 

type ProjectAnalyzer interface {
	// Perform analysis of the filesystem tree rooted at path, with the
	// root import path importRoot, to determine the project's constraints, as
	// indicated by a Manifest and Lock.
	//
	// Note that an error will typically cause the solver to treat the analyzed
	// version as unusable. As such, an error should generally only be returned
	// if the code tree is somehow malformed, but not if the implementor's
	// expected files containing Manifest and Lock data are merely absent.
	DeriveManifestAndLock(path string, importRoot ProjectRoot) (Manifest, Lock, error)

	// Info reports this project analyzer's info.
	Info() ProjectAnalyzerInfo
}

A ProjectAnalyzer is responsible for analyzing a given path for Manifest and Lock information. Tools relying on gps must implement one.

type ProjectAnalyzerInfo 

type ProjectAnalyzerInfo struct {
	Name    string
	Version int
}

ProjectAnalyzerInfo indicates a ProjectAnalyzer's name and version.

func (ProjectAnalyzerInfo) String 

func (p ProjectAnalyzerInfo) String() string

String returns a string like: "<name>.<decimal version>"

type ProjectConstraint 

type ProjectConstraint struct {