A shared project¶
A project that several people run, or one person runs on several machines, states its packages in two files and builds the rest on each machine. This page is what is committed, what a fresh clone does, and how a pinned version moves.
What is committed¶
| Path | Holds | In version control |
|---|---|---|
.hql/config.toml |
the declarations: [packages] dependencies, names with no version |
yes |
.hql/lock.toml |
the pins: one version and one source per declared package | yes |
.hql/packages/ |
the installed packages: built libraries | no |
.hql/cache/ |
the sources fetched to build from | no |
A library under .hql/packages/ is built for one hql, one compiler and
one platform
(the version rule), so it
is built on each machine and never shared. A .gitignore
beside the two files says so:
packages/
cache/
Declaring a package¶
hql package install writes both files. Here the project takes ml from
the registry (chapter 37):
hql package install ml
# .hql/config.toml
[packages]
dependencies = ["ml"]
# .hql/lock.toml
[[package]]
name = "ml"
version = "0.1.0"
source = "registry"
registry = "official"
tag = "hql-ext-ml-v0.1.0"
The declaration names the package. The pin names the version and where its
source is fetched from: the registry and the tag of the release. A version
written under dependencies is refused, since lock.toml is the one record
of versions.
A fresh clone¶
A clone has the two files and no .hql/packages/. A run in it fails before
any program is checked:
hql eval '1 + 1'
hql: package `ml` is a dependency in /home/bo/code/reading-club/.hql/config.toml and is not installed: run `hql package install`
The failure is the same for a program that imports nothing of the package: a declared dependency is part of the project's environment, and a run does not start in half of one.
hql package install with no name installs every declared package at the
version its pin names:
hql package install
installed ml 0.1.0 (ml, ml.metrics) in /home/bo/code/reading-club/.hql/packages/ml
It fetches the pinned source into .hql/cache/, builds it with this
machine's cargo against this machine's hql, and changes neither
committed file. A declared package that lock.toml does not pin is pinned
at the newest version this hql admits, and that is a change to lock.toml
to commit.
Moving a pin¶
| Command | Effect on the pin |
|---|---|
hql package update ml |
moves it to the version the registry now pins, and installs that version |
hql package install ml@0.2.0 |
sets it to the version named, and installs that version |
hql package remove ml |
drops the pin, the declaration and the installed package |
hql package rebuild ml |
none: builds the pinned version again, after hql was upgraded |
After update or install, lock.toml differs. Committing it is what
moves every other clone: each runs hql package install again and builds
the new version.
Path pins stay on one machine¶
A package installed with --path is pinned to the directory it was built
from, as an absolute path:
[[package]]
name = "hello"
version = "0.1.0"
source = "path"
path = "/home/ada/code/hello"
That directory exists on the machine that wrote the pin. On another, hql
package install finds no crate there and fails. A shared project
therefore pins from the registry, and uses a path in one of two ways that
commit nothing machine-specific:
[packages] pathswith a path relative to the project root, for a crate kept in the same repository as the project:paths = ["crates/hello"]. A listed crate is built on first use on every machine and is never pinned (A local crate).hql package install --home --path <dir>, which installs into the HQL home of one machine and writes the home'slock.toml, not the project's.
The project and the home¶
A run discovers packages in the project before the HQL home, so the
project's pinned version is the one its programs use, whatever a machine
has installed for itself with --home. hql package list names the level
of each:
ml 0.1.0 (ml, ml.metrics) [project]
hello 0.1.0 (hello) [home]