36. Installing packages¶
hql package builds a package from its crate and installs it into a
project, or into the HQL home, where every program on the machine reaches
it. This chapter is the commands, the files they write, and the settings of
.hql/config.toml that concern packages.
The commands¶
| Command | What it does |
|---|---|
hql package install <name> |
build a package the registry lists, install it into the project, declare it and pin it (chapter 37) |
hql package install --path <dir> |
build the package of a crate on this machine and install it into the project |
hql package install |
install every package the project declares, at the version it pins |
hql package list |
the packages installed in the project and in the HQL home, each with its modules and its level |
hql package info <name> |
what an installed package records about itself |
hql package rebuild [<name>] |
build an installed package again from its source; every installed package where none is named |
hql package remove <name> |
remove an installed package, its declaration and its pin |
install, rebuild, update and remove act on the project: the one
--project names, else the nearest directory at or above the working
directory holding .hql/config.toml. With --home they act on the HQL home
instead, as npm install -g acts on the machine rather than the project.
Without a project, each refuses and names --home.
This chapter installs from a directory, which needs no network and no
registry. Installing needs cargo on the PATH
(rustup installs it). Listing, describing and
removing need nothing but hql.
Installing¶
Inside a project, here one whose .hql/config.toml exists and is empty:
cd ~/code/reading-club
hql package install --path ~/hql/tests/packages/hello
Compiling hql-ext-hello v0.1.0
Finished `release` profile [optimized] target(s) in 58.20s
installed hello 0.1.0 (hello) in /home/ada/code/reading-club/.hql/packages/hello
The first build of a package compiles the hql crate and its
dependencies, which takes about a minute; later builds reuse them. The
last line is written once the package has been built, installed and
loaded: a package that builds and cannot be loaded is reported here, with
the reason, and not left for a program to find.
hql package list
hello 0.1.0 (hello) [project]
hql eval 'import hello
hello.greet("Ada")'
"Hello, Ada!"
What is installed¶
A project's .hql/ and the HQL home, ~/.hql unless $HQL_HOME names
another, have the same layout, and a package installs into either:
.hql/
├── config.toml declares the packages, by name
├── lock.toml pins each to a version and a source
├── packages/
│ └── hello/
│ ├── package.toml
│ ├── modules/
│ │ └── hello/mod.hql
│ └── libhql_ext_hello.dylib
└── cache/ sources fetched to build from
install declares the package by name in config.toml, with no version:
[packages]
dependencies = ["hello"]
and pins it in lock.toml, which hql package writes:
[[package]]
name = "hello"
version = "0.1.0"
source = "path"
path = "/home/ada/hql/tests/packages/hello"
A project commits config.toml and lock.toml, and leaves packages/ and
cache/ out of version control. hql package install with no name builds
them again: every declared package at the version its pin names, and a
declared package with no pin at the newest version this hql admits. A run
whose project declares a package that is not installed fails before any
program is checked, and names hql package install.
package.toml is the record of the build:
[package]
name = "hello"
crate = "hql-ext-hello"
version = "0.1.0"
provides = ["hello"]
[source]
kind = "path"
path = "/home/ada/hql/tests/packages/hello"
[build]
hql = "0.7.0"
rustc = "1.98.1 (48a229cea 2026-09-01)"
target = "aarch64-apple-darwin"
library = "libhql_ext_hello.dylib"
built = "2026-11-14T10:02:11Z"
| Table | Records |
|---|---|
[package] |
the package, its crate and version, and the modules it provides |
[source] |
where the source came from, which is what rebuild builds again |
[build] |
the hql and the compiler it was built with, and the library's file name |
The package's directory is self-contained. Removing it, with its declaration
and its pin, is what hql package remove does. The crate it was built from
is not needed again until a rebuild.
Installing for every project¶
--home installs into the HQL home instead:
hql package install --home --path ~/hql/tests/packages/hello
installed hello 0.1.0 (hello) in /home/ada/.hql/packages/hello
The home has its own config.toml and lock.toml, and its packages reach
every run on the machine, with a project or without one. A run looks for a
package in the project first and in the home second, so a project's pinned
version is the one its programs use.
Describing and rebuilding¶
hql package info hello
package: hello
crate: hql-ext-hello 0.1.0
provides: hello
source: path /home/ada/hql/tests/packages/hello
built: 2026-11-14T10:02:11Z against hql 0.7.0 with rustc 1.98.1 (48a229cea 2026-09-01) for aarch64-apple-darwin
library: /home/ada/code/reading-club/.hql/packages/hello/libhql_ext_hello.dylib
After hql is upgraded, an installed package was built for the previous
one and is refused until it is rebuilt
(the version rule).
hql package list says which:
hello 0.1.0 (hello) [project]: built against hql 0.7.0, run `hql package rebuild hello`
hql package rebuild
Without a name, rebuild builds every installed package again, which is
what an upgrade of hql asks for.
hql doctor reports the packages of the environment a program in the
current directory would run in, each as loaded or refused:
package ok hello 0.1.0 (hello)
A package under development¶
Installing copies a build. While a package is being written, a project
names the crate instead, under [packages] paths in its .hql/config.toml:
[packages]
paths = ["../hello"]
A path is read against the project root, the directory holding .hql/. Each
crate listed is built the first time a program runs in the project, and
again whenever its Cargo.toml, a file under src/ or a file under its
module root is newer than the build. The build is kept under the crate's own
target/ directory, and nothing is installed or pinned: a crate on disk is
never pinned.
import hello
Greeting("Ada").length
11
The project of that program is
examples/packages/,
whose .hql/config.toml lists the hello crate. A crate a project lists comes
before an installed package of the same name, so the checkout being edited
is the one that runs. A local crate follows one crate
from its first build to an installed package.
Importing a package for every program¶
A module of a package is imported where it is used, as any module outside
the prelude is. A project whose programs all use one may import it once,
under [modules] import in .hql/config.toml, by the package's name:
[modules]
import = ["hello"]
Every program of the project then starts with the package's modules
imported, and hello.greet("Ada") needs no import line. The setting names a
standard module or a package; it is the one place a package is named. An
entry may also be a from statement, "from hello import greet", and then
greet("Ada") is written without the module's name.
Where a module comes from¶
| Source | Found in | Wins over |
|---|---|---|
| a builtin package | the hql binary |
everything: no package provides a module std or hmd does |
a crate under [packages] paths |
the project's .hql/config.toml |
an installed package of the same name |
| a package installed in the project | .hql/packages/ of the project |
the same package installed in the HQL home |
| a package installed in the HQL home | ~/.hql/packages/ |
a project module of the same name |
| a project module | the module roots (chapter 5) |
hql builtins prints the module graph a program in the current directory
would see, each module with the package and version providing it.
The pages of this chapter¶
| Page | What it covers |
|---|---|
| A local crate | a crate on this machine, step by step: listed under [packages] paths, built on first use, rebuilt after an edit, then installed |
| A shared project | what a project commits, what a fresh clone runs, and how a pin moves |
What is next¶
Chapter 37 is how a package reaches other people: the registry that names packages, and publishing a crate.