Skip to content

The crate

A package is a Cargo crate with three additions: a name that says so, a library type hql can load, and a table naming the package. This is the whole Cargo.toml of hello:

[package]
name = "hql-ext-hello"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
hql = "0.7"

[package.metadata.hql]
package = "hello"
provides = ["hello"]
modules = "modules"

The name

The crate is named hql-ext- and then the package's name. The package name is one lowercase word, and it is also the namespace of the package's modules: hello provides hello and may provide hello.words, and nothing outside that prefix. A package named ml provides ml and ml.metrics.

The library type

crate-type states what the compiler produces from the crate.

Type What it is Why it is listed
cdylib a dynamic library: one file the operating system can load into a running process this is what hql loads
rlib a Rust library other Rust code links against at build time so cargo test can test the crate's own functions

Without cdylib the build leaves no file to load, and hql package install says so. Chapter 35 explains the two kinds.

The hql dependency

The crate depends on hql, the same crate the hql binary is built from, and uses one module of it, hql::ext. hql = "0.7" is a range: every 0.7 release. It says which versions the crate's source is written for.

The version the crate is actually built against is not chosen by this line. hql package install builds the crate against the exact version of the hql that runs the command, and refuses a crate whose range excludes that version before it builds anything (the version rule).

The package table

[package.metadata.hql] is the part Cargo ignores and hql reads.

Key What it states
package the package's name, which is also its extension's name and its directory once installed
provides every module the package provides, in the order they are loaded; a module that imports another comes after it
modules the module root: the directory holding the contracts, relative to the crate

provides is stated twice more, by the files under the module root and by the extension in src/lib.rs. The three must agree, and a package where they differ is refused when it is loaded.

A module's contract is found under the module root by its name, a dot becoming a directory:

Module File
hello modules/hello/mod.hql or modules/hello.hql
hello.words modules/hello/words.hql or modules/hello/words/mod.hql

The package's prelude

The module root may hold prelude.hql, the package's prelude: a file of import statements, which is not a module. hello's is one line:

import hello

While the package is active in a run, every unit of the run imports the modules the prelude lists. The prelude states when a package is active and what a prelude may hold.