What Gritpack is
What Gritpack does, what it leaves to your tools, and the words it uses
Most introductions to a package manager start with the package manager. This one starts with you. Perhaps you have a Rust crate that must not go to crates.io. Perhaps your Node project needs an internal package, or a C library reaches your team as a copied folder and a message that says "use the one on the shared drive". Perhaps one product holds all three, and a command-line tool you want your colleagues to install. Gritpack gives all of those a home: one place to publish them, find them, lock them and get them back, exactly, on any machine.
What you will be able to do
- say in a sentence what Gritpack does and what it leaves to your own tools;
- recognise the few words the rest of this guide uses;
- choose where to go next, depending on what you came for.
One client, one hub
Gritpack has two halves.
- The client is the
gritpackcommand on your computer. It finds packages, resolves versions, downloads and checks files, writes a lock file, publishes new versions and installs command-line applications for your user. - A hub is the package registry the client talks to. It stores every published version, decides who may publish under which name, and keeps a signed record of each publication.
There is one public hub, get.gritpack.org. Anyone can search it and install
from it without an account. Teams that need their packages kept to themselves
use a private hub. Frogfish runs private hubs for teams, as a service or on
the team's own premises under a written agreement. You join one when its
administrator invites you, and from then on the same commands work against it.
You never run a hub yourself to use Gritpack. You only need the client.
Many languages, one package home
Gritpack handles four kinds of package with the same client:
| Kind | What Gritpack does | What stays the same |
|---|---|---|
| Native packages: C, C++, applications, anything made of files | Packs, publishes, resolves, locks and installs them itself | Your build system: CMake, Meson, Make, or none |
| Rust crates | The hub is an ordinary Cargo registry next to crates.io | Cargo resolves, builds and publishes |
| npm packages | The hub is an npm registry for the scopes you choose | npm installs; your package.json stays yours |
| Go modules | The hub is a Go module proxy for your private module paths | The go command and go.mod |
For Rust, npm and Go, Gritpack sets your tools up to use the hub and adds publication checks and evidence. The familiar tool stays in charge of its own files. For native packages, which have no tool of their own, Gritpack does the whole job.
From Cargo.
cargo addandcargo buildkeep working. A private crate simply names the hub's registry, as you would name any alternate registry.
From npm.
@acme/parserstill means the packageparserin the scope@acme. Gritpack routes that scope to the hub and leaves the rest of npm alone.
What Gritpack is not
Gritpack is not a compiler and not a build system. It never compiles your code, and it never runs code from a package when it installs one: there are no install scripts. It does not need your work to live in Git, a monorepo service or any particular folder layout.
Those boundaries are on purpose. A package manager that also wants to be your build system has to understand every language and every build. Gritpack only has to understand packages: what files belong together, which version you asked for, which version you got, and whether the bytes on your disk are the bytes that were published.
Promises it keeps
A few rules hold everywhere in Gritpack. You will meet each one again.
- A published version never changes. Not its files, not its description. A fix is a new version. That is what lets a lock file from last year still mean something today.
- What you install is checked. Every downloaded package file is checked against the digest the hub recorded, and the installed files are checked against the lock.
- Nothing happens silently. A command that changes your project says
whether it changed anything (
status=changedorstatus=unchanged). A command that publishes asks first, unless you pass--yes. - A private name never quietly becomes a public one. When you use a private hub, the public hub is asked only when the private hub says it has never heard of a name. Network errors, refused logins and missing versions are errors, not reasons to look elsewhere.
- Publishing is all or nothing. When several packages are published together, either all of them become visible or none do.
Words you will see
You do not need to learn these now. Each chapter explains the one it uses.
| Word | Meaning |
|---|---|
| Package | A named piece of software, such as @ada/greet |
| Version | One published, unchangeable release of a package, such as 0.2.0 |
| Scope | The @ada in @ada/greet: who may publish under that name |
| Package file | The single file a version travels as; its digest proves its contents |
| Project | A directory with a gritpack.toml that lists what it depends on |
| Lock file | gritpack.lock: exactly which versions a project got, and from where |
| Hub | A package registry: the public one, or a private one you were invited to |
| Login | A credential for one hub, saved on your computer as a profile |
| Application | A package that provides commands, installed for your user |
Who this guide is for
The guide is written for three kinds of reader, in this order:
- Developers who want to get packages, publish their own, install applications and script Gritpack. Chapters 1 to 19 and 27 to 30.
- Teams sharing a private hub, with scopes, several packages in one repository, releases that publish together and evidence of who published what. Chapters 20 to 26.
- Hub administrators who invite people, assign scopes and decide which licences may be published. Chapters 31 and 32. This is about using a hub's administration commands, not about hosting one.
What just happened
You now know the shape of the whole system: a client on your computer, a hub that stores and vouches for packages, and four kinds of package that share one way of naming, locking and checking. Your own tools keep doing what they already do well.
You can stop here
If you only wanted to know whether Gritpack fits your problem, you have the answer. Everything else in this guide is about doing it.
Next
- Install the client: Install Gritpack.
- If you would rather see it working first, skim Your first five minutes, then come back.