Skip to content

The version rule

A package's library fits exactly one build of hql: the same version of the hql crate, compiled by the same version of the Rust compiler, with the same versions of the crates hql depends on. This page is why, how hql package arranges it, and what is reported when it does not hold.

Rust has no stable layout

When the library returns a Value, it hands the binary an address in memory. The binary reads the bytes at that address as a Value: which variant, where its fields are, how long its string is.

Where each field sits is the type's layout. C fixes layouts by rule, which is why a C library built years ago still loads. Rust does not: the compiler is free to order and pack the fields of a type as it sees fit, and a newer compiler may choose differently. The layout also changes when the type does, when a field is added to Value in a new hql, and when a type inside it changes, in a new version of a crate hql depends on.

So two compilations agree on a layout only when they are compilations of the same source by the same compiler:

Must be equal Because
the version of the hql crate Value, Diagnostic and the context are defined there
the version of rustc the compiler decides the layout
the versions of hql's dependencies Value holds their types: a decimal, a timestamp, a JSON tree

Where they differ, nothing reports an error. The binary reads bytes that mean something else, and the result is a wrong value or a crash somewhere unrelated. The checks of this chapter exist so that the question is answered before any such value is read.

How a build is made to fit

hql package install does not ask the package which hql it wants. It builds the package against the hql that is running:

Fact How it is fixed
the hql version the crate's dependency is pinned to exactly the running version; hql = "0.7" in the crate only says which versions the source accepts
the compiler cargo is run with the compiler version the running hql records
the dependencies a crate without a lock file of its own starts from the one the running hql was built with

The running hql records its own version, its compiler and its target when it is built. hql package info prints them for a package:

built: 2026-11-14T10:02:11Z against hql 0.7.0 with rustc 1.98.1 (48a229cea 2026-09-01) for aarch64-apple-darwin

This is also why a package is built on your machine. A library built elsewhere fits only if that machine used the same hql release and the same compiler, which is the condition a prebuilt library has to meet (chapter 37).

After an upgrade

A new hql is a new build, so the installed libraries no longer fit it. They are refused, and say what to do:

check error[unknown-name]: no module named `hello`: package `hello` was built against hql 0.7.0 with rustc 1.98.1 (48a229cea 2026-09-01); this is hql 0.7.1 with rustc 1.98.1 (48a229cea 2026-09-01): run `hql package rebuild hello`
 --> <expression>:1:1
  |
1 | import hello
  | ^^^^^^^^^^^^
hql package rebuild hello

The rebuild is the install again, from the same source, against the new hql. A program that imports no module of the package is unaffected the whole time: a refused package is absent, and nothing else changes.

Every refusal

The message says The cause What to do
was built against hql … with rustc …; this is hql … hql or its compiler changed since the build hql package rebuild <name>
was built with other versions or features of the crates hql depends on the versions match and a dependency was compiled differently, usually because the crate enables a feature of a crate it shares with hql rebuild; if it persists, remove the feature from the crate
states extension ABI …; this hql loads ABI 1 the library is for another generation of hql install a version of the package for this hql
exports no hql_extension_v1 the crate does not write hql::extension!, or the file is not a package's library add the macro; reinstall
provides … by its record and … by its extension provides in Cargo.toml and the modules in hql::extension! differ make the two lists equal, in the same order
packages … and … both provide …: a module has one provider, so neither is loaded two packages provide one module remove one of them
provides …, which … provides: a module has one provider a package provides a module of std or search rename the package's module
… is declared, and the extension … implements no such function a declaration in a contract has no entry in the module's table add the function, or remove the declaration
requires hql …; this is hql … at install: the crate's hql range excludes the running version a version of the crate for this hql, or a newer hql
needs cargo with rustc …, and none is on PATH at install: no Rust toolchain install Rust with rustup

Each is reported once, at install for the last two and otherwise when a program imports a module the package would have provided. hql package list marks a package whose build no longer fits, and hql doctor lists every package of the environment as loaded or refused, with the reason.