dep: Index | Files | Directories

package dep

import ""

Package dep is a prototype dependency management library.


Package Files

analyzer.go context.go doc.go lock.go manifest.go project.go txn_writer.go


const LockName = "Gopkg.lock"

LockName is the lock file name used by dep.

const ManifestName = "Gopkg.toml"

ManifestName is the manifest file name used by dep.

func BackupVendor Uses

func BackupVendor(vpath, suffix string) (string, error)

BackupVendor looks for existing vendor directory and if it's not empty, creates a backup of it to a new directory with the provided suffix.

func ValidateProjectRoots Uses

func ValidateProjectRoots(c *Ctx, m *Manifest, sm gps.SourceManager) error

ValidateProjectRoots validates the project roots present in manifest.

type Analyzer Uses

type Analyzer struct{}

Analyzer implements gps.ProjectAnalyzer.

func (Analyzer) DeriveManifestAndLock Uses

func (a Analyzer) DeriveManifestAndLock(path string, n gps.ProjectRoot) (gps.Manifest, gps.Lock, error)

DeriveManifestAndLock reads and returns the manifest at path/ManifestName or nil if one is not found. The Lock is always nil for now.

func (Analyzer) HasDepMetadata Uses

func (a Analyzer) HasDepMetadata(path string) bool

HasDepMetadata determines if a dep manifest exists at the specified path.

func (Analyzer) Info Uses

func (a Analyzer) Info() gps.ProjectAnalyzerInfo

Info returns Analyzer's name and version info.

type Ctx Uses

