pkgmgr:store
pkgmgr:store@0.0.0
A document is written as one of catalogManifest.
coordinate
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
namespace | string | Yes | Who produced the package and answers for it: the segment before the colon. Letters, digits, ., _ and - | |
name | string | Yes | The package's name within that namespace: the segment after the colon, up to any @. Letters, digits, ., _ and - | |
version | version | No | The version this coordinate pins, absent where it names no one version | |
latest | enum one of latest | No | Set where the coordinate was written @latest: the same reference as leaving the version off, said out loud rather than by omission |
Written as, for example:
"type:type""dev-tool:config@0.0.0"
pkgStore
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
uri | string | Yes | Where this store is. A relative path resolves against whatever declares the location -- the repository that configures a store, or the catalog that names an upstream -- and may not climb out of it: a store somewhere else is named by an absolute uri, or by one expanding ${CATALOG_ROOT}, as ${CATALOG_ROOT}/build, because where another checkout sits is a fact about the machine rather than about this repository. CATALOG_ROOT is the one variable a uri may expand; any other is refused as STORE_URI_VARIABLE_UNDECLARED. | |
type | enum one of local, git, archive | No | "local" | How the uri is reached. local is a filesystem path, read and written where it is. git is a repository's address: it is cloned into the user's cache directory, brought up to date once per operation, refused as STORE_FETCH_FAILED rather than read from an earlier copy when that cannot be done, and only ever read -- a write to one is refused as STORE_READ_ONLY. archive is the http: or https: address a store's own files are served under, each at its path in the store: its manifest and index are fetched into the same cache once per operation and an artifact the first time a lookup resolves to it, on the same terms -- STORE_FETCH_FAILED rather than an earlier copy, and only ever read. A gated one is sent the bearer token the caller resolving it supplies; a store document never holds one. |
directory | string | No | For a git store, the directory inside the fetched repository that is the store's root, relative to the repository's own: a repository of catalogs keeps one directory per catalog. Absent, the repository's root is the store. An archive store's uri names the store itself, so it states none. | |
ref | string | No | For a git store, the branch or tag of the repository that is read. Absent, the remote's default branch. It is fetched by name on every operation, so a branch is followed as it moves; stores naming different refs of one repository are fetched into clones of their own. | |
remote | string | No | The git repository this store's checkout is cloned from, where it is one: what a machine without the checkout clones to obtain it. Recorded beside the absolute uri of the clone, because both are facts about the machine's setup rather than about any repository that reads through the store. | |
updateOnRead | boolean | No | false | Bring this store's git checkout up to date with its upstream branch before it is read -- a lookup through a chain that reaches it, or a pull out of it. For a store other people write to, where reading what was held at the last pull would answer with a release that has since been superseded. A store that is not a git checkout, has no upstream, or would not fast-forward is refused rather than read stale. Pulled at most once per operation however many links reach it. |
updateOnWrite | boolean | No | false | Bring this store's git checkout up to date with its upstream branch before anything is registered or pushed into it, so a write cannot land on top of entries someone else wrote since the last pull. Refused on the same terms as updateOnRead. |
catalogUpstream
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
store | string | Yes | The label of a store in the same configuration's stores, whose location this entry defers to | |
shallow | boolean | No | false | Ask this store and stop there. Ordinarily the upstream's own upstreams are asked after it, in the order its configuration writes them. |
readInPlace | boolean | No | false | Read what this upstream answers -- itself or anything reached through it -- where it is. Ordinarily a hit is registered into the catalog that asked, so the next lookup is answered at home. |
pullOnly | boolean | No | false | This upstream is only where pkg pull and pkg push go. A lookup never reads through it: the catalog answers from what it holds, and the user decides when to pull an entry in or push one out. |
sameTree | boolean | No | false | This upstream is filled by the same working tree's own builds, so a build made from uncommitted source may answer from it. Off by default, which is what a catalog pulled or copied from elsewhere is: what it holds was built from source nobody here can obtain, and only a build keyed by a commit can be resolved across that boundary. It is declared rather than worked out from the path because whether two checkouts are one tree is a fact about how they are used, not about where they sit. |
catalogManifest
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
schemaVersion | version | Yes | The version of this document's schema that this document was written under -- granted by the meta-schema to every definition named in metadata.documentRoots, never declared | |
pkg | string | Yes | What this catalog's content is: an open identifier. build, schema and repo-adapter are the ones dev-tool reads, and a catalog reached in one of those roles, directly or as an upstream, must say so or is refused. Any other value, such as platform, is unconstrained. It is an identifier, never a location: the content root is always the directory holding this manifest. | |
artifactFilename | string | No | What an artifact is called inside a version's directory, for a catalog whose entries are files | |
versionShape | enum one of major, major.minor, major.minor.patch | No | How a version renders into a directory name and an index key. Absent, the reader's own default answers. | |
indexLayout | enum one of single, per-package | No | "single" | How the package index is kept. single, the default, is one .pkgmgr/pkgs.yml naming every package and each one's stored latest. per-package is one .pkgmgr/pkgs/<namespace>/<name>.yml per package with latest left out and worked out from the versions present on read, for a catalog several people release into through merged branches: two releases of different packages then touch no common file, so their pull requests merge without a conflict nobody meant. |
catalogLink
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
store | string | Yes | The label the store is configured under, in the configuration that named it as an upstream | |
uri | string | Yes | The store's uri as its configuration wrote it | |
root | path | No | The directory it names, absent when the uri is not a directory reachable here | |
defaultedRoot | path | No | The root a variable in the uri was read as because the environment did not set it, absent where the uri names no variable or the environment answered. A report of a store that could not be reached names it. | |
seed | boolean | Yes | Whether a hit here is registered into the catalog the chain was resolved for: the opposite of readInPlace on the entry this link was reached through, so an entry decides for everything its chain reaches | |
sameTree | boolean | No | false | Whether this link is filled by the same working tree's own builds, carried from sameTree on the entry it was reached through, so a build made from uncommitted source may be resolved from it |
updateOnRead | boolean | No | false | Whether the store this link names asks to be brought up to date before it is read, carried from its updateOnRead. The chain has already done so by the time it is returned. |
updateOnWrite | boolean | No | false | Whether the store this link names asks to be brought up to date before it is written, carried from its updateOnWrite |