33. Packages and extensions¶
A program names modules and nothing else. This chapter follows one
import from the module it names down to the file on disk that runs, and
names each unit on the way. Modules and packages
introduced the four terms; here they are put to work on a package that is
not part of hql.
Four units, one path¶
| Unit | What it is | For import hello |
|---|---|---|
| module | a named file of declarations; what import names |
hello |
| package | what is installed: a module root and the extension implementing it | hello |
| extension | the Rust functions behind a package's declarations | the hello extension |
| library | the compiled file an installed extension is loaded from | libhql_ext_hello.dylib |
The package of this chapter is hello, a small package kept in the hql
repository under
tests/packages/hello/.
Chapter 34 writes it from an empty directory.
An import names a module¶
import hello
hello.greet("Ada")
check error[unknown-name]: no module named `hello` under examples/reading-club/lib
--> <expression>:1:1
|
1 | import hello
| ^^^^^^^^^^^^
In the reading-club vault nothing provides hello: no package does, and the
vault's module root, examples/reading-club/lib, holds no such file. The
import is refused.
The program is the same in a project where a package does provide it:
import hello
hello.greet("Ada")
"Hello, Ada!"
Neither program names a package. Which package provides hello, and
whether one does, is a fact about the environment the program runs in.
A module has one provider¶
When hql starts it gathers the packages of the environment: the two
builtin ones, the crates a project lists, the packages installed in the
project and those installed in the HQL home, in that order
(chapter 36). Each package
states the modules it provides. A module has exactly one provider. Two
packages that provide one module are both refused: the order in which
packages are found picks no winner.
hql builtins names the provider beside each module:
hql --project examples/packages builtins
math (std 0.7.1, prelude)
…
hello (hello 0.1.0, imported where it is used)
greet
String | greet() -> String
pure, barrier
math comes from the package std at the version of hql itself.
hello comes from the package hello at the version of its own crate.
A package is a contract and an extension¶
A package holds two things, as std does
(chapter 32):
- a module root, a directory of contracts, one per module it provides;
- an extension, one Rust function per name those contracts declare.
For a builtin package both are inside the hql binary. For an installed
package the module root is a directory of .hql files and the extension
is a library beside it:
~/.hql/packages/hello/
├── package.toml what was built, from what, against which hql
├── modules/
│ └── hello/mod.hql the contract of module `hello`
└── libhql_ext_hello.dylib the extension, as a library
The library is .dylib on macOS, .so on Linux and .dll on Windows.
What an import does¶
import hello makes the declarations of the module hello visible to the
program, under the name hello. By the time a program is checked the
package is already bound: its contract was read, its library was loaded,
and each declaration was paired with its function. The import is a matter
of names. That is why a call to a function of a package is checked as any
call is:
import hello
hello.greet(3)
check error[type-mismatch]: `greet` needs String, not Int
--> <expression>:3:1
|
3 | hello.greet(3)
| ^^^^^^^^^^^^^^
The refusal comes from the contract, fn greet(name: String) : String.
The Rust function is never called with an Int.
A name of a package used without its import is reported as a missing import, since the environment knows which module declares it:
"hi".shout()
check error[unknown-name]: `shout` is declared in the module `hello`: write `import hello`
--> <expression>:1:1
|
1 | "hi".shout()
| ^^^^^^^^^^^^
What is next¶
Chapter 34 writes the hello package: its
crate, its contract, and the Rust functions behind it.