Skip to content

Modules and packages

A program imports modules. Modules are distributed and installed in packages. Some functions in a module are declared in HQL but implemented in Rust, by the package's extension. When you only write programs, you deal with modules. Packages matter when you install code someone else wrote.

d2 diagram

Four units

Term What it is Example
module a named unit of declarations, one mod.hql or one file under a module root; what import names regex, io.net, ml.metrics
package the unit that is distributed and installed: a module root holding one or more modules, with the extension that implements them std, hmd, ml
extension the native code of a package: the implementations of the declarations its modules write without a body std, ml
library the compiled file an installed package's extension is loaded from libhql_ext_ml.dylib

A program never names a package. import regex names the module, and the packages installed where the program runs determine which one provides it. Each module has exactly one provider: a package, or HQL itself when every declaration in the module has a body.

A package carries one extension, with the same name as the package. A declaration such as fn trim(self) : String has no body in HQL. The package's extension implements it, and hql checks that every such declaration has an implementation before any program runs.

Builtin packages

A builtin package ships inside the hql binary: its modules are bundled with it and its extension is compiled into it. There are two.

Package Modules How a program gets them
std, the standard package core, string, seq, math, io, regex, time and the rest the prelude for many, import for the others
hmd, HyperMarkdown hmd, hmd.vault, hmd.search, hmd.search.lexical, hmd.search.semantic import hmd, whose prelude imports the rest

"The standard library" is another name for the std package, and Part IV is its guide. hql builtins names the package beside each module, collections (std 0.7.1, prelude) (chapter 13).

Installable packages

An installable package is installed separately. Its extension is built into a library on your machine, and hql loads the library when it starts. A program then imports the package's modules the same way it imports a standard one:

hql package install ml
import ml

Dataset([[1.0f], [2.0f], [3.0f]], target = [3.0f, 5.0f, 7.0f]).fit_linear()

hql package install puts the package under the project's .hql/packages/ml/, or with --home under ~/.hql/packages/ml/: its modules, the library, and a record of the hql version it was built for. A library loads only into the hql version it was built for, so after an upgrade hql package rebuild builds it again.

The source of an installable package is a Rust crate named hql-ext-<package>: ml is built from the crate hql-ext-ml. A package provides modules under its own name only, ml and ml.metrics, and never takes a builtin package's or a builtin module's name.

A package is

  • official when its crate lives in the hql-extensions repository, as ml does;
  • known when its crate lives elsewhere and the package registry kept in that repository admits it by name;
  • a path package when it is installed from a directory.

hql package install ml installs an official or a known package by its name, hql package install --path <dir> a path package, and hql package list shows what is installed.

Part V is the whole of this subject: how a declaration without a body is implemented (chapter 32), writing a package (chapter 34), how its library is loaded (chapter 35), the commands (chapter 36) and the registry (chapter 37).