Your first five minutes
Search the public hub, look at a package, install an application, start a project
You have Gritpack installed and want to see it do something useful before reading any more. In five minutes you will look around the public hub, install an application and remove it again, then start a project and add a dependency to it. The first half needs no account at all.
What you will be able to do
- search the public hub and read about a package;
- install a command-line application for your user, and remove it;
- create a project, add a dependency and see exactly what you got;
- check the whole setup with one command.
1. Look around the public hub
With no login configured, Gritpack talks to the public hub,
get.gritpack.org. Ask it what it has:
$ gritpack search
@frogfish/gritpack 1.2.10 ecosystem=native score=0 dialect=application/cli variants=3 — Universal package, module-graph, and software distribution client [deprecated: Package renamed to gritpack. Install with: gritpack install gritpack --from get.gritpack.org]
@frogfish/gritpack-bootstrap 1.2.8 ecosystem=native score=0 dialect=application/bootstrap variants=1 — Compatibility bridge from pre-global-install Gritpack clients
@frogfish/scroll-throttle 1.0.0 ecosystem=native score=0 dialect=application/cli variants=1 — Rate-limits X11 scroll-wheel events; fixes unusably fast scrolling caused by a high-resolution trackpad relayed through RDP to a Linux X11 session
gritpack 1.2.63 ecosystem=native score=0 dialect=application/cli variants=64 — Universal package, module-graph, and software distribution client
gritpack-installer 1.2.63 ecosystem=native score=0 dialect=application/cli variants=61 — Installs one application, and Gritpack when it is missing
Each line is one package: its name, newest version, what kind of package it
is (dialect=application/cli), how many variants were published (one per
platform, here) and its description. A deprecated package says so, with the
publisher's advice.
Today the public hub holds Gritpack itself and a few small applications. Words narrow the search:
$ gritpack search throttle
@frogfish/scroll-throttle 1.0.0 ecosystem=native score=250 dialect=application/cli variants=1 — Rate-limits X11 scroll-wheel events; fixes unusably fast scrolling caused by a high-resolution trackpad relayed through RDP to a Linux X11 session
Read one package in full:
$ gritpack info @frogfish/scroll-throttle
@frogfish/scroll-throttle 1.0.0 (native)
Rate-limits X11 scroll-wheel events; fixes unusably fast scrolling caused by a high-resolution trackpad relayed through RDP to a Linux X11 session
dialect: application/cli
encoding: executable/native
target: x86_64-unknown-linux-gnu
versions: 1.0.0
variants: 1
license: MIT
owner: 01a075b2-d7da-77d0-a3e5-0fc4f6c79fb5
...
sha256: 6e1743d5e3773ff1a3e102eaea0cce4b62148e3f8069839c39f6792ddccba598
target says which platform this variant was built for. owner is the
account that published it. sha256 is the digest of the package file:
whatever you download is checked against it.
2. Install an application, then remove it
@frogfish/scroll-throttle is a small Linux tool. Installing it shows what
Gritpack does with applications:
$ gritpack install @frogfish/scroll-throttle
resolving @frogfish/scroll-throttle latest for x86_64-unknown-linux-gnu from the configured registry chain…
downloading and verifying 1 package…
installing and activating commands…
installed @frogfish/scroll-throttle 1.0.0 from https://get.gritpack.org:443 into /home/ada/.frogfish/gritpack commands=scroll-throttle integrity=verified provenance=registry-recorded
Gritpack picked the variant for this machine, checked the download, unpacked
it, and put a scroll-throttle command in ~/.frogfish/gritpack/bin. Ask
where a command comes from, and list what you have:
$ gritpack app which scroll-throttle
scroll-throttle -> @frogfish/scroll-throttle 1.0.0 (https://get.gritpack.org:443)
$ gritpack app list
@frogfish/scroll-throttle 1.0.0 provenance=registry-recorded origin=https://get.gritpack.org:443 commands=scroll-throttle
You did not want a scroll throttle, so take it away again:
$ gritpack uninstall @frogfish/scroll-throttle
uninstalled @frogfish/scroll-throttle 1.0.0 commands=scroll-throttle
On a Mac or on Windows there is no variant of this tool for your platform, so
install stops with cannot resolve @frogfish/scroll-throttle and exit code
5 (not found). Nothing is installed. Read along, or try the same commands
with gritpack itself, which you already have.
3. Start a project
A project is a directory with a gritpack.toml that lists what it
depends on. Make one:
$ mkdir hello && cd hello
$ gritpack init --dialect c/c23
initialized hello 0.1.0 dialect=c/c23 at ./gritpack.toml status=changed
--dialect says what kind of package the project itself is; c/c23 is C in
its 2023 edition. Gritpack needs it for a new native project and refuses to
guess:
$ gritpack init
cannot initialize project: a new native package needs --dialect, for example --dialect c/c23
If the directory already has a Cargo.toml, package.json or go.mod,
gritpack init recognises it and does not write a competing manifest; your
ecosystem's own file stays in charge (chapters 10 to 12).
4. Add a dependency
A project needs libraries, and the public hub holds applications rather than libraries today. So the rest of this chapter uses a private hub, the kind a team uses. If you have been invited to one, log in first (chapter 20 explains invitations):
gritpack login packages.example.com --email ada@example.com
If you have not, read along: the commands are the same on any hub.
Add the library @ada/greet:
$ gritpack add @ada/greet
added @ada/greet and installed 2 packages into ./packages
One command did three things. It wrote the requirement into gritpack.toml:
[dependencies]
"@ada/greet" = "^2.0.0"
It worked out every package needed, wrote the exact result into a new file,
gritpack.lock, and unpacked the checked files into packages/. Two
packages, because @ada/greet itself depends on @ada/strings:
$ gritpack list
@ada/greet 2.0.0 dialect=c/c23 direct source=https://packages.example.com:443 dependencies=@ada/strings
@ada/strings 1.1.0 dialect=c/c23 transitive source=https://packages.example.com:443 dependencies=-
$ gritpack why @ada/strings
@ada/greet -> @ada/strings
direct means you asked for it. transitive means something you asked for
needs it, and why shows the chain.
The files are where your build can find them:
packages/
├── @ada/
│ ├── greet/
│ │ ├── gritpack.toml
│ │ ├── README.md
│ │ ├── include/greet.h
│ │ └── src/greet.c
│ └── strings/
│ ├── gritpack.toml
│ ├── README.md
│ ├── include/strings_ex.h
│ └── src/strings_ex.c
├── .gritpack-install.json
└── .gritpack-universe.json
Point your compiler at packages/@ada/greet/include and build as you
always do. Gritpack never compiles anything.
5. Prove it reproduces
packages/ is only a copy of what the lock describes, so deleting it is
safe:
$ rm -rf packages
$ gritpack sync
synchronized 2 packages into ./packages status=changed
$ gritpack sync
synchronized 2 packages into ./packages status=unchanged
The first sync put the files back: the same versions and the same bytes,
because it read the lock instead of choosing again. The second had nothing to
do and said so.
6. Check everything at once
$ gritpack doctor
PASS project — detected native at /home/ada/hello
PASS profile — profile=work provider=file
PASS provider — credential material resolved
PASS identity — account=01a1e866-03d9-7440-9677-13a172f2c676 email=ada@example.com status=Active
PASS hub — repository=550e8400-e29b-41d4-a716-446655440000 endpoint=https://packages.example.com:443
PASS local — workspace: workspace directory exists
PASS local — manifest: 1 direct dependencies
PASS local — lock: lock v4 with 2 packages
PASS local — installed-universe: 2 verified packages
PASS local — consistency: universe 8efb3ff1... matches manifest and lock
...
Each line is one layer: the project, your login, the hub, the lock and the
installed files. A failing line comes with a repair: line naming the command
that fixes it. doctor checks your login too, so without one its profile
line fails and tells you to run gritpack login.
What just happened
You used the public hub without an account, installed and removed an application, and built a project with:
- a manifest,
gritpack.toml, that says what you want (^2.0.0); - a lock,
gritpack.lock, that records exactly what you got and from where; - a
packages/folder that matches the lock byte for byte; - one command,
doctor, that checks all of it.
You can stop here
If you wanted a dependable way to pull packages into a project and get the same result tomorrow, you have it. The next chapters explain what you just did in more depth.
Next
- The few ideas underneath all of this: A small mental model.
- Optional: if you came for applications rather than projects, go to Installing applications.