gps

README

gps

gps is the Go Packaging Solver. It is an engine for tackling dependency management problems in Go. It is trivial - about 35 lines of code - to replicate the fetching bits of go get using gps.

gps is not Yet Another Go Package Management Tool. Rather, it's a library that package management (and adjacent) tools can use to solve the hard parts of the problem in a consistent, holistic way. It is a distillation of the ideas behind language package managers like bundler, npm, elm-package, cargo (and others) into a library, artisanally handcrafted with ❤️ for Go's specific requirements.

gps is on track to become the engine behind glide.

The wiki has a general introduction to the gps approach, as well as guides for folks implementing tools or looking to contribute.

gps is progressing rapidly, but still in beta, with a concomitantly liberal sprinkling of panics.

Wait...a package management library?!

Yup. See the rationale.

Features

A feature list for a package management library is a bit different than one for a package management tool. Instead of listing the things an end-user can do, we list the choices a tool can make and offer, in some form, to its users, as well as the non-choices/assumptions/constraints that gps imposes on a tool.

Non-Choices

We'd love for gps's non-choices to be noncontroversial. But that's not always the case.

Nevertheless, these non-choices remain because, taken as a whole, they make experiments and discussion around Go package management coherent and productive.

• Go >=1.6, or 1.5 with GO15VENDOREXPERIMENT = 1 set
• Everything under vendor/ is volatile and controlled solely by the tool
• A central cache of repositories is used (cannot be GOPATH)
• A project concept: a tree of packages, all covered by one vendor directory
• A manifest and lock approach to tracking version and constraint information
• Source repositories can be git, bzr, hg or svn (Most of the work here is through a separate lib)
• What the available versions are for a given project/repository (all branches, tags, or revs are eligible)
  • In general, semver tags are preferred to plain tags, are preferred to branches
• The actual packages required (determined through import graph static analysis)
  • How the import graph is statically analyzed (Similar to go/build, but with a combinatorial view of build tags)
• Package import cycles are not allowed (not yet implemented)

There are also some current non-choices that we would like to push into the realm of choice:

• Different versions of packages from the same repository cannot be used
• Importable projects that are not bound to the repository root

Choices

These choices represent many of the ways that gps-based tools could substantively differ from each other.

Some of these are choices designed to encompass all options for topics on which reasonable people have disagreed. Others are simply important controls that no general library could know a priori.

• How to store manifest and lock information (file(s)? a db?)
• Which of the other package managers to interoperate with
• Which types of version constraints to allow the user to specify (e.g., allowing semver ranges or not)
• Whether or not to strip nested vendor directories
• Which packages in the import graph to ignore
• What informational output to show the end user
• What dependency version constraints are declared by the root project
• What dependency version constraints are declared by all dependencies
• Given a previous solution, which versions to let change, and how
  • In the absence of a previous solution, whether or not to use preferred versions
• Allowing, or not, the user to swap in different network names for import paths (e.g. forks)
• Specifying additional input/source packages not reachable from the root import graph (not complete)

This list may not be exhaustive - see the implementor's guide for a proper treatment.

Contributing

Yay, contributing! Please see CONTRIBUTING.md. Note that gps also abides by a Code of Conduct, and is MIT-licensed.

Documentation

Index

• func CreateVendorTree(basedir string, l Lock, sm SourceManager, sv bool) error
• func IsAny(c Constraint) bool
• type Constraint
  • func Any() Constraint
  • func NewSemverConstraint(body string) (Constraint, error)
• type LocalImportsError
  • func (e *LocalImportsError) Error() string
• type Lock
• type LockedProject
  • func NewLockedProject(n ProjectRoot, v Version, url string, pkgs []string) LockedProject
  • func (lp LockedProject) Ident() ProjectIdentifier
  • func (lp LockedProject) Version() Version
• type Manifest
• type Package
• type PackageOrErr
• type PackageTree
  • func (t PackageTree) ExternalReach(main, tests bool, ignore map[string]bool) map[string][]string
  • func (t PackageTree) ListExternalImports(main, tests bool, ignore map[string]bool) []string
