dep

Edit

Glossary

dep uses some specialized terminology. Learn about it here!

Atom

Atoms are a source at a particular version. In practice, this means a two-tuple of project root and version, e.g. github.com/foo/bar@master. Atoms are primarily internal to the solver, and the term is rarely used elsewhere.

Cache lock

Also "cache lock file." A file, named sm.lock, used to ensure only a single dep process operates on the local cache at a time, as it is unsafe in dep's current design for multiple processes to access the local cache.

Constraint

Constraints have both a narrow and a looser meaning. The narrow sense refers to a [[constraint]] stanza in Gopkg.toml. However, in some contexts, the word may be used more loosely to refer to the idea of applying rules and requirements to dependency management in general.

Current Project

The project on which dep is operating - writing its Gopkg.lock and populating its vendor directory.

Also called the "root project."

Deducible

A shorthand way of referring to whether or not import path deduction will return successfully for a given import path. "Undeducible" is also often used, to refer to an import path for which deduction fails.

Deduction

Deduction is the process of determining the subset of an import path that corresponds to a source root. Some patterns are known a priori (static); others must be discovered via network requests (dynamic). See the reference on import path deduction for specifics.

Direct Dependency

A project's direct dependencies are those that it imports from one or more of its packages, or includes in its required list in Gopkg.toml.

If each letter in A -> B -> C -> D represents a distinct project containing only a single package, and -> indicates an import statement, then B is A's direct dependency, whereas C and D are transitive dependencies of A.

Dep only incorporates the required rules from the current project's Gopkg.toml. Therefore, if => represents required rather than a standard import, and A -> B => C, then C is a direct dependency of B only when B is the current project. Because the B-to-C link does not exist when A is the current project, then C won't actually be in the graph at all.

External Import

An import statement that points to a package in a project other than the one in which it originates. For example, an import in package github.com/foo/bar will be considered an external import if it points to anything other than stdlib or github.com/foo/bar/*.

GPS

Acronym for "Go packaging solver", it is a subtree of library-style packages within dep, and is the engine around which dep is built. Most commonly referred to as "gps."

Local cache

dep maintains its own, pristine set of upstream sources (so, generally, git repository clones). This is kept separate from $GOPATH/src so that there is no obligation to maintain disk state within $GOPATH, as dep frequently needs to change disk state in order to do its work.

By default, the local cache lives at $GOPATH/pkg/dep. If you have multiple $GOPATH entries, dep will use whichever is the logical parent of the process' working directory. Alternatively, the location can be forced via the DEPCACHEDIR environment variable.

Lock

A generic term, used across many language package managers, for the kind of information dep keeps in a Gopkg.lock file.

Manifest

A generic term, used across many language package managers, for the kind of information dep keeps in a Gopkg.toml file.

Metadata Service

An HTTP service that, when it receives an HTTP request containing a go-get=1 in the query string, treats interprets the path portion of the request as an import path, and responds by embedding data in HTML <meta> tags that indicate the type and URL of of the underlying source root. This is the server-side component of dynamic deduction.

The behavior of metadata services is defined in the Go documentation on remote import paths.

Variously referenced as "HTTP metadata service", "go-get HTTP metadata service", "go-get service", etc.

Override

An override is a [[override]] stanza in Gopkg.toml.

Project

A project is a tree of Go packages. Projects cannot be nested. See Project Root for more information about how the root of the tree is determined.

Project Root

The root import path for a project. A project root is defined as:

  • For the current project, the location of the Gopkg.toml file defines the project root
  • For dependencies, the root of the network source (VCS repository) is treated as the project root

These are generally one and the same, though not always. When using dep inside a monorepo, multiple Gopkg.toml files may exist at subpaths for discrete projects, designating each of those import paths as Project Roots. This works fine when working directly on those projects. If, however, any project not in the repository seeks to import the monorepo, dep will treat the monorepo as one big Project, with the root directory being the Project Root; it will disregard any and all Gopkg.toml files in subdirectories.

This may also be referred to as the "import root" or "root import path."

Solver

"The solver" is a reference to the domain-specific SAT solver contained in gps. More detail can be found on its reference page.

Source

The remote entities that hold versioned code. Sources are specifically the entity containing the code, not any particular version of the code itself.

"Source" is used in lieu of "VCS" because Go package management tools will soon learn to use more than just VCS systems.

Source Root

The portion of an import path that corresponds to the network location of a source. This is similar to Project Root, but refers strictly to the second, network-oriented definition.

Sync

Dep is designed around a well-defined relationship between four states:

  1. import statements in .go files
  2. Gopkg.toml
  3. Gopkg.lock
  4. The vendor directory

If any aspect of the relationship is unfulfilled (e.g., there is an import not reflected in Gopkg.lock, or a project that's missing from vendor), then dep considers the project to be "out of sync."

This concept is explored in detail in ensure mechanics.

Transitive Dependency

A project's transitive dependencies are those dependencies that it does not import itself, but are imported by one of its dependencies.

If each letter in A -> B -> C -> D represents a distinct project containing only a single package, and -> indicates an import statement, then C and D are A's transitive dependencies, whereas B is a direct dependency of A.

Vendor Verification

Dep guarantees that vendor/ contains exactly the expected code by hashing the contents of each project and storing the resulting digest in Gopkg.lock. This digest is computed after pruning rules are applied.

The digest is used to determine if the contents of vendor/ need to be regenerated during a dep ensure run, and dep check uses it to determine whether Gopkg.lock and vendor/ are in sync. The noverify list in Gopkg.toml can be used to bypass most of these verification behaviors.

← Environment Variables