Skip to content

A local crate

A local crate is a package's crate in a directory on this machine: one being written, or one checked out to be changed. This page follows one from its first build to an installed package. The crate is hello, the worked example of chapter 34, copied beside a project:

~/code/
├── hello/               the crate: Cargo.toml, src/, modules/
└── reading-club/        the project
    └── .hql/
        └── config.toml

Every command below runs in ~/code/reading-club.

Listing the crate

[packages] paths in the project's .hql/config.toml names the crate's directory:

[packages]
paths = ["../hello"]

A path is read against the project root, the directory holding .hql/, so ../hello is ~/code/hello from any working directory. A listed crate is a package dependency of the project that is never installed, declared under dependencies or pinned in lock.toml.

The first run builds it

No command builds a listed crate. The first program run in the project does, before the program is checked:

hql eval 'import hello
hello.greet("Ada")'
hql: building package `hello` from /home/ada/code/hello
   Compiling hql-ext-hello v0.1.0 (/home/ada/code/hello)
    Finished `release` profile [optimized] target(s) in 1m 01s
"Hello, Ada!"

The build runs cargo in the crate, against the hql that is running, and keeps its result under the crate's own target/hql/hello/: the library, a copy of the module root and a package.toml, laid out as an installed package is. The project's .hql/ gains nothing. The first build compiles the hql crate and its dependencies, which takes about a minute.

The second run finds the build current and starts no compiler:

hql eval 'import hello
hello.greet("Ada")'
"Hello, Ada!"

An edit rebuilds it

A build is current while it is newer than the crate's Cargo.toml, every file under src/ and every file under the module root. Changing one of them makes the next run build again. Here the greeting in src/lib.rs changes from Hello to Good evening:

hql eval 'import hello
hello.greet("Ada")'
hql: building package `hello` from /home/ada/code/hello
   Compiling hql-ext-hello v0.1.0 (/home/ada/code/hello)
    Finished `release` profile [optimized] target(s) in 0.47s
"Good evening, Ada!"

Only the crate itself is compiled again. A change to a contract under modules/, a new declaration or a changed signature, is picked up the same way, and a contract the Rust no longer implements refuses the package with the declaration's name.

A build that fails does not stop hql from starting. The package is refused, and an import of one of its modules reports why:

check error[unknown-name]: no module named `hello`: ...

What the project sees

hql doctor reports the packages a program in the current directory runs with, the listed crate among them:

package  ok      hello 0.1.0 (hello)

hql package list lists installed packages only, and a listed crate is not one, so it prints nothing here.

Installing the crate

install --path copies the build into the project and records it:

hql package install --path ../hello
    Finished `release` profile [optimized] target(s) in 0.12s
installed hello 0.1.0 (hello) in /home/ada/code/reading-club/.hql/packages/hello
hql package list
hello 0.1.0 (hello) [project]

.hql/config.toml now declares the package beside the path:

[packages]
dependencies = ["hello"]
paths = ["../hello"]

and .hql/lock.toml pins it to the directory it was built from:

[[package]]
name = "hello"
version = "0.1.0"
source = "path"
path = "/home/ada/code/hello"

Which one runs

With the crate both listed and installed, the listed crate is the one a program reaches: a run discovers packages from [packages] paths first, the project's .hql/packages/ second and the HQL home's third, and the same package found twice is the first found. Edits to the crate still take effect on the next run.

Removing the paths entry leaves the installed copy, which no edit to the crate changes:

[packages]
dependencies = ["hello"]

The installed package is the build made when it was installed. hql package rebuild hello builds it again from the directory its pin names.

The project has A program runs An edit to the crate
the crate under paths the crate's own build rebuilds on the next run
the crate under paths, and the package installed the crate's own build rebuilds on the next run
the package installed the copy under .hql/packages/ has no effect until hql package rebuild

A path pin names a directory on the machine that wrote it. A shared project is about what that means for a project more than one person runs.