Projects and dependencies

gritpack.toml, init, add, remove, and the packages directory

Chapter 5 of 34Current for Gritpack 1.2.63Source: docs/guide/05-projects-and-dependencies.md

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:

  1. writes the requirement into gritpack.toml;
  2. resolves the whole graph, including what @ada/greet itself needs, and writes the result to gritpack.lock;
  3. 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 verify reports them and gritpack sync puts 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 folderCommit it?Why
gritpack.tomlyeswhat the project asks for
gritpack.lockyesexactly what it got, so everyone gets the same
packages/norebuilt from the lock by gritpack sync
.gritpack/noGritpack'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 --json and prints a gritpack-project-change/1 report 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