• type PairedVersion
• type ProjectAnalyzer
• type ProjectConstraint
• type ProjectConstraints
• type ProjectIdentifier
• type ProjectProperties
• type ProjectRoot
• type Revision
  • func (r Revision) Intersect(c Constraint) Constraint
  • func (r Revision) Matches(v Version) bool
  • func (r Revision) MatchesAny(c Constraint) bool
  • func (r Revision) String() string
  • func (r Revision) Type() string
• type RootManifest
• type SimpleLock
  • func (SimpleLock) InputHash() []byte
  • func (l SimpleLock) Projects() []LockedProject
• type SimpleManifest
  • func (m SimpleManifest) DependencyConstraints() []ProjectConstraint
  • func (m SimpleManifest) TestDependencyConstraints() []ProjectConstraint
• type Solution
• type SolveParameters
• type Solver
  • func Prepare(params SolveParameters, sm SourceManager) (Solver, error)
• type SourceManager
• type SourceMgr
  • func NewSourceManager(an ProjectAnalyzer, cachedir string, force bool) (*SourceMgr, error)
  • func (sm *SourceMgr) AnalyzerInfo() (name string, version *semver.Version)
  • func (sm *SourceMgr) ExportProject(n ProjectRoot, v Version, to string) error
  • func (sm *SourceMgr) GetManifestAndLock(n ProjectRoot, v Version) (Manifest, Lock, error)
  • func (sm *SourceMgr) ListPackages(n ProjectRoot, v Version) (PackageTree, error)
  • func (sm *SourceMgr) ListVersions(n ProjectRoot) ([]Version, error)
  • func (sm *SourceMgr) Release()
  • func (sm *SourceMgr) RepoExists(n ProjectRoot) (bool, error)
  • func (sm *SourceMgr) RevisionPresentIn(n ProjectRoot, r Revision) (bool, error)
• type UnpairedVersion
  • func NewBranch(body string) UnpairedVersion
  • func NewVersion(body string) UnpairedVersion
• type Version

Functions

func CreateVendorTree

func CreateVendorTree(basedir string, l Lock, sm SourceManager, sv bool) error

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

It requires a SourceManager to do the work, and takes a flag indicating whether or not to strip vendor directories contained in the exported dependencies.

func IsAny

func IsAny(c Constraint) bool

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

Types

type Constraint