type Ctx struct {
    WorkingDir     string        // Where to execute.
    GOPATH         string        // Selected Go path, containing WorkingDir.
    GOPATHs        []string      // Other Go paths.
    ExplicitRoot   string        // An explicitly-set path to use as the project root.
    Out, Err       *log.Logger   // Required loggers.
    Verbose        bool          // Enables more verbose logging.
    DisableLocking bool          // When set, no lock file will be created to protect against simultaneous dep processes.
    Cachedir       string        // Cache directory loaded from environment.
    CacheAge       time.Duration // Maximum valid age of cached source data. <=0: Don't cache.

Ctx defines the supporting context of dep.

A properly initialized Ctx has a GOPATH containing the project root and non-nil Loggers.

ctx := &dep.Ctx{
	WorkingDir: GOPATH + "/src/project/root",
	Out: log.New(os.Stdout, "", 0),
	Err: log.New(os.Stderr, "", 0),

Ctx.DetectProjectGOPATH() helps with setting the containing GOPATH.

ctx.GOPATH, err := Ctx.DetectProjectGOPATH(project)
if err != nil {
	// Could not determine which GOPATH to use for the project.

func (*Ctx) AbsForImport Uses

func (c *Ctx) AbsForImport(path string) (string, error)

AbsForImport returns the absolute path for the project root including the $GOPATH. This will not work with stdlib packages and the package directory needs to exist.

func (*Ctx) DetectProjectGOPATH Uses

func (c *Ctx) DetectProjectGOPATH(p *Project) (string, error)

DetectProjectGOPATH attempt to find the GOPATH containing the project.

If p.AbsRoot is not a symlink and is within a GOPATH, the GOPATH containing p.AbsRoot is returned.
If p.AbsRoot is a symlink and is not within any known GOPATH, the GOPATH containing p.ResolvedAbsRoot is returned.

p.AbsRoot is assumed to be a symlink if it is not the same as p.ResolvedAbsRoot.

DetectProjectGOPATH will return an error in the following cases:

If p.AbsRoot is not a symlink and is not within any known GOPATH.
If neither p.AbsRoot nor p.ResolvedAbsRoot are within a known GOPATH.
If both p.AbsRoot and p.ResolvedAbsRoot are within the same GOPATH.
If p.AbsRoot and p.ResolvedAbsRoot are each within a different GOPATH.

func (*Ctx) ImportForAbs Uses

func (c *Ctx) ImportForAbs(path string) (string, error)

ImportForAbs returns the import path for an absolute project path by trimming the `$GOPATH/src/` prefix. Returns an error for paths equal to, or without this prefix.

func (*Ctx) LoadProject Uses

func (c *Ctx) LoadProject() (*Project, error)

LoadProject starts from the current working directory and searches up the directory tree for a project root. The search stops when a file with the name ManifestName (Gopkg.toml, by default) is located.

The Project contains the parsed manifest as well as a parsed lock file, if present. The import path is calculated as the remaining path segment below Ctx.GOPATH/src.

func (*Ctx) SetPaths Uses

func (c *Ctx) SetPaths(wd string, GOPATHs ...string) error

SetPaths sets the WorkingDir and GOPATHs fields. If GOPATHs is empty, then the GOPATH environment variable (or the default GOPATH) is used instead.

func (*Ctx) SourceManager Uses

func (c *Ctx) SourceManager() (*gps.SourceMgr, error)

SourceManager produces an instance of gps's built-in SourceManager initialized to log to the receiver's logger.

func (*Ctx) ValidateParams Uses

func (c *Ctx) ValidateParams(sm gps.SourceManager, params gps.SolveParameters) error

ValidateParams ensure that solving can be completed with the specified params.

type DeltaWriter Uses

type DeltaWriter struct {
    // contains filtered or unexported fields

DeltaWriter manages batched writes to populate vendor/ and update Gopkg.lock. Its primary design goal is to minimize writes by only writing things that have changed.

func (*DeltaWriter) PrintPreparedActions Uses

func (dw *DeltaWriter) PrintPreparedActions(output *log.Logger, verbose bool) error

PrintPreparedActions indicates what changes the DeltaWriter plans to make.

func (*DeltaWriter) Write Uses

func (dw *DeltaWriter) Write(path string, sm gps.SourceManager, examples bool, logger *log.Logger) error

Write executes the planned changes.

This writes recreated projects to a new directory, then moves in existing, unchanged projects from the original vendor directory. If any failures occur, reasonable attempts are made to roll back the changes.

type Lock Uses

type Lock struct {
    SolveMeta SolveMeta
    P         []gps.LockedProject

Lock holds lock file data and implements gps.Lock.

func LockFromSolution Uses

func LockFromSolution(in gps.Solution, prune gps.CascadingPruneOptions) *Lock

LockFromSolution converts a gps.Solution to dep's representation of a lock. It makes sure that that the provided prune options are set correctly, as the solver does not use VerifiableProjects for new selections it makes.

Data is defensively copied wherever necessary to ensure the resulting *Lock shares no memory with the input solution.

func (*Lock) HasProjectWithRoot Uses

func (l *Lock) HasProjectWithRoot(root gps.ProjectRoot) bool

HasProjectWithRoot checks if the lock contains a project with the provided ProjectRoot.

This check is O(n) in the number of projects.

func (*Lock) InputImports Uses

func (l *Lock) InputImports() []string

InputImports reports the list of input imports that were used in generating this Lock.

func (*Lock) MarshalTOML Uses

func (l *Lock) MarshalTOML() ([]byte, error)

MarshalTOML serializes this lock into TOML via an intermediate raw form.

func (*Lock) Projects Uses

func (l *Lock) Projects() []gps.LockedProject

Projects returns the list of LockedProjects contained in the lock data.

type Manifest Uses

type Manifest struct {
    Constraints gps.ProjectConstraints
    Ovr         gps.ProjectConstraints

    Ignored  []string
    Required []string

    NoVerify []string

    PruneOptions gps.CascadingPruneOptions

Manifest holds manifest file data and implements gps.RootManifest.

func NewManifest Uses

func NewManifest() *Manifest

NewManifest instantites a new manifest.

func (*Manifest) DependencyConstraints Uses

func (m *Manifest) DependencyConstraints() gps.ProjectConstraints

DependencyConstraints returns a list of project-level constraints.

func (*Manifest) HasConstraintsOn Uses

func (m *Manifest) HasConstraintsOn(root gps.ProjectRoot) bool

HasConstraintsOn checks if the manifest contains either constraints or overrides on the provided ProjectRoot.

func (*Manifest) IgnoredPackages Uses

func (m *Manifest) IgnoredPackages() *pkgtree.IgnoredRuleset

IgnoredPackages returns a set of import paths to ignore.

func (*Manifest) MarshalTOML Uses

func (m *Manifest) MarshalTOML() ([]byte, error)

MarshalTOML serializes this manifest into TOML via an intermediate raw form.

func (*Manifest) Overrides Uses

func (m *Manifest) Overrides() gps.ProjectConstraints

Overrides returns a list of project-level override constraints.

func (*Manifest) RequiredPackages Uses

func (m *Manifest) RequiredPackages() map[string]bool

RequiredPackages returns a set of import paths to require.

type Project Uses

type Project struct {
    // AbsRoot is the absolute path to the root directory of the project.
    AbsRoot string
    // ResolvedAbsRoot is the resolved absolute path to the root directory of the project.
    // If AbsRoot is not a symlink, then ResolvedAbsRoot should equal AbsRoot.
    ResolvedAbsRoot string
    // ImportRoot is the import path of the project's root directory.
    ImportRoot gps.ProjectRoot
    // The Manifest, as read from Gopkg.toml on disk.
    Manifest *Manifest
    // The Lock, as read from Gopkg.lock on disk.
    Lock *Lock // Optional
    // The above Lock, with changes applied to it. There are two possible classes of
    // changes:
    //  1. Changes to InputImports
    //  2. Changes to per-project prune options
    ChangedLock *Lock
    // The PackageTree representing the project, with hidden and ignored
    // packages already trimmed.
    RootPackageTree pkgtree.PackageTree
    // Oncer to manage access to initial check of vendor.
    CheckVendor sync.Once
    // The result of calling verify.CheckDepTree against the current lock and
    // vendor dir.
    VendorStatus map[string]verify.VendorStatus
    // The error, if any, from checking vendor.
    CheckVendorErr error

A Project holds a Manifest and optional Lock for a project.

func (*Project) FindIneffectualConstraints Uses

func (p *Project) FindIneffectualConstraints(sm gps.SourceManager) []gps.ProjectRoot

FindIneffectualConstraints looks for constraint rules expressed in the manifest that will have no effect during solving, as they are specified for projects that are not direct dependencies of the Project.

"Direct dependency" here is as implemented by GetDirectDependencyNames(); it correctly incorporates all "ignored" and "required" rules.

func (*Project) GetDirectDependencyNames Uses

func (p *Project) GetDirectDependencyNames(sm gps.SourceManager) (map[gps.ProjectRoot]bool, error)

GetDirectDependencyNames returns the set of unique Project Roots that are the direct dependencies of this Project.

A project is considered a direct dependency if at least one of its packages is named in either this Project's required list, or if there is at least one non-ignored import statement from a non-ignored package in the current project's package tree.

The returned map of Project Roots contains only boolean true values; this makes a "false" value always indicate an absent key, which makes conditional checks against the map more ergonomic.

This function will correctly utilize ignores and requireds from an existing manifest, if one is present, but will also do the right thing without a manifest.

func (*Project) MakeParams Uses

func (p *Project) MakeParams() gps.SolveParameters

MakeParams is a simple helper to create a gps.SolveParameters without setting any nils incorrectly.

func (*Project) SetRoot Uses

func (p *Project) SetRoot(root string) error

SetRoot sets the project AbsRoot and ResolvedAbsRoot. If root is not a symlink, ResolvedAbsRoot will be set to root.

func (*Project) VerifyVendor Uses

func (p *Project) VerifyVendor() (map[string]verify.VendorStatus, error)

VerifyVendor checks the vendor directory against the hash digests in Gopkg.lock.

This operation is overseen by the sync.Once in CheckVendor. This is intended to facilitate running verification in the background while solving, then having the results ready later.

type SafeWriter Uses

type SafeWriter struct {
    Manifest *Manifest
    // contains filtered or unexported fields

SafeWriter transactionalizes writes of manifest, lock, and vendor dir, both individually and in any combination, into a pseudo-atomic action with transactional rollback.

It is not impervious to errors (writing to disk is hard), but it should guard against non-arcane failure conditions.

func NewSafeWriter Uses

func NewSafeWriter(manifest *Manifest, oldLock, newLock *Lock, vendor VendorBehavior, prune gps.CascadingPruneOptions, status map[string]verify.VendorStatus) (*SafeWriter, error)

NewSafeWriter sets up a SafeWriter to write a set of manifest, lock, and vendor tree.

- If manifest is provided, it will be written to the standard manifest file name beneath root.

- If newLock is provided, it will be written to the standard lock file name beneath root.

- If vendor is VendorAlways, or is VendorOnChanged and the locks are different, the vendor directory will be written beneath root based on newLock.

- If oldLock is provided without newLock, error.

- If vendor is VendorAlways without a newLock, error.

func (*SafeWriter) HasLock Uses

func (sw *SafeWriter) HasLock() bool

HasLock checks if a Lock is present in the SafeWriter

func (*SafeWriter) HasManifest Uses

func (sw *SafeWriter) HasManifest() bool

HasManifest checks if a Manifest is present in the SafeWriter

func (*SafeWriter) PrintPreparedActions Uses

func (sw *SafeWriter) PrintPreparedActions(output *log.Logger, verbose bool) error

PrintPreparedActions logs the actions a call to Write would perform.

func (*SafeWriter) Write Uses

func (sw *SafeWriter) Write(root string, sm gps.SourceManager, examples bool, logger *log.Logger) error

Write saves some combination of manifest, lock, and a vendor tree. root is the absolute path of root dir in which to write. sm is only required if vendor is being written.

It first writes to a temp dir, then moves them in place if and only if all the write operations succeeded. It also does its best to roll back if any moves fail. This mostly guarantees that dep cannot exit with a partial write that would leave an undefined state on disk.

If logger is not nil, progress will be logged after each project write.

type SolveMeta Uses

type SolveMeta struct {
    AnalyzerName    string
    AnalyzerVersion int
    SolverName      string
    SolverVersion   int
    InputImports    []string

SolveMeta holds metadata about the solving process that created the lock that is not specific to any individual project.

type TreeWriter Uses

type TreeWriter interface {
    PrintPreparedActions(output *log.Logger, verbose bool) error
    Write(path string, sm gps.SourceManager, examples bool, logger *log.Logger) error

A TreeWriter is responsible for writing important dep states to disk - Gopkg.lock, vendor, and possibly Gopkg.toml.

func NewDeltaWriter Uses

func NewDeltaWriter(p *Project, newLock *Lock, behavior VendorBehavior) (TreeWriter, error)

NewDeltaWriter prepares a vendor writer that will construct a vendor directory by writing out only those projects that actually need to be written out - they have changed in some way, or they lack the necessary hash information to be verified.

type VendorBehavior Uses

type VendorBehavior int

VendorBehavior defines when the vendor directory should be written.

const (
    // VendorOnChanged indicates that the vendor directory should be written
    // when the lock is new or changed, or a project in vendor differs from its
    // intended state.
    VendorOnChanged VendorBehavior = iota
    // VendorAlways forces the vendor directory to always be written.
    // VendorNever indicates the vendor directory should never be written.


cmd/depDep is a tool for managing dependencies for Go projects
gpsPackage gps is a Go packaging solver library.
gps/internal/pbPackage pb provides generated Protocol Buffers for cache serialization.
vendor/ errors provides simple error handling primitives.

Package dep imports 22 packages (graph) and is imported by 149 packages. Updated 2020-09-05. Refresh now. Tools for package owners.