A small mental model
Package, name, scope, version, variant, hub, login, lock: the few ideas everything else uses
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.2or=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:
| Requirement | Accepts |
|---|---|
^1.2.3 | 1.2.3 and newer, but not 2.0.0: compatible releases |
~1.2.3 | 1.2.3 and newer patches, but not 1.3.0 |
=1.2.3 | exactly 1.2.3 |
1.2.3 | exactly 1.2.3, when written in gritpack.toml |
>=1.2.3, <2.0.0 | both 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.tomla bare1.2.3means^1.2.3. Ingritpack.tomla bare1.2.3means 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.
| Requirement | Lock entry | |
|---|---|---|
| Lives in | gritpack.toml | gritpack.lock |
| Looks like | ^2.0.0 | 2.0.0, its digest, the hub it came from |
| Chosen by | you | Gritpack, when it resolves |
| Changes when | you edit it, or run add or upgrade | you 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
| What | Where | Shared by |
|---|---|---|
| Your project's manifest and lock | gritpack.toml, gritpack.lock | the project; commit both |
| Its installed packages | packages/ in the project | the project; rebuilt by sync |
| Downloaded package files | ~/.frogfish/gritpack/cache | every project of your user |
| Applications | ~/.frogfish/gritpack/store and bin | your 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_moduleswithout 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
- The same ideas in daily use: Projects and dependencies.
- Optional: names, scopes and ownership in depth, in Names, scopes and owners.