Your first five minutes

Search the public hub, look at a package, install an application, start a project

Chapter 3 of 34Current for Gritpack 1.2.63Source: docs/guide/03-first-five-minutes.md

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