Projects and dependencies
gritpack.toml, init, add, remove, and the packages directory
Most days with a package manager are the same few moves: start a project, add what it needs, take out what it no longer needs, and hand the result to a colleague who gets exactly the same thing. This chapter covers the first three, with the files they change. The next chapter covers the last one, the lock file.
What you will be able to do
- create a project and read its
gritpack.toml; - add dependencies with the version range you mean;
- choose a variant when a package has several;
- remove a dependency cleanly;
- decide what to commit to version control.
The project manifest
A project is a directory with a gritpack.toml. gritpack init writes a
minimal one:
$ gritpack init --dialect c/c23
initialized hello 0.1.0 dialect=c/c23 at ./gritpack.toml status=changed
$ cat gritpack.toml
[dependencies]
[package]
dialect = "c/c23"
name = "hello"
version = "0.1.0"
The [package] table describes the project itself. Its name defaults to the
directory's name, and its version to 0.1.0. Choose others when you like:
gritpack init parser --dialect c/c23 --version 1.0.0
gritpack init --dialect c/c23 --path ./libs/parser
init never overwrites an existing gritpack.toml. Run it twice and the
second run says status=unchanged.
The [dependencies] table lists what the project needs. You rarely edit it
by hand, because add does it for you, but it is an ordinary TOML file and
hand edits are fine.
Under the hood. The manifest only describes the package: its identity, its files and its dependencies. It never holds a hub address, a password or build settings. Which hub a package came from is recorded in the lock file instead, so the same manifest works for everyone on the team.
Projects that already have a manifest
If the directory already belongs to Cargo, npm or Go, init notices
Cargo.toml, package.json or go.mod and does not write a competing
gritpack.toml. That ecosystem's own tool stays in charge of dependencies,
and Gritpack connects it to your hub instead (chapters 10 to 12). If it finds
more than one, it stops and asks you to pick with
--adapter cargo|npm|go|native|c. It decides from file names alone and never
runs another tool to find out.
Adding a dependency
$ gritpack add @ada/greet
added @ada/greet and installed 2 packages into ./packages
add does three things in one step:
- writes the requirement into
gritpack.toml; - resolves the whole graph, including what
@ada/greetitself needs, and writes the result togritpack.lock; - downloads, checks and unpacks every package into
packages/.
Everything is checked before anything is replaced. If any step fails, your
packages/ folder and lock file stay as they were.
Saying which versions you accept
With no version, add takes the newest release and saves a compatible range
for it:
"@ada/greet" = "^2.0.0"
Give a version to start from an older line. A plain version is saved as a compatible range, the way npm does it:
$ gritpack add @ada/greet 1.0
added @ada/greet and installed 2 packages into ./packages
$ gritpack list
@ada/greet 1.0.1 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.toml now says "@ada/greet" = "^1.0", and Gritpack chose 1.0.1,
the newest 1.x release. To pin one exact version, put = in front:
gritpack add @ada/greet '=1.0.0'
The quotes matter in zsh, which otherwise reads =1.0.0 as the path of a
command called 1.0.0. Quote any requirement with ^, ~, <, > or *
too.
Chapter 4 lists every requirement form.
A dependency is added once
add refuses a package that is already in gritpack.toml, so it never
silently changes a range you chose:
$ gritpack add @ada/greet
invalid manifest: dependency @ada/greet already exists
To change the range, use gritpack upgrade (chapter 7) or edit the line and
run gritpack sync.
Choosing a variant
Most packages have one variant for each version, or one per platform where Gritpack picks yours. When a package was published in several dialects or encodings, say which you want:
gritpack add native-parser --dialect c/c23
gritpack add native-parser 2.1 --dialect c/c23 --target x86_64-unknown-linux-gnu
The choice is saved with the dependency:
[dependencies]
native-parser = { version = "^2.1", dialect = "c/c23", target = "x86_64-unknown-linux-gnu" }
Without a selector, Gritpack only goes ahead when exactly one variant fits. If several do, it stops and asks you to choose. It never picks one at random.
Where the packages go
By default packages are unpacked into packages/ in the project:
packages/
├── @ada/
│ ├── greet/
│ └── strings/
├── .gritpack-install.json
└── .gritpack-universe.json
Every package sits directly under packages/ by its full name, whether you
asked for it or something else did. A scoped name becomes two folders,
@ada/greet/. Each package folder holds exactly the files that were
published, including its own gritpack.toml, and nothing else. Gritpack does
not rename, compile or rewrite them. The two hidden files record what was
installed, so verify and sync can check the folder against the lock.
Point your compiler or build at these folders. For C and C++, chapter 13 shows how to get include and link settings without typing paths.
To use another folder, pass --packages-dir or set GRITPACK_PACKAGES_DIR:
gritpack add @ada/greet --packages-dir third_party/gritpack
A relative folder is taken relative to the project directory. Gritpack only replaces a folder it recognises as its own; it refuses to overwrite a folder it did not create.
Careful. Treat
packages/as Gritpack's. Edits you make there are not kept:gritpack verifyreports them andgritpack syncputs the published files back.
Removing a dependency
The dependable way to remove a dependency is to delete its line from
gritpack.toml and run sync:
$ gritpack sync
synchronized 0 packages into ./packages status=changed
Gritpack resolves again from the manifest, so the package goes, and so does
everything that was there only because of it. @ada/strings went with
@ada/greet here. The lock file is rewritten to match.
There is also a remove command:
$ gritpack remove @ada/greet
removed @ada/greet
In Gritpack 1.2.63, for a single project, remove takes the package out of
gritpack.lock and packages/ but leaves its line in gritpack.toml, so the
next sync installs it again, and verify complains until then that the
manifest and lock disagree. Use the manifest-and-sync route above until
that changes. remove refuses a package that something else still needs:
$ gritpack remove @ada/strings
invalid lock file: cannot remove @ada/strings; required by @ada/greet
What to commit
| File or folder | Commit it? | Why |
|---|---|---|
gritpack.toml | yes | what the project asks for |
gritpack.lock | yes | exactly what it got, so everyone gets the same |
packages/ | no | rebuilt from the lock by gritpack sync |
.gritpack/ | no | Gritpack's working files, such as publication plans |
A .gitignore for a Gritpack project:
/packages/
/.gritpack/
A colleague who clones the repository runs gritpack sync and gets the same
packages, byte for byte.
For automation. Every command in this chapter takes
--jsonand prints agritpack-project-change/1report instead of a sentence: the command, the packages and versions that resulted, and where they went. Chapter 27 shows how to use it.
What just happened
A project is one manifest that says what you want. add writes a requirement,
resolves the whole graph, writes the lock and installs, in one step that
either completes or changes nothing. Dependencies of dependencies are
installed next to yours, by name, in one flat folder. Removing a line and
running sync removes the package and everything only it needed.
You can stop here
If you add and remove dependencies in one project, you know what you need. The lock file is worth one more chapter if you share the project or build it in CI.
Next
- What the lock file promises, and how to rely on it: The lock file and sync.
- Optional: the C and C++ side of
packages/, in C and C++.