type Constraint interface {
	fmt.Stringer
	// 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.

type LocalImportsError

type LocalImportsError struct {
	Dir          string
	LocalImports []string
}

LocalImportsError indicates that a package contains at least one relative import that will prevent it from compiling.

TODO(sdboyer) add a Files property once we're doing our own per-file parsing

func (*LocalImportsError) Error

func (e *LocalImportsError) Error() string

type Lock

type Lock interface {

	// The hash of inputs to gps that resulted in this lock data
	InputHash() []byte

	// Projects returns the list of LockedProjects contained in the lock data.
	Projects() []LockedProject
}

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 struct {
	// contains filtered or unexported fields
}

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(n ProjectRoot, v Version, url string, pkgs []string) LockedProject

NewLockedProject creates a new LockedProject struct with a given name, version, and upstream repository URL.

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.

func (LockedProject) Ident

func (lp LockedProject) Ident() ProjectIdentifier

Ident returns the identifier describing the project. This includes both the local name (the root name by which the project is referenced in import paths) and the network name, where the upstream source lives.

func (LockedProject) Version

func (lp LockedProject) Version() Version

Version assembles together whatever version and/or revision data is available into a single Version.

type Manifest

type Manifest interface {
	// Returns a list of project-level constraints.
	DependencyConstraints() []ProjectConstraint

	// Returns a list of constraints applicable to test imports.
	//
	// These are applied only when tests are incorporated. Typically, that
	// will only be for root manifests.
	TestDependencyConstraints() []ProjectConstraint
}

Manifest represents manifest-type data for a project at a particular version. That means dependency constraints, both for normal dependencies and for tests. 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 Package

type Package struct {
	ImportPath, CommentPath string
	Name                    string
	Imports                 []string
	TestImports             []string
}

Package represents a Go package. It contains a subset of the information go/build.Package does.

type PackageOrErr

type PackageOrErr struct {
	P   Package
	Err error
}

PackageOrErr stores the results of attempting to parse a single directory for Go source code.

type PackageTree

type PackageTree struct {
	ImportRoot string
	Packages   map[string]PackageOrErr
}

A PackageTree represents the results of recursively parsing a tree of packages, starting at the ImportRoot. The results of parsing the files in the directory identified by each import path - a Package or an error - are stored in the Packages map, keyed by that import path.

func (PackageTree) ExternalReach

func (t PackageTree) ExternalReach(main, tests bool, ignore map[string]bool) map[string][]string

ExternalReach looks through a PackageTree and computes the list of external packages (not logical children of PackageTree.ImportRoot) that are transitively imported by the internal packages in the tree.

main indicates whether (true) or not (false) to include main packages in the analysis. main packages are generally excluded when analyzing anything other than the root project, as they inherently can't be imported.

tests indicates whether (true) or not (false) to include imports from test files in packages when computing the reach map.

ignore is a map of import paths that, if encountered, should be excluded from analysis. This exclusion applies to both internal and external packages. If an external import path is ignored, it is simply omitted from the results.

If an internal path is ignored, then it is excluded from all transitive dependency chains and does not appear as a key in the final map. That is, if you ignore A/foo, then the external package list for all internal packages that import A/foo will not include external packages that are only reachable through A/foo.

Visually, this means that, given a PackageTree with root A and packages at A, A/foo, and A/bar, and the following import chain:

A -> A/foo -> A/bar -> B/baz

If you ignore A/foo, then the returned map would be:

 map[string][]string{
	"A": []string{},
	"A/bar": []string{"B/baz"},
 }

It is safe to pass a nil map if there are no packages to ignore.

func (PackageTree) ListExternalImports

func (t PackageTree) ListExternalImports(main, tests bool, ignore map[string]bool) []string

ListExternalImports computes a sorted, deduplicated list of all the external packages that are reachable through imports from all valid packages in the PackageTree.

main and tests determine whether main packages and test imports should be included in the calculation. "External" is defined as anything not prefixed, after path cleaning, by the PackageTree.ImportRoot. This includes stdlib.

If an internal path is ignored, all of the external packages that it uniquely imports are omitted. Note, however, that no internal transitivity checks are made here - every non-ignored package in the tree is considered independently (with one set of exceptions, noted below). That means, given a PackageTree with root A and packages at A, A/foo, and A/bar, and the following import chain:

A -> A/foo -> A/bar -> B/baz

If you ignore A or A/foo, A/bar will still be visited, and B/baz will be returned, because this method visits ALL packages in the tree, not only those reachable from the root (or any other) packages. If your use case requires interrogating external imports with respect to only specific package entry points, you need ExternalReach() instead.

It is safe to pass a nil map if there are no packages to ignore.

If an internal package has an error (that is, PackageOrErr is Err), it is excluded from consideration. Internal packages that transitively import the error package are also excluded. So, if:

  -> B/foo
 /
A
 \
  -> A/bar -> B/baz

And A/bar has some error in it, then both A and A/bar will be eliminated from consideration; neither B/foo nor B/baz will be in the results. If A/bar, with its errors, is ignored, however, then A will remain, and B/foo will be in the results.

Finally, note that if a directory is named "testdata", or has a leading dot or underscore, it will not be directly analyzed as a source. This is in keeping with Go tooling conventions that such directories should be ignored. So, if:

A -> B/foo
A/.bar -> B/baz
A/_qux -> B/baz
A/testdata -> B/baz

Then B/foo will be returned, but B/baz will not, because all three of the packages that import it are in directories with disallowed names.

HOWEVER, in keeping with the Go compiler, if one of those packages in a disallowed directory is imported by a package in an allowed directory, then it *will* be used. That is, while tools like go list will ignore a directory named .foo, you can still import from .foo. Thus, it must be included. So, if:

  -> B/foo
 /
A
 \
  -> A/.bar -> B/baz

A is legal, and it imports A/.bar, so the results will include B/baz.

type PairedVersion

type PairedVersion interface {
	Version
	// Underlying returns the immutable Revision that identifies this Version.
	Underlying() Revision
	// 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.
	DeriveManifestAndLock(path string, importRoot ProjectRoot) (Manifest, Lock, error)
	// Report the name and version of this ProjectAnalyzer.
	Info() (name string, version *semver.Version)
}

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

type ProjectConstraint

type ProjectConstraint struct {
	Ident      ProjectIdentifier
	Constraint Constraint
}

A ProjectConstraint combines a ProjectIdentifier with a Constraint. It indicates that, if packages contained in the ProjectIdentifier enter the depgraph, they must do so at a version that is allowed by the Constraint.

type ProjectConstraints

type ProjectConstraints map[ProjectRoot]ProjectProperties

type ProjectIdentifier

type ProjectIdentifier struct {
	ProjectRoot ProjectRoot
	NetworkName string
}

A ProjectIdentifier is, more or less, the name of a dependency. It is related to, but differs in two keys ways from, an import path.

First, ProjectIdentifiers do not identify a single package. Rather, they encompasses the whole tree of packages that exist at or below their ProjectRoot. In gps' current design, this ProjectRoot must correspond to the root of a repository, though this may not always be the case.

Second, ProjectIdentifiers can optionally carry a NetworkName, which identifies where the underlying source code can be located on the network. These can be either a full URL, including protocol, or plain import paths. So, these are all valid data for NetworkName:

github.com/sdboyer/gps
github.com/fork/gps
git@github.com:sdboyer/gps
https://github.com/sdboyer/gps

With plain import paths, network addresses are derived purely through an algorithm. By having an explicit network name, it becomes possible to, for example, transparently substitute a fork for an original upstream repository.

Note that gps makes no guarantees about the actual import paths contained in a repository aligning with ImportRoot. If tools, or their users, specify an alternate NetworkName that contains a repository with incompatible internal import paths, gps will fail. (gps does no import rewriting.)

Also note that if different projects' manifests report a different NetworkName for a given ImportRoot, it is a solve failure. Everyone has to agree on where a given import path should be sourced from.

If NetworkName is not explicitly set, gps will derive the network address from the ImportRoot using a similar algorithm to that of the official go tooling.

type ProjectProperties

type ProjectProperties struct {
	NetworkName string
	Constraint  Constraint
}

ProjectProperties comprise the properties that can attached to a ProjectRoot.

In general, these are declared in the context of a map of ProjectRoot to its ProjectProperties; they make little sense without their corresponding ProjectRoot.

type ProjectRoot

type ProjectRoot string

ProjectRoot is the topmost import path in a tree of other import paths - the root of the tree. In gps' current design, ProjectRoots have to correspond to a repository root (mostly), but their real purpose is to identify the root import path of a "project", logically encompassing all child packages.

Projects are a crucial unit of operation in gps. Constraints are declared by a project's manifest, and apply to all packages in a ProjectRoot's tree. Solving itself mostly proceeds on a project-by-project basis.

Aliasing string types is usually a bit of an anti-pattern. We do it here as a means of clarifying API intent. This is important because Go's package management domain has lots of different path-ish strings floating around:

 actual directories:
	/home/sdboyer/go/src/github.com/sdboyer/gps/example
 URLs:
	https://github.com/sdboyer/gps
 import paths:
	github.com/sdboyer/gps/example
 portions of import paths that refer to a package:
	example
 portions that could not possibly refer to anything sane:
	github.com/sdboyer
 portions that correspond to a repository root:
	github.com/sdboyer/gps

While not a panacea, defining ProjectRoot at least allows us to clearly identify when one of these path-ish strings is *supposed* to have certain semantics.

type Revision

type Revision string

A Revision represents an immutable versioning identifier.

func (Revision) Intersect

func (r Revision) Intersect(c Constraint) Constraint

func (Revision) Matches

func (r Revision) Matches(v Version) bool

Matches is the Revision acting as a constraint; it checks to see if the provided version is the same Revision as itself.

func (Revision) MatchesAny

func (r Revision) MatchesAny(c Constraint) bool

MatchesAny is the Revision acting as a constraint; it checks to see if the provided version is the same Revision as itself.

func (Revision) String

func (r Revision) String() string

String converts the Revision back into a string.

func (Revision) Type

func (r Revision) Type() string

type RootManifest

type RootManifest interface {
	Manifest

	// Overrides returns a list of ProjectConstraints that will unconditionally
	// supercede any ProjectConstraint declarations made in either the root
	// manifest, or in any dependency's manifest.
	//
	// Overrides are a special control afforded only to root manifests. Tool
	// users should be encouraged to use them only as a last resort; they do not
	// "play well with others" (that is their express goal), and overreliance on
	// them can harm the ecosystem as a whole.
	Overrides() ProjectConstraints

	// IngorePackages returns a set of import paths to ignore. These import
	// paths can be within the root project, or part of other projects. Ignoring
	// a package means that both it and its (unique) imports will be disregarded
	// by all relevant solver operations.
	IgnorePackages() map[string]bool
}

RootManifest extends Manifest to add special controls over solving that are only afforded to the root project.

type SimpleLock

type SimpleLock []LockedProject

SimpleLock is a helper for tools to easily describe lock data when they know that no hash, or other complex information, is available.

func (SimpleLock) InputHash

func (SimpleLock) InputHash() []byte

InputHash always returns an empty string for SimpleLock. This makes it useless as a stable lock to be written to disk, but still useful for some ephemeral purposes.

func (SimpleLock) Projects

func (l SimpleLock) Projects() []LockedProject

Projects returns the entire contents of the SimpleLock.

type SimpleManifest

type SimpleManifest struct {
	Deps     []ProjectConstraint
	TestDeps []ProjectConstraint
}

SimpleManifest is a helper for tools to enumerate manifest data. It's generally intended for ephemeral manifests, such as those Analyzers create on the fly for projects with no manifest metadata, or metadata through a foreign tool's idioms.

func (SimpleManifest) DependencyConstraints

func (m SimpleManifest) DependencyConstraints() []ProjectConstraint

DependencyConstraints returns the project's dependencies.

func (SimpleManifest) TestDependencyConstraints

func (m SimpleManifest) TestDependencyConstraints() []ProjectConstraint

TestDependencyConstraints returns the project's test dependencies.

type Solution

type Solution interface {
	Lock
	Attempts() int
}

A Solution is returned by a solver run. It is mostly just a Lock, with some additional methods that report information about the solve run.

type SolveParameters

type SolveParameters struct {
	// The path to the root of the project on which the solver should operate.
	// This should point to the directory that should contain the vendor/
	// directory.
	//
	// In general, it is wise for this to be under an active GOPATH, though it
	// is not (currently) required.
	//
	// A real path to a readable directory is required.
	RootDir string

	// The import path at the base of all import paths covered by the project.
	// For example, the appropriate value for gps itself here is:
	//
	//  github.com/sdboyer/gps
	//
	// In most cases, this should match the latter portion of RootDir. However,
	// that is not (currently) required.
	//
	// A non-empty string is required.
	ImportRoot ProjectRoot

	// The root manifest. This contains all the dependency constraints
	// associated with normal Manifests, as well as the particular controls
	// afforded only to the root project.
	//
	// May be nil, but for most cases, that would be unwise.
	Manifest RootManifest

	// The root lock. Optional. Generally, this lock is the output of a previous
	// solve run.
	//
	// If provided, the solver will attempt to preserve the versions specified
	// in the lock, unless ToChange or ChangeAll settings indicate otherwise.
	Lock Lock

	// ToChange is a list of project names that should be changed - that is, any
	// versions specified for those projects in the root lock file should be
	// ignored.
	//
	// Passing ChangeAll has subtly different behavior from enumerating all
	// projects into ToChange. In general, ToChange should *only* be used if the
	// user expressly requested an upgrade for a specific project.
	ToChange []ProjectRoot

	// ChangeAll indicates that all projects should be changed - that is, any
	// versions specified in the root lock file should be ignored.
	ChangeAll bool

	// Downgrade indicates whether the solver will attempt to upgrade (false) or
	// downgrade (true) projects that are not locked, or are marked for change.
	//
	// Upgrading is, by far, the most typical case. The field is named
	// 'Downgrade' so that the bool's zero value corresponds to that most
	// typical case.
	Downgrade bool

	// Trace controls whether the solver will generate informative trace output
	// as it moves through the solving process.
	Trace bool

	// TraceLogger is the logger to use for generating trace output. If Trace is
	// true but no logger is provided, solving will result in an error.
	TraceLogger *log.Logger
}

SolveParameters hold all arguments to a solver run.

Only RootDir and ImportRoot are absolutely required. A nil Manifest is allowed, though it usually makes little sense.

Of these properties, only Manifest and Ignore are (directly) incorporated in memoization hashing.

type Solver

type Solver interface {
	// HashInputs produces a hash digest representing the unique inputs to this
	// solver. It is guaranteed that, if the hash digest is equal to the digest
	// from a previous Solution.InputHash(), that that Solution is valid for
	// this Solver's inputs.
	//
	// In such a case, it may not be necessary to run Solve() at all.
	HashInputs() ([]byte, error)
	Solve() (Solution, error)
}

A Solver is the main workhorse of gps: given a set of project inputs, it performs a constraint solving analysis to develop a complete Solution, or else fail with an informative error.

If a Solution is found, an implementing tool may persist it - typically into what a "lock file" - and/or use it to write out a directory tree of dependencies, suitable to be a vendor directory, via CreateVendorTree.

func Prepare

func Prepare(params SolveParameters, sm SourceManager) (Solver, error)

Prepare readies a Solver for use.

This function reads and validates the provided SolveParameters. If a problem with the inputs is detected, an error is returned. Otherwise, a Solver is returned, ready to hash and check inputs or perform a solving run.

type SourceManager

type SourceManager interface {
	// RepoExists checks if a repository exists, either upstream or in the
	// SourceManager's central repository cache.
	RepoExists(ProjectRoot) (bool, error)

	// ListVersions retrieves a list of the available versions for a given
	// repository name.
	ListVersions(ProjectRoot) ([]Version, error)

	// RevisionPresentIn indicates whether the provided Version is present in
	// the given repository.
	RevisionPresentIn(ProjectRoot, Revision) (bool, error)

	// ListPackages retrieves a tree of the Go packages at or below the provided
	// import path, at the provided version.
	ListPackages(ProjectRoot, Version) (PackageTree, error)

	// GetManifestAndLock returns manifest and lock information for the provided
	// root import path.
	//
	// gps currently requires that projects be rooted at their
	// repository root, necessitating that this ProjectRoot must also be a
	// repository root.
	GetManifestAndLock(ProjectRoot, Version) (Manifest, Lock, error)

	// AnalyzerInfo reports the name and version of the logic used to service
	// GetManifestAndLock().
	AnalyzerInfo() (name string, version *semver.Version)

	// ExportProject writes out the tree of the provided import path, at the
	// provided version, to the provided directory.
	ExportProject(ProjectRoot, Version, string) error

	// Release lets go of any locks held by the SourceManager.
	Release()
}

A SourceManager is responsible for retrieving, managing, and interrogating source repositories. Its primary purpose is to serve the needs of a Solver, but it is handy for other purposes, as well.

gps's built-in SourceManager, accessible via NewSourceManager(), is intended to be generic and sufficient for any purpose. It provides some additional semantics around the methods defined here.

type SourceMgr

type SourceMgr struct {
	// contains filtered or unexported fields
}

SourceMgr is the default SourceManager for gps.

There's no (planned) reason why it would need to be reimplemented by other tools; control via dependency injection is intended to be sufficient.

func NewSourceManager

func NewSourceManager(an ProjectAnalyzer, cachedir string, force bool) (*SourceMgr, error)

NewSourceManager produces an instance of gps's built-in SourceManager. It takes a cache directory (where local instances of upstream repositories are stored), a vendor directory for the project currently being worked on, and a force flag indicating whether to overwrite the global cache lock file (if present).

The returned SourceManager aggressively caches information wherever possible. It is recommended that, if tools need to do preliminary, work involving upstream repository analysis prior to invoking a solve run, that they create this SourceManager as early as possible and use it to their ends. That way, the solver can benefit from any caches that may have already been warmed.

gps's SourceManager is intended to be threadsafe (if it's not, please file a bug!). It should certainly be safe to reuse from one solving run to the next; however, the fact that it takes a basedir as an argument makes it much less useful for simultaneous use by separate solvers operating on different root projects. This architecture may change in the future.

