github.com/golang/dep@v0.5.4/docs/glossary.md (about) 1 --- 2 id: glossary 3 title: Glossary 4 --- 5 6 dep uses some specialized terminology. Learn about it here! 7 8 * [Atom](#atom) 9 * [Cache lock](#cache-lock) 10 * [Constraint](#constraint) 11 * [Current Project](#current-project) 12 * [Deducible](#deducible) 13 * [Deduction](#deduction) 14 * [Direct Dependency](#direct-dependency) 15 * [External Import](#external-import) 16 * [GPS](#gps) 17 * [Local cache](#local-cache) 18 * [Lock](#lock) 19 * [Manifest](#manifest) 20 * [Metadata Service](#metadata-service) 21 * [Override](#override) 22 * [Project](#project) 23 * [Project Root](#project-root) 24 * [Solver](#solver) 25 * [Source](#source) 26 * [Source Root](#source-root) 27 * [Sync](#sync) 28 * [Transitive Dependency](#transitive-dependency) 29 * [Vendor Verification](#vendor-verification) 30 31 --- 32 33 ### Atom 34 35 Atoms are a source at a particular version. In practice, this means a two-tuple of [project root](#project-root) and version, e.g. `github.com/foo/bar@master`. Atoms are primarily internal to the [solver](#solver), and the term is rarely used elsewhere. 36 37 ### Cache lock 38 39 Also "cache lock file." A file, named `sm.lock`, used to ensure only a single dep process operates on the [local cache](#local-cache) at a time, as it is unsafe in dep's current design for multiple processes to access the local cache. 40 41 ### Constraint 42 43 Constraints have both a narrow and a looser meaning. The narrow sense refers to a [`[[constraint]]`](Gopkg.toml.md#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. 44 45 ### Current Project 46 47 The project on which dep is operating - writing its `Gopkg.lock` and populating its `vendor` directory. 48 49 Also called the "root project." 50 51 ### Deducible 52 53 A shorthand way of referring to whether or not import path [deduction](#deduction) will return successfully for a given import path. "Undeducible" is also often used, to refer to an import path for which deduction fails. 54 55 ### Deduction 56 57 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](deduction.md) for specifics. 58 59 ### Direct Dependency 60 61 A project's direct dependencies are those that it _imports_ from one or more of its packages, or includes in its [`required`](Gopkg.toml.md#required) list in `Gopkg.toml`. 62 63 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](#transitive-dependency) of `A`. 64 65 Dep only incorporates the `required` rules from the [current project's](#current-project) `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. 66 67 ### External Import 68 69 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/*`. 70 71 ### GPS 72 73 Acronym for "Go packaging solver", it is [a subtree of library-style packages within dep](https://godoc.org/github.com/golang/dep/gps), and is the engine around which dep is built. Most commonly referred to as "gps." 74 75 ### Local cache 76 77 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. 78 79 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](env-vars.md#depcachedir). 80 81 ### Lock 82 83 A generic term, used across many language package managers, for the kind of information dep keeps in a `Gopkg.lock` file. 84 85 ### Manifest 86 87 A generic term, used across many language package managers, for the kind of information dep keeps in a `Gopkg.toml` file. 88 89 ### Metadata Service 90 91 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](#deduction). 92 93 The behavior of metadata services is defined in the [Go documentation on remote import paths](https://golang.org/cmd/go/#hdr-Remote_import_paths). 94 95 Variously referenced as "HTTP metadata service", "`go-get` HTTP metadata service", "`go-get` service", etc. 96 97 ### Override 98 99 An override is a [`[[override]]`](Gopkg.toml.md#override) stanza in `Gopkg.toml`. 100 101 ### Project 102 103 A project is a tree of Go packages. Projects cannot be nested. See [Project Root](#project-root) for more information about how the root of the tree is determined. 104 105 ### Project Root 106 107 The root import path for a project. A project root is defined as: 108 109 * For the current project, the location of the `Gopkg.toml` file defines the project root 110 * For dependencies, the root of the network [source](#source) (VCS repository) is treated as the project root 111 112 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. 113 114 This may also be referred to as the "import root" or "root import path." 115 116 ### Solver 117 118 "The solver" is a reference to the domain-specific SAT solver contained in [gps](#gps). More detail can be found on its [reference page](the-solver.md). 119 120 ### Source 121 122 The remote entities that hold versioned code. Sources are specifically the entity containing the code, not any particular version of the code itself. 123 124 "Source" is used in lieu of "VCS" because Go package management tools will soon learn to use more than just VCS systems. 125 126 ### Source Root 127 128 The portion of an import path that corresponds to the network location of a source. This is similar to [Project Root](#project-root), but refers strictly to the second, network-oriented definition. 129 130 ### Sync 131 132 Dep is designed around a well-defined relationship between four states: 133 134 1. `import` statements in `.go` files 135 2. `Gopkg.toml` 136 3. `Gopkg.lock` 137 4. The `vendor` directory 138 139 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." 140 141 This concept is explored in detail in [ensure mechanics](ensure-mechanics.md#staying-in-sync). 142 143 ### Transitive Dependency 144 145 A project's transitive dependencies are those dependencies that it does not import itself, but are imported by one of its dependencies. 146 147 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](#transitive-dependency) of `A`. 148 149 ### Vendor Verification 150 151 Dep guarantees that `vendor/` contains exactly the expected code by hashing the contents of each project and storing the resulting [digest in Gopkg.lock](Gopkg.lock.md#digest). This digest is computed _after_ pruning rules are applied. 152 153 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](#sync). The [`noverify`](Gopkg.toml.md#noverify) list in `Gopkg.toml` can be used to bypass most of these verification behaviors.