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.
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
mldoes; - 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).