func (*SourceMgr) AnalyzerInfo

func (sm *SourceMgr) AnalyzerInfo() (name string, version *semver.Version)

AnalyzerInfo reports the name and version of the injected ProjectAnalyzer.

func (*SourceMgr) ExportProject

func (sm *SourceMgr) ExportProject(n ProjectRoot, v Version, to string) error

ExportProject writes out the tree of the provided import path, at the provided version, to the provided directory.

func (*SourceMgr) GetManifestAndLock

func (sm *SourceMgr) GetManifestAndLock(n ProjectRoot, v Version) (Manifest, Lock, error)

GetManifestAndLock returns manifest and lock information for the provided import path. gps currently requires that projects be rooted at their repository root, which means that this ProjectRoot must also be a repository root.

The work of producing the manifest and lock is delegated to the injected ProjectAnalyzer's DeriveManifestAndLock() method.

func (*SourceMgr) ListPackages

func (sm *SourceMgr) ListPackages(n ProjectRoot, v Version) (PackageTree, error)

ListPackages retrieves a tree of the Go packages at or below the provided import path, at the provided version.

func (*SourceMgr) ListVersions

func (sm *SourceMgr) ListVersions(n ProjectRoot) ([]Version, error)

ListVersions retrieves a list of the available versions for a given repository name.

