A small mental model

Package, name, scope, version, variant, hub, login, lock: the few ideas everything else uses

Chapter 4 of 34Current for Gritpack 1.2.63Source: docs/guide/04-a-small-mental-model.md

In the last chapter you ran the commands. This chapter names the handful of ideas those commands are built from. Once you have them, the rest of the guide is mostly combinations you can already picture. It is a short chapter on purpose: the details live in the chapters that need them.

What you will be able to do

  • name the parts of a package and how they fit together;
  • tell a requirement you write apart from a version Gritpack locks;
  • read a version requirement such as ^1.2 or =1.0.0;
  • say where a package comes from and where it ends up on your disk.

A package has a name

A package is a named piece of software. Its name takes one of two forms:

greet          a global name, shared by everyone on that hub
@ada/greet     the name "greet" inside the scope "@ada"

A scope, such as @ada, decides who may publish under it on a hub: only its owner. A global name belongs to whoever published it first. The two forms are different packages, never aliases of each other: greet and @ada/greet have nothing to do with each other.

A scope does not make a package private. Every package on a hub is visible to everyone who can read that hub. Privacy comes from the hub itself: a private hub is read only by the people invited to it. Chapter 22 covers names and scopes in full.

A version never changes

A version is one release of a package. Versions follow Semantic Versioning: 1.4.2, 0.2.0, 2.0.0-rc.1. The first number changes when a release breaks something, the second when it adds something, the third when it only fixes something.

Once a version is published it never changes: not its files, not its description, not its README. A fix ships as a new version. That one rule is what makes everything else trustworthy: a lock file written six months ago still names exactly the same bytes today.

A publisher can still say something about an old version. Deprecating it attaches a warning, such as "use 0.2 or later". Yanking it stops new projects from choosing it, while projects that already locked it keep working. Neither changes the version itself. Chapter 18 shows both.

A variant says what kind of package it is

Gritpack serves many languages, which is not the same as being language-neutral. Every package says what it is with a dialect, written family/edition:

c/c23    c++/c++20    rust/2024    go/1.23    application/cli

Two optional fields describe a variant further. Encoding says how the contents are represented (source/utf8, executable/native). Target says which platform a built variant is for (x86_64-unknown-linux-gnu, aarch64-apple-darwin).

One name and version can have several variants. The gritpack package has one variant per platform for each version, and Gritpack picks the one for your machine. Most of the time you never name a variant yourself; when two would match, Gritpack asks you to choose with --dialect, --encoding or --target rather than pick one at random.

A dependency is a name and a requirement

A dependency is one package asking for another. In gritpack.toml it is a name and a requirement:

[dependencies]
"@ada/greet" = "^2.0.0"

A requirement is a range you accept, not a single version:

RequirementAccepts
^1.2.31.2.3 and newer, but not 2.0.0: compatible releases
~1.2.31.2.3 and newer patches, but not 1.3.0
=1.2.3exactly 1.2.3
1.2.3exactly 1.2.3, when written in gritpack.toml
>=1.2.3, <2.0.0both conditions at once
1.2.*any 1.2 release
*any version

Pre-release versions such as 2.0.0-rc.1 are left out unless the requirement names a pre-release itself.

When you add a dependency from the command line, Gritpack writes a compatible range for you, as npm does: gritpack add @ada/greet 1.2.3 saves ^1.2.3, and gritpack add @ada/greet saves ^ of the newest version. To pin an exact version, ask for it with =1.2.3.

From Cargo. In Cargo.toml a bare 1.2.3 means ^1.2.3. In gritpack.toml a bare 1.2.3 means exactly that version. The command line writes the caret for you, so you only meet the difference if you edit the file by hand.

The lock records exactly what you got

The requirement is your intent. The lock is the outcome.

RequirementLock entry
Lives ingritpack.tomlgritpack.lock
Looks like^2.0.02.0.0, its digest, the hub it came from
Chosen byyouGritpack, when it resolves
Changes whenyou edit it, or run add or upgradeyou run add, update or upgrade

When Gritpack resolves, it looks at every requirement in the whole graph, your own and those of your dependencies, and picks the highest version of each package that satisfies all of them at once. Each package name appears once in a project: if two packages need different ranges of the same library, Gritpack finds one version both accept, or stops and tells you which chain of requirements disagrees. It never guesses.

The lock also records where each package came from and the digest of its package file. gritpack sync replays the lock without deciding anything again. That is the whole difference between reproducing a result and resolving a new one.

A version travels as a package file

Every published version is one package file: a single file holding the package's files and its manifest, with one SHA-256 digest that proves its contents. The hub records that digest when the version is published. Your client checks it on every download, and checks it again when it reads a file back from its cache. A package file that does not match is never installed.

You rarely handle package files directly. gritpack pack makes one, and gritpack publish makes and uploads one for you (chapter 16).

A hub is where packages live

A hub is a package registry. The public hub, get.gritpack.org, can be read by anyone. A private hub is read only by the people invited to it.

To use a private hub you log in once. Gritpack saves the result as a profile: a name, the hub's address and the credential that proves who you are. With one profile there is nothing to choose; with several, one is the default and --profile picks another. Logins last 30 days and are renewed before they expire (chapter 20).

When you have a private profile, Gritpack asks that hub first and the public hub only when the private hub has never heard of a name. Chapter 9 explains this chain and how to step outside it.

Where things end up

WhatWhereShared by
Your project's manifest and lockgritpack.toml, gritpack.lockthe project; commit both
Its installed packagespackages/ in the projectthe project; rebuilt by sync
Downloaded package files~/.frogfish/gritpack/cacheevery project of your user
Applications~/.frogfish/gritpack/store and binyour user
Logins~/.frogfish/gritpack/config.toml and credentials/your user

packages/ is flat: every package, direct or transitive, sits directly under it by its full name, so @ada/strings is at packages/@ada/strings/ even though only @ada/greet asked for it. Nothing is nested inside the package that needed it.

From npm. This is like node_modules without nesting: one version of each name per project, always.

What just happened

The everyday model is a handful of words:

package (global or scoped name) · version (never changes) · variant (dialect, encoding, target) · dependency (name and requirement) · lock (the exact result) · package file (what a version travels as, with its digest) · hub and login (where packages live, and how you reach a private one).

Every later chapter is these in combination.

You can stop here

If you only use packages, this is the whole mental model. You never need to know how a package file is laid out inside or how a hub stores one.

Next