The list is not sorted; while it may be returned in the order that the underlying VCS reports version information, no guarantee is made. It is expected that the caller either not care about order, or sort the result themselves.

This list is always retrieved from upstream; if upstream is not accessible (network outage, access issues, or the resource actually went away), an error will be returned.

func (*SourceMgr) Release

func (sm *SourceMgr) Release()

Release lets go of any locks held by the SourceManager.

func (*SourceMgr) RepoExists

func (sm *SourceMgr) RepoExists(n ProjectRoot) (bool, error)

RepoExists checks if a repository exists, either upstream or in the cache, for the provided ProjectRoot.

func (*SourceMgr) RevisionPresentIn

func (sm *SourceMgr) RevisionPresentIn(n ProjectRoot, r Revision) (bool, error)

RevisionPresentIn indicates whether the provided Revision is present in the given repository.

type UnpairedVersion

type UnpairedVersion interface {
	Version
	// Is takes the underlying Revision that this UnpairedVersion corresponds
	// to and unites them into a PairedVersion.
	Is(Revision) PairedVersion
	// contains filtered or unexported methods
}

UnpairedVersion represents a normal Version, with a method for creating a VersionPair by indicating the version's corresponding, underlying Revision.

func NewBranch

func NewBranch(body string) UnpairedVersion

NewBranch creates a new Version to represent a floating version (in general, a branch).

func NewVersion

func NewVersion(body string) UnpairedVersion

NewVersion creates a Semver-typed Version if the provided version string is valid semver, and a plain/non-semver version if not.

type Version

type Version interface {
	Constraint
	// Indicates the type of version - Revision, Branch, Version, or Semver
	Type() string
}

Version represents one of the different types of versions used by gps.

Version composes Constraint, because all versions can be used as a constraint (where they allow one, and only one, version - themselves), but constraints are not necessarily discrete versions.

Version is an interface, but it contains private methods, which restricts it to gps's own internal implementations. We do this for the confluence of two reasons: the implementation of Versions is complete (there is no case in which we'd need other types), and the implementation relies on type magic under the hood, which would be unsafe to do if other dynamic types could be hiding behind the interface.